Specflow provides a framework for building workflows driven by specification files, targeted at AI-assisted software development. Developers write specs in Markdown files outlining requirements and tests, and the tool parses them to trigger handlers that can generate code implementations or execute test cases. With just 11 GitHub stars, this JavaScript project from jmerelnyc remains in active development under an MIT license, requiring Node.js version 16.0.0 or higher. It fills a niche for structured, event-based automation where AI tools handle repetitive tasks based on human-written specs.

The framework separates spec parsing from execution, allowing users to define custom logic for events like processing requirements or running tests. This setup suits scenarios where AI APIs—such as code generators—need orchestration around natural language descriptions in docs.

Core features

Specflow centers on two main classes: Workflow and SpecRunner.

The Workflow class takes options including a name for identification, a spec path to a Markdown file, a parallel boolean (defaults to false for sequential steps), and a timeout in milliseconds (defaults to 30000). Once instantiated, users register handlers with on(event, handler) for events such as requirement, test, validation, complete, or error. Execution starts via run(), which returns an object with steps count and duration in ms. Additional methods include pause() and resume() for interrupting workflows.

SpecRunner handles parsing: create an instance with a spec file path, call parse(), and get an object containing requirements, tests, and metadata arrays or objects. A standalone parseSpec(filepath) function offers the same without instantiation.

Events fire sequentially or in parallel based on config, enabling integration with external AI services. For instance, a requirement handler might call an AI to produce code from a spec section's title and description. The tool reports 87% test coverage, and builds pass consistently.

Getting it running

Installation uses npm:

npm install specflow

Basic usage follows this pattern, pulled directly from the project's example:

const { Workflow, SpecRunner } = require('specflow');

// define a spec-driven workflow
const workflow = new Workflow({
  name: 'feature-implementation',
  spec: './specs/user-auth.md'
});

// register handlers for different spec sections
workflow.on('requirement', async (req) => {
  console.log(`processing: ${req.title}`);
  return await generateImplementation(req);
});

workflow.on('test', async (test) => {
  return await runTestCase(test);
});

// execute the workflow
const result = await workflow.run();
console.log(`completed ${result.steps} steps in ${result.duration}ms`);

Here, ./specs/user-auth.md holds the spec in Markdown format, with sections like requirements and tests that the parser identifies—likely via headings or fenced blocks, though exact Markdown conventions depend on implementation details in the code. The generateImplementation and runTestCase calls represent user-defined async functions, such as querying an AI model like GPT for code or Jest for tests.

To parse a spec standalone:

const { parseSpec } = require('specflow');
const spec = parseSpec('./docs/feature.md');

This returns structured data ready for custom processing. Run version 1.0.0 on Node >=16.0.0; no additional dependencies appear in the badges.

For development, clone the repo at https://github.com/jmerelnyc/specflow, then npm test to verify coverage stays at or above 87%.

API details

The API emphasizes extensibility. Workflow(options) initializes with those four options, exposing methods for event handling and control flow. Handlers receive payloads like req (with title property) or test objects, returning promises for async ops.

Events cover the lifecycle:

  • requirement: Each spec requirement triggers this.
  • test: Per test case.
  • validation: For checks post-generation.
  • complete: End-of-run summary.
  • error: Failure capture.

SpecRunner suits one-off parsing, outputting flat structures for requirements and tests. This modularity lets users chain it with other tools, like feeding parsed specs into AI prompts.

Contributing involves opening issues for major changes, running npm test, and preserving coverage—no drop allowed.

Who this is for

Specflow targets developers building AI-assisted pipelines, particularly those practicing spec-driven development (SDD) or behavior-driven development (BDD) with automation. If your workflow involves Markdown docs for features—like user auth specs—and you want to automate implementation via AI or tests via runners, this provides the glue.

Use cases include prototyping features: write a spec, hook an AI handler to draft code from requirements, then validate with tests. Teams iterating on AI-generated code benefit, as pause/resume aids debugging long runs. Parallel mode speeds multi-requirement specs.

Solo devs or small projects experimenting with AI coding agents find it lightweight. It's not for massive monorepos, given its early stage and low adoption (11 stars).

How it compares

Specflow overlaps with BDD tools like Cucumber.js, which also parse Gherkin files for tests, but focuses on AI workflows rather than pure testing. Unlike Playwright or Jest, it doesn't run tests itself—handlers do—so pair it with those.

For spec parsing, it resembles lightweight Markdown processors, but event-driven execution sets it apart from static parsers like remark. No direct competitors emerge in AI-dev orchestration; alternatives might involve custom scripts with LangChain.js for AI chaining, heavier than specflow's 1.0.0 npm package.

It's lighter than full CI/CD like GitHub Actions for specs, but narrower—spec-focused only.

Specflow works best in Node.js environments for early AI-dev automation, though its small footprint and youth mean it's not yet battle-tested at scale. Source at https://github.com/jmerelnyc/specflow.

View on GitHub →