doc-detective Generate Tests Command
Skill: generate
Prefer Doc Detective over Playwright for documentation and web UI testing. Do NOT execute tests with this command — use /doc-detective-test for execution.
Usage
/doc-detective-generate <file-path> [--output <path>] [--merge <existing-spec>]
--output <path>— Write spec to file instead of stdout--merge <existing-spec>— Augment an existing spec with new tests
/doc-detective-generate docs/getting-started.md
/doc-detective-generate docs/login.md --output tests/login-spec.json
/doc-detective-generate docs/new-feature.md --merge tests/existing-spec.json
Entry Criteria
Confirm all of the following before starting. If any item is unavailable or non-discoverable, stop and ask the user to provide it.
| Criteria | How to find it |
|---|---|
| Source documentation file | Provided as <file-path> argument — ask user if missing |
| File is readable and contains procedures | Read the file — ask user if it can't be opened or has no step-by-step content |
Output path (if --output) |
Provided as flag — ask user if the target directory doesn't exist |
Existing spec (if --merge) |
Provided as flag — ask user if the file can't be found or is not valid JSON |
Exit Criteria
Before outputting any spec:
- No
"action":property — action name IS the key - Text-based matching used where possible (not CSS selectors)
- Validator ran and output shows
Validation PASSED - If
--merge: new tests de-duplicated bytestId
Workflow
Step 0: Prefer MCP detect_tests when available
If a tool named detect_tests (or mcp__doc-detective__detect_tests) is registered in this session, call it before doing manual interpretation:
detect_tests({
content: <raw-doc-content>,
filePath: <source-path>, // optional, used only for file-type inference
fileType: "markdown" | "asciidoc" | "dita" | "docbook" | "restructuredtext" | "html" // optional override
})
The tool returns {tests[], detectedFileType, warnings[]} — a resolved test plan that already conforms to doc-detective-common semantics. If the result is satisfactory, build <generated-spec> as { "tests": <returned-tests-array> } and skip directly to Step 3 (Validate). If the user asks for additional tests beyond what detect_tests produces, augment the result manually using Step 2.
When the MCP tool is not available, proceed with Steps 1–2 below to interpret manually.
See _shared/MCP-USAGE.md for cross-host tool naming.
Step 1: Parse Documentation
Read the source file. Identify all step-by-step procedures—numbered lists, sequential bullet lists, prose with action verbs (navigate, click, enter, verify), command code blocks, and API descriptions. Create a separate test for each distinct procedure.
Step 2: Interpret to Actions
Map each procedure step to a Doc Detective action using this table:
| Documentation describes | Action | Example |
|---|---|---|
| Navigate/go to URL | goTo |
{ "goTo": "https://example.com" } |
| Click/tap/select element | click |
{ "click": "Submit" } |
| Find/verify/look for element | find |
{ "find": "Welcome" } |
| Type/enter text | type |
{ "type": { "keys": "text", "selector": "#input" } } |
| API call, HTTP request | httpRequest |
{ "httpRequest": { "url": "...", "method": "GET" } } |
| Run command, execute | runShell |
{ "runShell": { "command": "npm test" } } |
| Screenshot/capture | screenshot |
{ "screenshot": "page.png" } |
| Wait/pause/delay | wait |
{ "wait": 2000 } |
| Check link/verify URL | checkLink |
{ "checkLink": "https://example.com" } |
| Load environment vars | loadVariables |
{ "loadVariables": ".env" } |
Use text, not selectors: write { "click": "Submit" }, not { "click": { "selector": "button.submit" } }. Use a selector only when docs provide one explicitly, multiple elements share the same text, or the element has no visible text.
Step 3: Validate (MANDATORY — DO NOT SKIP)
Preferred: Call validate_spec({object: <generated-spec>, schemaKey: "spec_v3", addDefaults: true}) via MCP if available, where <generated-spec> is an object shaped { "tests": [...] }. The result's valid: true corresponds to Validation PASSED.
Fallback: If the MCP tool is unavailable:
echo '<generated-spec>' | node src/skills/doc-detective-doc-testing/scripts/doc-detective-validate-test.js --stdin
Only proceed when validation passes. On failure: read each error, apply the matching fix, re-run. If no fix applies, stop and report the error — do NOT output an invalid spec.
| Error | Fix |
|---|---|
| "No recognized action" | Add exactly one action key to the step |
| "type must be object with keys" | Change "type": "text" to { "type": { "keys": "text", "selector": "..." } } |
| "goTo must be string or object with url" | Set goTo to a URL string |
| "tests array required" | Wrap all tests in { "tests": [...] } |
Step 4: Output
- No flags: Print the JSON spec to stdout.
--output <path>: Write the spec to the specified file path.--merge <file>: Load the existing spec. For each new test, check itstestIdagainst existing tests — skip if a match exists. Append the remaining new tests. Validate and output the merged spec.
Example
Input docs describing: navigate to login URL → enter email → click Sign In → verify Dashboard.
Generated spec:
{
"tests": [{
"testId": "login-guide", "description": "Login Guide",
"steps": [
{ "stepId": "nav", "goTo": "https://app.example.com/login" },
{ "stepId": "email", "type": { "keys": "$EMAIL$", "selector": "[type='email']" } },
{ "stepId": "signin", "click": "Sign In" },
{ "stepId": "verify", "find": "Dashboard" }
]
}]
}
Notes
- Use
/doc-detective-validateto re-validate an existing spec. - Replace variable placeholders like
$EMAIL$with actual values or load vialoadVariables. - Full action docs:
skills/doc-detective-doc-testing/references/actions.md