Skip to main content

​
Overview

pdd test operates in four modes depending on its arguments:
  1. Agentic UI test generation — Pass a GitHub issue URL to generate comprehensive UI, contract, and accessibility tests via an 18-step workflow.
  2. Manual unit test generation — Pass a prompt file and code file to generate or enhance unit tests.
  3. Story generation — Pass one or more .prompt files to generate a user_stories/story__*.md file.
  4. Story metadata linking — Pass a story__*.md file to update prompt links in existing story metadata.

​
Usage

pdd [GLOBAL OPTIONS] test GITHUB_ISSUE_URL

​
Options

​
--manual
flag
Use manual mode with explicit file arguments. Required when passing a URL but wanting unit test generation rather than agentic UI testing.
​
--output
string
Where to save the generated test file. Defaults to test_<basename>.<language_extension>. If a file with that name already exists, a numbered suffix is added (e.g., test_calculator_1.py). Or set PDD_TEST_OUTPUT_PATH as an environment variable for a persistent default.
​
--language
string
Programming language for the generated tests. Defaults to the language inferred from the prompt filename.
​
--coverage-report
string
Path to an existing coverage report file. When provided, generates additional tests targeting uncovered lines and branches.
​
--existing-tests
string
Path(s) to existing unit test files (repeatable). Required when using --coverage-report. Multiple paths can be provided.
​
--target-coverage
float
default:"90.0"
Desired code coverage percentage to achieve.
​
--merge
flag
When used with --existing-tests, merges new tests into the existing test file instead of creating a separate file.

​
Agentic mode options

​
--timeout-adder
float
default:"0.0"
Additional seconds to add to each step’s timeout.
​
--no-github-state
flag
Disable GitHub issue comment-based state persistence. By default, state is stored in a hidden comment for cross-machine resume.

​
Agentic UI test generation (18-step workflow)

When passed a GitHub issue URL, test runs a comprehensive agentic workflow to generate UI, contract, and accessibility tests.
1

Duplicate check

Search for existing issues describing the same test requirements. If found, merge content and close the duplicate.
2

Documentation check

Review repo documentation and codebase to understand what needs to be tested. Identifies OpenAPI/Swagger specs if present.
3

Analyze and clarify

Determine if enough information exists to create tests. Posts a comment requesting clarification if needed.
4

Detect frontend

Identify the test type: web UI, CLI, desktop app, or API. Determines the appropriate testing framework.
5

Create test plan

Design a comprehensive test plan and verify it is achievable.
6

Enhance test plan

Add contract validation test cases (from OpenAPI/Swagger specs) and accessibility test cases (for web apps using @axe-core/playwright at WCAG 2.1 AA level).
7

Assess coverage (web only)

Compare requirements against the enhanced test plan to identify gaps. Requires playwright-cli in PATH.
8

Create manual testing checklist (web only)

Generate a checklist using three strategies: page-by-page exhaustive testing, user-story walkthroughs, and accessibility spot-checks.
9

Manual testing execution (web only)

Execute checklist items via playwright-cli. Runs serially in CLI mode, or in parallel via Cloud Batch when PDD_CLOUD_RUN=true.
10

Create regression tests (web only)

Generate automated tests that reproduce bugs found in the manual testing step.
11

Validate regression tests (web only)

Confirm regression tests fail against current code, proving the bugs exist.
12

Loop check (web only)

Check checklist completion. Loops back to the execution step if items remain (max 3 iterations).
13

Generate tests

Create tests from the enhanced plan, including behavioral, contract, and accessibility tests.
14

Run tests

Execute all generated tests against the target.
15

Fix and iterate

Fix any failing tests and re-run until they pass.
16

Validate tests against plan

Cross-reference the enhanced plan against generated tests. Generate missing tests for any unimplemented cases.
17

Run newly generated tests

Run and fix tests created in the previous step, if any.
18

Submit PR

Create a draft PR with an enhanced description including test plan coverage ratio, contract test summary, accessibility audit summary, and manual testing summary.
Execution modes:
ModeSteps 7–12 behavior
CLI (pdd test <url>)Serial: runs each checklist chunk one at a time
GitHub App (PDD_CLOUD_RUN=true)Parallel: fans out to Cloud Batch spot VMs
Steps 7–12 (manual/exploratory testing) require playwright-cli in your PATH. If not found, these steps are skipped with a warning. They only run for web test types.
Cross-machine resume: Workflow state is stored in a hidden GitHub issue comment. Re-run the same command on any machine to resume.

​
Manual unit test generation

Pass a prompt file and a code file to generate or enhance unit tests for a module. 
# Generate initial unit tests
pdd test --output tests/test_calculator.py \
  calculator_python.prompt src/calculator.py

# Generate tests from an example file (TDD style)
pdd test --output tests/test_calculator.py \
  calculator_python.prompt examples/calculator_example.py

# Generate additional tests to improve coverage
pdd test \
  --coverage-report coverage.xml \
  --existing-tests tests/test_calculator.py \
  --existing-tests tests/test_calculator_edge_cases.py \
  --output tests/test_calculator_enhanced.py \
  calculator_python.prompt src/calculator.py

# Improve coverage and merge into existing tests
pdd test \
  --coverage-report coverage.xml \
  --existing-tests tests/test_calculator.py \
  --merge \
  --target-coverage 95.0 \
  calculator_python.prompt src/calculator.py
Test organization: PDD maintains a single test file per target (named test_<basename>.<extension> by default). New tests accumulate in that file over time rather than replacing existing tests. Coverage analysis: When --coverage-report is provided, the command analyzes the report to identify uncovered lines and branches, partially tested conditions, and missing edge cases. It prioritizes generating tests for complex uncovered code paths, error conditions, boundary values, and integration points.

​
Story mode

Generate user stories or update story metadata to link them to affected prompts. 
# Generate a user story from one or more prompt files
pdd test prompts/upload_python.prompt prompts/notify_python.prompt

# Update prompt links in an existing story file
pdd test user_stories/story__my_flow.md
Stories are stored as Markdown files matching story__*.md in the user_stories/ directory by default. Use PDD_USER_STORIES_DIR to override the directory and PDD_PROMPTS_DIR to override the prompts directory.

​
Project-specific context

The test command looks for a context/test.prompt file in the current working directory. If found, its content is included in the internal prompt to specify testing conventions: 
context/test.prompt

Please ensure all tests use the pytest framework and import the main module as: from my_module import *

​
Examples

# Generate UI tests from a GitHub issue
pdd test https://github.com/myorg/myrepo/issues/789

# Resume after answering clarifying questions
pdd test https://github.com/myorg/myrepo/issues/789

# Generate unit tests for a Python module
pdd test --output tests/test_factorial_calculator.py \
  factorial_calculator_python.prompt src/factorial_calculator.py

# Generate user story from prompt files
pdd test prompts/upload_python.prompt prompts/notify_python.prompt

# Fix failing tests revealed by agentic test generation
pdd fix https://github.com/myorg/myrepo/issues/789

Build docs developers (and LLMs) love

Get started for freeTalk to us