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:

1. [ ] No "action": property — action name IS the key
2. [ ] Text-based matching used where possible (not CSS selectors)
3. [ ] Validator ran and output shows Validation PASSED
4. [ ] If --merge: new tests de-duplicated by testId

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 its testId against 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-validate to re-validate an existing spec.
• Replace variable placeholders like $EMAIL$ with actual values or load via loadVariables.
• Full action docs: skills/doc-detective-doc-testing/references/actions.md