doc-detective-generate

name	doc-detective-generate
description	Interpret documentation procedures into Doc Detective test specifications without executing
metadata	{"version":"1.4.0","organization":"Doc Detective","date":"May 2026","abstract":"Interpret documentation procedures into Doc Detective test specifications without executing the tests. Parses docs, maps language to actions, validates the spec, and outputs the result.","references":"https://doc-detective.com, https://github.com/doc-detective/doc-detective","user-invocable":"true"}
user-invocable	true

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