Skooma Ruby Library

To use Skooma in a Rails application with multiple OpenAPI documents, include the Skooma::RSpec module in your RSpec configuration. You can provide a path_prefix option if your API is mounted under a specific path. Each inclusion should be associated with a unique RSpec metadata filter (e.g., :bar_api) so you can target specific APIs in your tests.

Example configuration in rails_helper.rb:

RSpec.configure do |config|
  config.include Skooma::RSpec[bar_openapi, path_prefix: "/bar"], :bar_api
  config.include Skooma::RSpec[baz_openapi, path_prefix: "/baz"], :baz_api
end

If you are working with the repository source, follow these steps to prepare your environment:

1. Run bin/setup to install all necessary dependencies.
2. Use bin/console to open an interactive prompt for experimenting with the library.
3. Run rake spec to execute the test suite.

To install the Skooma gem onto your local machine for development or testing, use the following command:

bundle exec rake install

To run the provided example application, use the following commands:

bundle install
bundle exec rspec

To use Skooma in your Ruby application, add the gem to your Gemfile using bundler:

$ bundle add skooma

If you are not using bundler, you can install it directly via gem:

$ gem install skooma

To avoid manually adding API metadata filters (like :bar_api) to every spec file, use RSpec's config.define_derived_metadata. This allows you to automatically assign metadata based on the file path of the spec.

RSpec.configure do |config|
  config.define_derived_metadata(file_path: %r{/spec/requests/bar}) do |metadata|
    metadata[:bar_api] = true
  end
end

To prevent coverage data collisions in parallel CI environments, you can pass a custom object to the coverage_store: option. The object must implement the following interface:

• load_data
• save_data
• clear

This allows you to write coverage data to separate files (e.g., one per parallel runner) and merge them in a subsequent step.

To use Skooma's OpenAPI schema validation matchers in your RSpec tests, include Skooma::RSpec in your RSpec configuration. You must provide the path to your OpenAPI specification file (e.g., openapi.yml) and can pass additional parameters. It is common practice to include it for the :request type so that schema validation is available in request specs.

When initialized, Skooma also sets up an at_exit hook to automatically generate a coverage report after the test suite finishes.

RSpec.configure do |config|
  # ...
  config.include Skooma::RSpec[Rails.root.join("docs", "openapi.yml")], type: :request
end

Use the conform_schema(status_code) matcher to validate that a request/response cycle matches the schema defined for a specific HTTP status code in your OpenAPI document.

# spec/requests/feed_spec.rb

require "rails_helper"

describe "/animals/:animal_id/feed" do  
  let(:animal) { create(:animal, :unicorn) }
  
  describe "POST" do
    subject { post "/animals/#{animal.id}/feed", body:, as: :json }
    
    let(:body) { {food: "apple", quantity: 3} }

    it { is_expected.to conform_schema(200) }

    context "with wrong food type" do
      let(:body) { {food: "wood", quantity: 1} }
    
      it { is_expected.to conform_schema(422) }
    end
  end
end

Use the skooma_openapi_schema helper and the be_valid_document matcher to ensure your OpenAPI specification is valid.

# spec/openapi_spec.rb

require "rails_helper"

describe "OpenAPI document", type: :request do
  subject(:schema) { skooma_openapi_schema }

  it { is_expected.to be_valid_document }
end