spec-kit

spec-kit is an interactive CLI scaffolding tool that generates production-ready test automation projects in seconds. Pick your framework, answer a few prompts, and get a fully wired project — page objects, step definitions, feature files, CI pipelines, Docker, reporting, and AI agent workflows — all ready to run.

Quick Start

No installation needed. Run directly with npx:

npx @aigenerated/spec-kit init

You will be walked through a series of prompts. A complete project is generated in the current directory when you are done.

Supported Frameworks

| Framework | Language | Notes | |---|---|---| | Playwright BDD | TypeScript / JavaScript | BDD via playwright-bdd + Cucumber | | Playwright POM | TypeScript | Pure Page Object Model — test() blocks, no BDD layer | | Cypress BDD | TypeScript / JavaScript | BDD via @badeball/cypress-cucumber-preprocessor | | Python API Testing | Python | OpenAPI / Schemathesis driven, pytest-bdd | | Manual Spec Driven | — | AI-agent-driven spec → feature → CSV test-case workflow |

What Gets Generated

Playwright BDD / Cypress BDD

Every BDD scaffold follows a clean features/ → scenarios/ → pages/ separation:

my-project/
├── features/          # Gherkin .feature files (plain English)
├── scenarios/         # Step definitions (Given / When / Then)
├── pages/             # Page Object Models
├── fixtures/          # Shared test fixtures & world state
├── utils/             # Assertions, helpers, random data utils
├── data/              # Static test data (JSON)
├── envs/              # .env files per environment (dev/staging/prod)
├── ci/                # GitHub Actions workflow (optional)
├── docker/            # Dockerfile + compose (optional)
└── playwright.config  # or cypress.config

Sample scenarios for Login, Checkout, and Search flows are included out of the box so you can run tests immediately after scaffolding.

Playwright POM

A TypeScript Page Object Model project with AI agents that drive the entire workflow:

my-project/
├── tests/             # Playwright .spec.ts files
├── pages/             # Page Object Models (extend BasePage)
├── fixtures/          # Auth fixtures
├── utils/             # Helpers & logger
├── test-data/         # JSON test data
├── config/            # Env config reader
├── constants/         # Shared constants
├── specs/             # QA spec docs (AI-generated)
├── test-suites/       # Per-module test_cases.csv + suite files
│   ├── <module>/
│   │   ├── test_cases.csv
│   │   ├── <module>-smoke.md
│   │   └── <module>-regression.md
│   ├── p1-critical.md
│   ├── smoke-suite.md
│   └── regression-suite.md
├── reports/           # Test run reports
├── playwright.config.ts
└── .env.example

Comes with 5 AI agents (.github/agents/) that automate the full spec → page object → test → CSV workflow. A .vscode/mcp.json is also pre-configured with the Playwright MCP server so agents can browse and inspect live pages out of the box.

Manual Spec Driven

A documentation-only project with 7 AI agents that handle the complete manual QA workflow — no code required:

my-project/
├── specs/             # QA spec docs per module
├── features/          # Gherkin .feature files
├── scenarios/         # Step-by-step manual test instructions
├── test-suites/       # Per-module test_cases.csv + cross-module suites
└── reports/           # Test execution results

Interactive Prompts

All frameworks

| Prompt | Options | |---|---| | Project name | free text | | Project description | free text | | Author | free text | | Framework | Playwright BDD, Playwright POM, Cypress BDD, Python API Testing, Manual Spec Driven |

Playwright BDD / Cypress BDD

| Prompt | Options | |---|---| | Language | TypeScript, JavaScript | | Browser (Playwright BDD) | Chromium, Firefox, WebKit, All | | Reporting (Playwright BDD) | HTML, Allure, Both | | Reporting (Cypress BDD) | Mochawesome, Allure, Both | | Include GitHub Actions CI? | Yes / No | | Include Docker setup? | Yes / No | | Include parallel execution config? | Yes / No | | Include custom Cypress commands? (Cypress BDD only) | Yes / No |

Playwright POM

| Prompt | Options | |---|---| | Browser | Chromium, Firefox, WebKit, All | | Include GitHub Actions CI? | Yes / No | | Include Docker setup? | Yes / No |

Python API Testing

| Prompt | Options | |---|---| | OpenAPI spec format | OpenAPI 3.x, Swagger 2.0 | | Provide a spec file path or URL? | Yes / No | | HTTP client | requests, httpx, both | | Spec-driven strategy | Schemathesis (auto), Custom pytest + openapi-core, Both | | Include auth fixtures? | Bearer / API Key / OAuth2 | | Include environment config (.env)? | Yes / No | | Reporting | pytest-html, Allure, Both | | Include GitHub Actions CI? | Yes / No | | Include Docker setup? | Yes / No |

Framework Details

Playwright BDD

Uses playwright-bdd to run Cucumber .feature files natively inside the Playwright test runner. Generates:

• BasePage + LoginPage Page Object Models
• world.js/ts fixture wiring page objects into every step
• hooks.js/ts with Before/After screenshot-on-failure
• assertions and helpers utility modules
• Sample login, checkout, and search feature + step files

Playwright POM

A clean TypeScript Page Object Model setup — test() blocks, no Gherkin. Ships with 5 VS Code AI agents in .github/agents/:

| Agent | Role | |---|---| | playwright-pom-orchestrator | Main agent — give it a URL + creds + requirement and it drives the full flow | | spec-writer | Generates specs/<module>/QA-<feature>-spec.md | | page-object-writer | Generates pages/<module>/<Feature>Page.ts extending BasePage | | test-script-writer | Generates tests/<module>/<feature>.spec.ts | | test-case-csv-writer | Generates test-suites/<module>/test_cases.csv from spec + test files |

The orchestrator runs all 5 steps end-to-end from a single prompt. The csv-test-case-generator skill (.github/skills/) is invoked automatically during CSV generation.

Cypress BDD

Uses @badeball/cypress-cucumber-preprocessor with esbuild bundling. Generates custom commands, page objects, and the same BDD feature/scenario structure as the Playwright BDD variant.

Python API Testing

Generates a spec-first API test suite powered by your OpenAPI/Swagger document:

• Schemathesis strategy: contract-tests every endpoint automatically from the spec
• Custom pytest strategy: manually authored tests with openapi-core request/response validation
• Wrapped HTTP client (requests or httpx) with auth support (Bearer, API Key, OAuth2)
• pytest-bdd scenarios for functional end-to-end flows

Manual Spec Driven

A documentation-only project with 7 VS Code AI agents that handle the full manual QA pipeline — no programming required:

| Agent | Role | |---|---| | manual-spec-orchestrator | Main agent — drives the full 6-step workflow | | spec-writer | Creates specs/<module>/QA_SPEC_<feature>.md | | feature-writer | Writes Gherkin .feature files from the spec | | scenarios-writer | Writes step-by-step manual test instructions | | test-case-tracker | Generates test-suites/<module>/test_cases.csv via the CSV skill | | test-case-reviewer | Validates coverage and fixes gaps automatically | | test-suite-query | Filters test cases by tag, priority, status, or module |

Requirements

• Node.js >= 16.0.0
• npm >= 7.0.0
• Python >= 3.8 (Python API projects only)

License

MIT © spec-kit contributors