RSpec::Parameterized

For users of version 0.x, the transition to v1.0 is straightforward. The implementation has been split into core and syntax-specific gems. Most users can simply run bundle update to upgrade.

Note that the original rspec-parameterized gem is now a wrapper. If you want to reduce dependencies, you can choose to install only the core gem instead of the full package.

The rspec-parameterized gem includes rspec-parameterized-table_syntax, which depends on native extensions. If your test suite does not require the TableSyntax feature, you can reduce your dependency footprint by replacing rspec-parameterized with rspec-parameterized-core in your Gemfile.

# Before
gem "rspec-parameterized"

# After
gem "rspec-parameterized-core"

To use the library, require it in your spec_helper.rb file.

require 'rspec_parameterized'

Add rspec-parameterized to your test group in your Gemfile. Requires Ruby 2.6.0 or later.

group :test do
  gem "rspec-parameterized", ">= 1.0.0"
end

For highly explicit or complex test data, use a where block that returns a hash where keys are strings (representing the test case name) and values are hashes of the parameters.

describe "Verbose syntax" do
  where do
    {
      "positive integers" => { a: 1, b: 2, answer: 3 },
      "negative_integers" => { a: -1, b: -2, answer: -3 },
      "mixed_integers" => { a: 3, b: -3, answer: 0 }
    }
  end

  with_them do
    it "should do additions" do
      expect(a + b).to eq answer
    end
  end
end

When passing a hash to where where values are arrays, the library generates a test case for every possible combination of the provided values (Cartesian product).

describe "Hash arguments" do
  where(a: [1, 3], b: [5, 7, 9], c: [2, 4])

  with_them do
    it "sums is even" do
      expect(a + b + c).to be_even
    end
  end
end

Define parameters using the where block with an array of arrays. Each inner array represents a set of values mapped to the symbols provided to where. Inside the with_them block, these values are available as local variables.

describe "plus" do
  where(:a, :b, :answer) do
    [
      [1 , 2 , 3],
      [5 , 8 , 13],
      [0 , 0 , 0]
    ]
  end

  with_them do
    it "should do additions" do
      expect(a + b).to eq answer
    end
  end
end

To interact with RSpec let or let! variables within a where block:

• Use ref(:symbol) to reference a variable defined in the outer scope.
• Use lazy { ... } when you want the variable to be evaluated after the where block (e.g., to use variables defined inside a with_them block).

describe "lazy and ref types" do
  let(:one) { 1 }
  let(:four) { 4 }

  where(:a, :b, :result) do
    [[ref(:one), ref(:four), lazy { two + three }]]
  end

  with_them do
    context "use let after where block" do
      let(:two) { 2 }
      let(:three) { 3 }

      it 'should equal 5' do
        expect(a + b).to eq result
      end
    end
  end
end

For a syntax similar to Groovy Spock, include using RSpec::Parameterized::TableSyntax within your describe block. This allows you to define parameters using the pipe (|) delimiter.

describe "plus" do
  using RSpec::Parameterized::TableSyntax

  where(:a, :b, :answer) do
    1 | 2 | 3
    5 | 8 | 13
    0 | 0 | 0
  end

  with_them do
    it "should do additions" do
      expect(a + b).to eq answer
    end
  end
end

Inside a with_them block, you can access the current parameter set using the params method (returns a hash) or all_params method.

describe "plus" do
  where(:a, :b, :answer) do
    [[1, 2, 3]]
  end

  with_them do
    it "uses params hash" do
      expect("#{params[:a]} + #{params[:b]} == #{params[:answer]}").to eq "1 + 2 == 3"
    end
  end
end

You can override the default test case names in two ways:

1. Regular Syntax: Include a :case_name symbol as the first argument to where and provide the name in your data array.
2. Hash Syntax: Provide a :case_names lambda to the where method. This lambda receives the parameters and should return a string for the name.

# Regular syntax with :case_name
describe "Custom names" do
  where(:case_name, :a, :b, :answer) do
    [["positive integers", 6, 2, 8]]
  end

  with_them do
    it "should do additions" do
      expect(a + b).to eq answer
    end
  end
end

# Hash syntax with :case_names lambda
describe "Custom naming for hash" do
  where(case_names: ->(a, b, c){ "#{a} + #{b} + #{c}"}, a: [1], b: [5], c: [2])

  with_them do
    it "sum is even" do
      expect(a + b + c).to be_even
    end
  end
end