Plan Tests

Quick Reference

HARD-GATE

CHECKPOINT: Test Design Review

1. Present: Show the failing spec(s) written
2. Ask:
   - Does this test cover the right behavior?
   - Is the boundary correct (request vs service vs model)?
   - Are the most important edge cases represented?
   - Is the failure reason correct (feature missing, not setup error)?
3. Confirm: Only proceed to implementation once test design is approved.

Core Process

Start at the highest-value boundary that proves the behavior with the least unnecessary setup.

Steps

1. Name the behavior: State the user-visible outcome or invariant to prove.
2. Locate the boundary: Decide where the behavior is observed first — HTTP request, service entry point, model rule, job execution, engine integration, or external adapter. Use the Quick Reference table to map the change type to the right spec type.
3. Write one failing example: Keep it minimal; one example is enough to open the gate. List additional cases as follow-up coverage.
4. Suggest the path: Name the likely spec path using normal Rails conventions (e.g. spec/requests/..., spec/services/..., spec/jobs/..., spec/models/...).
5. Run and validate: Confirm the failure is because the behavior is missing, not because the setup is broken.
6. Hand off: Continue with the skill that fits the slice — [write-tests](skills/write-tests/SKILL.md) for general spec writing, [test-service](skills/test-service/SKILL.md) for service-layer coverage, or [test-engine](skills/test-engine/SKILL.md) for engine integration.

Examples

Good: New JSON Endpoint

# Behavior: POST /orders validates params and returns 201 with JSON payload
# First slice: request spec
# Suggested path: spec/requests/orders/create_spec.rb

RSpec.describe "POST /orders", type: :request do
  let(:user) { create(:user) }
  let(:valid_params) { { order: { product_id: create(:product).id, quantity: 1 } } }

  before { sign_in user }

  it "creates an order and returns 201" do
    post orders_path, params: valid_params, as: :json
    expect(response).to have_http_status(:created)
    expect(response.parsed_body["id"]).to be_present
  end
end

Good: New Orchestration Service

# Behavior: Orders::CreateOrder validates inventory, persists, and enqueues follow-up work
# First slice: service spec
# Suggested path: spec/services/orders/create_order_spec.rb

RSpec.describe Orders::CreateOrder do
  subject(:result) { described_class.call(user: user, product: product, quantity: 1) }

  let(:user)    { create(:user) }
  let(:product) { create(:product, stock: 5) }

  it "returns a successful result with the new order" do
    expect(result).to be_success
    expect(result.order).to be_persisted
  end
end

Pitfalls

Extended Resources (Progressive Disclosure)

Load these files only when their specific content is needed:

• [assets/firstslicetemplate.md](assets/firstslicetemplate.md) — Use when documenting the test plan; provides a structured template for behavior, boundary decision, opening gate spec, and follow-up coverage

Output Style

When completing test planning, produce a brief structured summary and populate the full plan using [assets/firstslicetemplate.md](assets/firstslicetemplate.md). The summary must cover:

• Behavior — user-visible outcome being proved
• First Slice — spec type, file path, and boundary rationale
• Opening Gate — expected RED failure message and confirmation that failure reason is "feature missing, not setup error"
• Follow-up Coverage — bulleted list of additional cases deferred from the initial gate
• Design Checkpoint — confirmation that behavior, boundary, edge cases, and failure reason are all validated