← Work with SpecDD skills guides

How to derive tests from a spec (specdd-test)

How-To Work with SpecDD skills Intermediate 1091005HOWTO-1091005

HOWTO-1091005Work with SpecDD skillsIntermediate

This guide shows you how to use specdd-test to derive focused tests from active SpecDD specs in a spec-driven development workflow.

Tests should prove the behavior the spec requires. They should not test the wording of the spec, and they should not create a broad harness unless the spec or project conventions call for it.

Short answer

Use specdd-test when an agent should add, update, derive, or assess tests from SpecDD contracts. The agent should identify test authority, derive cases from Must, Scenario, Handles, Returns, Raises, Tasks, and Done when, add the smallest useful checks, run the relevant project test command, and report which spec entries are covered or still unverified.

When to use this guide

Use this guide when:

Steps

1. Choose the behavior to verify

Use a focused prompt:

Derive tests for Itinerary validation.

or:

Assess test coverage for Itinerary validation.

Avoid asking for all tests in a large module unless that is the actual review task.

2. Identify test authority

The agent should confirm that tests can be edited under the nearest relevant spec.

Example:

Owns:
  ./itinerary.js
  ./itinerary.test.js

If the spec requires behavior but does not grant clear authority to edit a test file, the agent should ask before editing. Do not assume any nearby test file is writable just because it has a similar name.

3. Derive cases from spec entries

Useful sources include:

Example:

Must:
  Reject itinerary items without a place name.
  Keep existing itinerary items unchanged when validation fails.

Done when:
  Missing-place behavior is covered by a check.

Possible tests:

4. Prefer small behavior tests

Write tests that prove observable behavior.

Good:

Rejects an itinerary item without a place name and leaves the itinerary unchanged.

Weak:

Checks that the validation function contains a condition named place.

The spec describes behavior and contracts. Tests should verify behavior and contracts, not implementation wording.

5. Cover forbidden regressions when needed

Some Must not and Forbids rules deserve checks when they can regress silently.

Example:

Must not:
  Change destination search behavior.

If itinerary validation previously broke destination search, add a regression check or include the existing destination checks in verification. If the forbidden behavior is better covered by review or architecture linting, report that.

6. Run the relevant test command

Use the project command named in shared conventions or local setup. The test command might be a focused unit test, a package-level test, or a documentation check.

If tests cannot run, the report should explain why and list what remains unverified.

7. Report coverage and gaps

A good specdd-test report includes:

Example

Spec:

Scenario: missing place name
  Given the place name is empty
  When the person adds the itinerary item
  Then validation fails
  And no itinerary item is stored

Derived checks:

1. Empty place name returns a validation failure.
2. The itinerary item count stays unchanged.
3. Existing itinerary items are still present after the failed add.

These tests prove the scenario rather than mirroring its words.

Common mistakes

How to verify the result

The testing workflow worked when:

← Work with SpecDD skills guides