How to test structs and actions with RSpec
Say you have a Voyage struct and a LogCrossing action, and you want specs that read like the outcome they check.
actionable/rspec needs RSpec, and the site’s bundle has none. So most of this page is plain code. The matcher and the result builders are tried on a small object that extends the same modules.
1. Load the helpers
Section titled “1. Load the helpers”require 'actionable/rspec'If RSpec is defined, this pulls the matcher and the stub helpers into every example group. Coverage is a separate require, actionable/rspec/coverage.
2. Test a struct
Section titled “2. Test a struct”A struct spec is ordinary RSpec. Check validity and the messages, and leave inspect alone.
RSpec.describe Voyage do it 'needs a route' do voyage = described_class.new(route: '')
expect(voyage).not_to be_valid expect(voyage.errors[:route]).to eq(['is required']) end
it 'reads a date from a string' do expect(described_class.new(route: 'Quay-Isle', departs_on: '2026-07-03').departs_on).to eq(Date.new(2026, 7, 3)) endend3. Test the outcome in one line
Section titled “3. Test the outcome in one line”perform_actionable calls .run on the class and inspects the result. On its own it expects success, and the chains name every other outcome. Make the class the subject: RSpec’s default subject is an instance, which has no .run.
RSpec.describe LogCrossing do subject { described_class }
it { is_expected.to perform_actionable(route: 'Quay-Isle') } it { is_expected.to perform_actionable(route: 'Quay-Isle', logged: true).and_skip(:already_logged) } it { is_expected.to perform_actionable.and_fail(:missing_route, /needs a route/) }endIf the action declares its codes, asking for one it doesn’t declare raises ArgumentError inside the spec. That is on purpose, because such a spec would assert an outcome the action can never produce. To show it, we ran the matcher outside RSpec:
require 'actionable/rspec'
class LogCrossing < Actionable::Action input do optional :route, :string optional :logged, :boolean end
fails :missing_route, 'a crossing needs a route' skips :already_logged
step :check
private
def check fail!(:missing_route) if input.route.nil? skip!(:already_logged) if input.logged succeed endend
spec = Object.new.extend(Actionable::RSpec::Matchers, Actionable::RSpec::Stubs)
spec.perform_actionable(route: 'Quay-Isle').matches?(LogCrossing) # => truespec.perform_actionable.and_fail(:missing_route, /needs a route/).matches?(LogCrossing) # => truespec.perform_actionable.and_skip(:already_logged).matches?(LogCrossing) # => falsespec.perform_actionable(route: 'Quay-Isle', logged: true).and_skip(:already_logged).matches?(LogCrossing) # => true
begin spec.perform_actionable.and_fail(:missing_rout).matches?(LogCrossing)rescue ArgumentError => e e.message.start_with?('LogCrossing does not declare :missing_rout') # => trueend4. Build a result without running anything
Section titled “4. Build a result without running anything”The builders return a real result, handy when you test code that only consumes one.
failure = spec.actionable_failure_result(code: :missing_route, errors: { route: 'is required' })failure.code # => :missing_routefailure.errors.to_h # => {route: ["is required"]}spec.actionable_skip_result(code: :already_logged).skipped? # => truespec.actionable_success_result(output: { leg: 4 }).output # => {leg: 4}5. Stub a collaborator action
Section titled “5. Stub a collaborator action”When one action calls another, swap the collaborator out with allow_actionable_failure, allow_actionable_success or allow_actionable_skip. Each builds a real result and stubs run through rspec-mocks. The stub_actionable_* forms also expect the call to happen.
RSpec.describe Embark do it 'stops when the deck is full' do allow_actionable_failure(ReserveBerth, code: :deck_full)
expect(Embark).to perform_actionable(callsign: 'x').and_fail(:deck_full) endendA stubbed code that the collaborator doesn’t declare raises, exactly like the matcher. And when the collaborator has an output schema, the stubbed output goes through it.
See also
Section titled “See also”FieldStruct, Actionable and their adapters are open source under the MIT license.