Inline Tests in Markdown

Inline tests allow you to embed test steps directly within your markdown documentation. This keeps your tests close to your content and ensures your documentation instructions are always accurate.

Why Inline Tests?

Inline tests offer several advantages:

Co-location: Tests live with the content they validate
Automatic detection: Doc Detective can detect tests from natural language
Easy maintenance: Update tests when you update docs
Documentation as tests: Your documentation becomes executable

Two Approaches

Doc Detective supports two methods for inline testing:

Explicit inline tests: Define test steps using special comments
Detected tests: Let Doc Detective infer tests from markdown patterns

Explicit Inline Tests

Define test steps using markdown comments that Doc Detective recognizes.

Comment Syntax

Doc Detective supports multiple comment formats:

Markdown Comments
HTML Comments
JSX Comments (MDX)

[comment]: # (step { "action": "goTo", "url": "https://example.com" })

<!-- step { "action": "goTo", "url": "https://example.com" } -->

{/* step { "action": "goTo", "url": "https://example.com" } */}

Basic Example

Write your documentation

Create your markdown content with instructions:

# How to Search for Kittens

To search for American Shorthair kittens:

1. Go to [DuckDuckGo](https://www.duckduckgo.com).
2. In the search bar, enter "American Shorthair kittens", then press Enter.

Add test steps

Add test step comments after each instruction:

# How to Search for Kittens

To search for American Shorthair kittens:

1. Go to [DuckDuckGo](https://www.duckduckgo.com).

   [comment]: # (step { "action": "goTo", "url": "https://www.duckduckgo.com"})

2. In the search bar, enter "American Shorthair kittens", then press Enter.

   [comment]: # (step { "action": "find", "selector": "#searchbox_input", "click": true })
   [comment]: # (step { "action": "typeKeys", "keys": ["American Shorthair kittens", "$ENTER$"] })
   [comment]: # (step { "action": "find", "selector": "[data-testid='web-vertical']" })

Run the test

Doc Detective automatically detects and runs inline tests:

npx doc-detective kitten-search.md

Test Boundaries

Control where tests start and end:

Test Start
Test End
Ignore Sections

Mark the beginning of a test:

[comment]: # (test start testId: my-test)

<!-- Or with more options -->
[comment]: # (test { "testId": "my-test", "detectSteps": false })

Mark the end of a test:

[comment]: # (test end)

Exclude content from test detection:

[comment]: # (test ignore start)

This content won't be tested.

[comment]: # (test ignore end)

Complete Example

To search for American Shorthair kittens,

[comment]: # (test { "testId": "kitten-search", "detectSteps": false })

1. Go to [DuckDuckGo](https://www.duckduckgo.com).

   [comment]: # (step { "action": "goTo", "url": "https://www.duckduckgo.com"})
   [comment]: # (step { "action": "startRecording", "path": "search-results.gif"})

2. In the search bar, enter "American Shorthair kittens", then press Enter.

   [comment]: # (step { "action": "find", "selector": "#searchbox_input", "click": true })
   [comment]: # (step { "action": "typeKeys", "keys": ["American Shorthair kittens", "$ENTER$"] })
   [comment]: # (step { "action": "find", "selector": "[data-testid='web-vertical']" })
   [comment]: # (step { "action": "stopRecording" })

![](search-results.gif)

[comment]: # (test end)

Detected Tests

Doc Detective can automatically detect test steps from markdown patterns without explicit step comments.

Enabling Detection

Configure detection patterns in .doc-detective.json:

{
  "fileTypes": [
    {
      "name": "markdown",
      "extensions": ["md", "markdown", "mdx"],
      "markup": [
        {
          "name": "goToUrl",
          "regex": [
            "\\b(?:[Gg]o\\s+to|[Oo]pen|[Nn]avigate\\s+to)\\b\\s+\\[[^\\]]+\\]\\(\\s*(https?:\\/\\/[^\\s)]+)"
          ],
          "actions": ["goTo"]
        },
        {
          "name": "clickOnscreenText",
          "regex": [
            "\\b(?:[Cc]lick|[Tt]ap|[Ss]elect)\\b\\s+\\*\\*((?:(?!\\*\\*).)+)\\*\\*"
          ],
          "actions": ["click"]
        },
        {
          "name": "typeText",
          "regex": [
            "\\b(?:enter|type)\\b\\s+\"([^\"]+)\""
          ],
          "actions": ["type"]
        }
      ]
    }
  ]
}

Detection Patterns

Doc Detective’s default configuration includes these patterns:

Navigate to URL

Trigger phrases: “Go to”, “Open”, “Navigate to”, “Visit”

Go to [DuckDuckGo](https://www.duckduckgo.com).

Generates:

{ "action": "goTo", "url": "https://www.duckduckgo.com" }

Click Element

Trigger phrases: “Click”, “Tap”, “Select” + bold text

Click **Submit**.

Generates:

{ "action": "find", "selector": "Submit", "click": true }

Type Text

Trigger phrases: “enter”, “type” + quoted text

Enter "American Shorthair kittens" in the search bar.

Generates:

{ "action": "typeKeys", "keys": ["American Shorthair kittens"] }

Press Enter

Trigger phrase: “press Enter”

Press Enter to submit.

Generates:

{ "action": "typeKeys", "keys": ["$ENTER$"] }

Find Text

Any bold text is treated as something to find:

You should see **Search results**.

Generates:

{ "action": "find", "selector": "Search results" }

Check Links

All markdown links are checked by default:

See [our documentation](https://example.com/docs).

Generates:

{ "action": "checkLink", "url": "https://example.com/docs" }

Screenshot from Image

Images with .screenshot class:

![Search results](search-results.png){ .screenshot }

Generates:

{ "action": "saveScreenshot", "path": "search-results.png" }

Detection Example

To search for American Shorthair kittens,

1. Go to [DuckDuckGo](https://www.duckduckgo.com).
2. In the search bar, enter "American Shorthair kittens", then press Enter.

<!-- step wait: 10000 -->

!["Search results for kittens"](search-results.png){ .screenshot }

Doc Detective detects:

Navigation to DuckDuckGo
Typing the search query
Pressing Enter
A 10-second wait
Screenshot capture

Combining Both Approaches

You can mix explicit steps with detection:

# User Registration

[comment]: # (test testId: user-registration)

1. Go to [the registration page](https://app.example.com/register).

2. Fill in your details:
   - Enter "[email protected]" in the email field
   - Enter "securepassword" in the password field

3. Click **Sign Up**.

   [comment]: # (step { "action": "wait", "duration": 2000 })
   [comment]: # (step { "action": "find", "selector": ".welcome-message" })

[comment]: # (test end)

Recording Media

Capture screenshots and recordings during test execution:

Screenshots

Basic Screenshot
With Directory
With Variation

[comment]: # (step { "action": "saveScreenshot", "path": "result.png" })

![Result](result.png)

[comment]: # (step { "action": "saveScreenshot", "path": "result.png", "directory": "screenshots" })

[comment]: # (step { "action": "saveScreenshot", "path": "result.png", "maxVariation": 5, "overwrite": "byVariation" })

Screen Recordings

[comment]: # (step { "action": "startRecording", "path": "demo.gif" })

<!-- Perform your steps -->

[comment]: # (step { "action": "stopRecording" })

![Demo](demo.gif)

Recordings are only supported in browser contexts, not for shell commands or API tests.

Configuration Options

Control inline test behavior in .doc-detective.json:

{
  "fileTypes": [
    {
      "name": "markdown",
      "extensions": ["md", "markdown", "mdx"],
      "inlineStatements": {
        "testStart": [
          "{\\/\\*\\s*test\\s+?([\\s\\S]*?)\\s*\\*\\/}",
          "<!--\\s*test\\s*([\\s\\S]*?)\\s*-->",
          "\\[comment\\]:\\s+#\\s+\\(test\\s*(.*?)\\s*\\)"
        ],
        "testEnd": [
          "{\\/\\*\\s*test end\\s*\\*\\/}",
          "<!--\\s*test end\\s*([\\s\\S]*?)\\s*-->",
          "\\[comment\\]:\\s+#\\s+\\(test end\\)"
        ],
        "step": [
          "{\\/\\*\\s*step\\s+?([\\s\\S]*?)\\s*\\*\\/}",
          "<!--\\s*step\\s*([\\s\\S]*?)\\s*-->",
          "\\[comment\\]:\\s+#\\s+\\(step\\s*(.*?)\\s*\\)"
        ]
      }
    }
  ]
}

Best Practices

Keep steps simple

Each step should do one clear action. Break complex operations into multiple steps.

Use detection wisely

Detection works great for simple navigation and clicks. Use explicit steps for complex interactions.

Add wait steps

Pages often need time to load. Add explicit waits after navigation or interactions:

<!-- step wait: 2000 -->

Test boundaries

Use test start and test end to clearly define what’s being tested, especially in long documents.

Troubleshooting

Tests not being detected

Verify your .doc-detective.json includes the file extension
Check that markup patterns are properly configured
Ensure your markdown follows the expected patterns
Try adding detectSteps: true to test definition

Steps executing in wrong order

Use explicit step comments for precise control
Check that steps are in the correct sequence in your markdown
Disable detection (detectSteps: false) if needed

Screenshots not capturing correctly

Add a wait step before the screenshot
Verify the element you want to capture is visible
Check the path and directory exist or can be created

Comments visible in rendered docs

Use proper comment syntax:

Markdown: [comment]: # (step ...)
HTML: 
JSX/MDX: {/* step ... */}

Common Pitfalls

Mixing test syntaxes inconsistently within the same document
Forgetting to close test boundaries with test end
Using detection without configuring appropriate regex patterns
Not adding waits between steps for dynamic content
Placing step comments too far from the instruction they test

Next Steps

Writing Tests

Learn about standalone test specifications

Configuration

Customize detection patterns and file types

Contexts

Test across multiple platforms and browsers

Actions Reference

Explore all available test actions

Get Started

Core Concepts

Actions

Guides

Inline Tests in Markdown

Why Inline Tests?

Two Approaches

Explicit Inline Tests

Comment Syntax

Basic Example

Test Boundaries

Complete Example

Detected Tests

Enabling Detection

Detection Patterns

Detection Example

Combining Both Approaches

Recording Media

Screenshots

Screen Recordings

Configuration Options

Best Practices

Keep steps simple

Use detection wisely

Add wait steps

Test boundaries

Troubleshooting

Next Steps

Writing Tests

Configuration

Contexts

Actions Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Actions

Guides

​Why Inline Tests?

​Two Approaches

​Explicit Inline Tests

​Comment Syntax

​Basic Example

​Test Boundaries

​Complete Example

​Detected Tests

​Enabling Detection

​Detection Patterns

​Detection Example

​Combining Both Approaches

​Recording Media

​Screenshots

​Screen Recordings

​Configuration Options

​Best Practices

Keep steps simple

Use detection wisely

Add wait steps

Test boundaries

​Troubleshooting

​Next Steps

Writing Tests

Configuration

Contexts

Actions Reference

Build docs developers (and LLMs) love

Why Inline Tests?

Two Approaches

Explicit Inline Tests

Comment Syntax

Basic Example

Test Boundaries

Complete Example

Detected Tests

Enabling Detection

Detection Patterns

Detection Example

Combining Both Approaches

Recording Media

Screenshots

Screen Recordings

Configuration Options

Best Practices

Troubleshooting

Next Steps