integration-test-gen

<!-- Auto-generated by Clef Bind — claude-skills target --> <!-- Concept: IntegrationTestGen --> <!-- Do not edit manually; regenerate with: clef interface generate -->

IntegrationTestGen

Generate a ProcessSpec integration test for $ARGUMENTS.

When to use: Use when you need to exercise an external-API concept against the real API. Generates a ProcessSpec integration test from fixture chains AND scenario invariants in the concept spec.

Design Principles

• Spec-Driven Test Generation: The concept spec is the single source of truth — fixtures define happy and error paths; scenario invariants define end-to-end behavioral claims. Regeneration is always safe.
• Settlement Mode → Step Primitive: Synchronous scenarios emit a plain external-call step. async-eventually scenarios emit pollUntil with a CheckVerification predicate. async-with-anchor scenarios emit waitForCompletion pinned to the completion of the preceding action.
• Binding over Hardcoding: $fixture.field references must resolve to step output bindings — never copy values between fixtures. The ProcessSpec runtime substitutes at execution time.

Step-by-Step Process

Step 1: Register Generator

Self-register with PluginRegistry so KindSystem can track (ConceptSpec + IngestManifest) → ProcessSpec transformations.

Examples: Register the integration test generator

const result = await integrationTestGenHandler.register({}, storage);

Step 2: Preview Test Steps

Parse the concept spec and compute the ordered step list without creating a ProcessSpec or storing a generation record . Returns the steps as a JSON array so the caller can inspect the generated plan before committing to a full generate call .

Arguments: $0 conceptSpec (string), $1 source (string)

Step 3: Generate ProcessSpec Integration Test

Parse the concept spec string to extract all fixtures . Walk the after chains among fixtures to build a dependency graph , then perform a topological sort to produce ordered steps . Emit a ProcessSpec JSON document where each fixture becomes a step of type external-call . Step inputs come from the fixture s field values ; $ fixture . field output references become step output bindings resolved at run time . Each step s expected variant annotation ( ok , error , notfound , etc . ) is emitted as a CheckVerification assertion . Stores the resulting generation record and returns the ProcessSpec JSON and total step count .

Arguments: $0 conceptSpec (string), $1 ingestManifest (string), $2 source (string)

Checklist:

• Concept spec parses without error?
• No after cycles among fixtures?
• Every $fixture.field reference resolves to a known prior fixture?
• Ingest manifest JSON parses?
• Each fixture emits exactly one step?
• Scenario invariants emit a step sequence with the correct settlement mode?
• settlement: async-eventually scenarios become pollUntil steps?
• settlement: async-with-anchor scenarios become waitForCompletion steps?
• Expected variants emitted as CheckVerification assertions?

Examples: Generate a ProcessSpec from a concept spec + ingest manifest

clef generate integration-test --concept-spec ./specs/app/charge.concept --ingest-manifest ./ingest.json --source payments

Step 4: Run the Generated Test

Execute the generated ProcessSpec by invoking each step in dependency order . Each step dispatches an external call to the handler registered for the concept action . CheckVerification evaluates the actual response variant against the expected variant declared in the fixture annotation . Tallies pass and fail counts across all steps and returns a results summary JSON alongside the pass / fail totals .

Arguments: $0 processSpec (string)

Quick Reference

Flag	Type	Purpose
--concept-spec	path	Path to the .concept file
--ingest-manifest	path	Path to the ingest manifest JSON
--source	string	Source name under which to run steps

Output: ProcessSpec JSON on stdout (or to --output path). Run with clef generate integration-test run --process-spec <file>.

Validation

Generate a ProcessSpec from a concept spec + manifest:

clef generate integration-test --concept-spec ./specs/app/charge.concept --ingest-manifest ./ingest.json --source payments

Run the generated ProcessSpec:

clef generate integration-test run --process-spec ./out/charge.process.json

Related Skills

Skill	When to Use
/create-external-concept-impl	Generate the external concept implementation the integration test exercises.