tdd-loop

Use this workflow when implementing any Hanami 2.x feature using Test-Driven Development.

Core principle: Write a failing test → verify it fails for the right reason → implement → verify it passes → review.

Quick Reference

Core Process

1. [Plan Tests] — Load skill: test-planning-process (from ruby-core-skills)

   • Decide: request spec, action unit spec, relation spec, or repository spec?
   • Document the test plan: what behavior, what inputs, what assertions
   • Handoff condition: Test plan is written and reviewed

2. [Write Failing Test] — Load skill: write-request-spec or write-action-spec

   • Write the test that describes the desired behavior
   • Run the test: bundle exec rspec spec/requests/... (request spec) or bundle exec rspec spec/actions/... (action spec)
   • Confirm it FAILS and fails for the right reason (feature missing, not a typo)
   • HARD-GATE (TDD — tdd-process (from ruby-core-skills)): Do not proceed until the test fails for the right reason.
   • Handoff condition: Failing test committed or saved

3. [Implement] — Write minimal code to make the test pass

   • Start with the simplest implementation that satisfies the test
   • Run bundle exec rspec after each change
   • Refactor only after the test passes
   • Handoff condition: Test passes

4. [Review] — Load skill: review-code

   • Check for Action responsibility violations
   • Check for DI usage
   • Check for query encapsulation
   • Check for test coverage
   • Handoff condition: No critical violations

Minimal Example

Failing request spec (spec/requests/posts/create_spec.rb):

RSpec.describe "POST /posts", type: :request do
  it "creates a post and redirects" do
    post "/posts", params: { post: { title: "Hello" } }
    expect(last_response.status).to eq(302)
  end
end

Run: bundle exec rspec spec/requests/posts/create_spec.rb → expect a failure such as ActionNotFound or 404.

Minimal implementation — generate the action and register the route:

# app/actions/posts/create.rb
module MyApp
  module Actions
    module Posts
      class Create < MyApp::Action
        def handle(request, response)
          response.redirect_to "/posts"
        end
      end
    end
  end
end

Run: bundle exec rspec spec/requests/posts/create_spec.rb → expect green.

Common Mistakes & Red Flags