Skip to content

Commit 71d7498

Browse files
promptless[bot]promptless[bot]
authored
Sync documentation updates from Promptless agent
1 parent 74771d0 commit 71d7498

File tree

2 files changed

+180
-6
lines changed

2 files changed

+180
-6
lines changed

‎docs/get-started/tests/index.mdx‎

Lines changed: 177 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,15 @@ DITA supports two syntax options:
160160

161161
Attribute values are automatically converted to the appropriate type: booleans (`detectSteps=false`), numbers (`wait=500`), and strings. You can use dot notation for nested objects—for example, `<?doc-detective step httpRequest.url="https://api.example.com" httpRequest.method="GET" ?>` creates a nested `httpRequest` object with `url` and `method` properties.
162162

163+
You can also use HTML comment syntax as an alternative to processing instructions:
164+
165+
- Test comments: `<!-- test testId="my-test" detectSteps=false -->`
166+
- Step comments: `<!-- step checkLink="https://example.com" -->`
167+
- Test end: `<!-- test end -->`
168+
- Ignore blocks: `<!-- test ignore start -->` and `<!-- test ignore end -->`
169+
170+
HTML comments and processing instructions work identically. You can use whichever fits your documentation workflow better, or mix them in the same file.
171+
163172
> **Note:** DITA isn't enabled by default. To use DITA detection, add `"dita"` to your config's `fileTypes` array or define custom patterns. See the [config reference](/docs/references/schemas/config) for details.
164173
165174
#### Examples
@@ -243,7 +252,9 @@ Detected tests are useful for keeping your tests in sync with your documentation
243252

244253
> You can mix detected tests with [inline tests](#inline-json-or-yaml) to declare steps that might not be covered in your content, such starting or stopping a recording.
245254
246-
Doc Detective includes several default markup patterns for Markdown files. Here are all the built-in patterns:
255+
Doc Detective includes default markup patterns for Markdown and DITA files. Here are the built-in patterns:
256+
257+
#### Markdown patterns
247258

248259
````json
249260
{
@@ -329,8 +340,78 @@ Doc Detective includes several default markup patterns for Markdown files. Here
329340
}
330341
````
331342

343+
#### DITA patterns
344+
345+
````json
346+
{
347+
"fileTypes": [
348+
{
349+
"name": "dita",
350+
"extensions": ["dita", "ditamap", "xml"],
351+
"markup": [
352+
{
353+
"name": "checkHyperlink",
354+
"regex": [
355+
"<xref\\s+href=\"(https?:\\/\\/[^\"]+)\"[^>]*>"
356+
],
357+
"actions": ["checkLink"]
358+
},
359+
{
360+
"name": "clickOnscreenText",
361+
"regex": [
362+
"\\b(?:[Cc]lick|[Tt]ap|[Ll]eft-click|[Cc]hoose|[Ss]elect|[Cc]heck)\\b\\s+<b>((?:(?!<\\/b>).)+)<\\/b>"
363+
],
364+
"actions": ["click"]
365+
},
366+
{
367+
"name": "findOnscreenText",
368+
"regex": ["<b>((?:(?!<\\/b>).)+)<\\/b>"],
369+
"actions": ["find"]
370+
},
371+
{
372+
"name": "goToUrl",
373+
"regex": [
374+
"\\b(?:[Gg]o\\s+to|[Oo]pen|[Nn]avigate\\s+to|[Vv]isit|[Aa]ccess|[Pp]roceed\\s+to|[Ll]aunch)\\b\\s+<xref\\s+href=\"(https?:\\/\\/[^\"]+)\"[^>]*>"
375+
],
376+
"actions": ["goTo"]
377+
},
378+
{
379+
"name": "screenshotImage",
380+
"regex": [
381+
"<image\\s+[^>]*href=\"([^\"]+)\"[^>]*outputclass=\"[^\"]*screenshot[^\"]*\"[^>]*\\/>"
382+
],
383+
"actions": ["screenshot"]
384+
},
385+
{
386+
"name": "typeText",
387+
"regex": ["\\b(?:[Pp]ress|[Ee]nter|[Tt]ype)\\b\\s+\"([^\"]+)\""],
388+
"actions": ["type"]
389+
},
390+
{
391+
"name": "runCode",
392+
"regex": [
393+
"<codeblock[^>]*outputclass=\"(bash|python|py|javascript|js)\"[^>]*>([\\s\\S]*?)<\\/codeblock>"
394+
],
395+
"actions": [
396+
{
397+
"unsafe": true,
398+
"runCode": {
399+
"language": "$1",
400+
"code": "$2"
401+
}
402+
}
403+
]
404+
}
405+
]
406+
}
407+
]
408+
}
409+
````
410+
332411
#### Default markup pattern descriptions
333412

413+
##### Markdown patterns
414+
334415
**checkHyperlink**: Detects standard Markdown links (excluding images) and checks that they return a valid HTTP status code.
335416

336417
- Pattern: `[link text](https://example.com)`
@@ -371,6 +452,43 @@ Doc Detective includes several default markup patterns for Markdown files. Here
371452
- Pattern: Code blocks with `bash`, `python`, `py`, `javascript`, or `js` language tags (excluding those marked with `testIgnore`)
372453
- Action: Executes the code in the specified language (marked as unsafe)
373454

455+
##### DITA patterns
456+
457+
**checkHyperlink**: Detects DITA xref elements with HTTP/HTTPS URLs and checks that they return a valid HTTP status code.
458+
459+
- Pattern: `<xref href="https://example.com">Link</xref>`
460+
- Action: Performs a GET request to verify the link is accessible
461+
462+
**clickOnscreenText**: Detects action verbs followed by bold text and clicks on that element.
463+
464+
- Pattern: `Click <b>Button Name</b>`, `Tap <b>Menu Item</b>`, `Select <b>Option</b>`
465+
- Action: Clicks on the specified element using its text content
466+
467+
**findOnscreenText**: Detects any bold text and verifies it exists on the page.
468+
469+
- Pattern: `<b>Any Bold Text</b>`
470+
- Action: Searches for the text on the current page
471+
472+
**goToUrl**: Detects navigation instructions with xref elements and opens the URL.
473+
474+
- Pattern: `Go to <xref href="https://example.com">Page Name</xref>`, `Navigate to <xref href="https://example.com">Site</xref>`
475+
- Action: Opens the specified URL in the browser
476+
477+
**screenshotImage**: Detects image elements with a screenshot outputclass and takes a screenshot.
478+
479+
- Pattern: `<image href="image.png" outputclass="screenshot"/>`
480+
- Action: Saves a screenshot to the specified path
481+
482+
**typeText**: Detects typing instructions with quoted text and types the content.
483+
484+
- Pattern: `Type "Hello World"`, `Enter "username"`
485+
- Action: Types the specified text into the active element
486+
487+
**runCode**: Detects code blocks in supported languages and executes the code.
488+
489+
- Pattern: Code blocks with `bash`, `python`, `py`, `javascript`, or `js` outputclass (excluding those marked with `testIgnore`)
490+
- Action: Executes the code in the specified language (marked as unsafe)
491+
374492
The `regex` property defines the regular expression patterns to match, and the `actions` property defines the actions to perform when the pattern is detected. With the default configuration, Doc Detective would take the following Markdown and generate tests automatically:
375493

376494
Markdown:
@@ -415,6 +533,58 @@ Detected tests:
415533
}
416534
```
417535

536+
**DITA example with detected tests:**
537+
538+
```xml
539+
<?xml version="1.0" encoding="UTF-8"?>
540+
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
541+
<topic id="getting-started">
542+
<title>Getting Started</title>
543+
<!-- test testId="dita-detected-test" detectSteps=true -->
544+
<body>
545+
<p>To get started,</p>
546+
<ol>
547+
<li>Go to <xref href="https://console.acme.com">Acme Console</xref>.</li>
548+
<li>Click <b>Search</b>.</li>
549+
<li>Type "American Shorthair kittens".</li>
550+
</ol>
551+
<p>Check out our <xref href="https://docs.example.com">documentation</xref> for more information.</p>
552+
<fig>
553+
<image href="search-results.png" outputclass="screenshot"/>
554+
</fig>
555+
</body>
556+
<!-- test end -->
557+
</topic>
558+
```
559+
560+
Detected tests:
561+
562+
```json
563+
{
564+
"tests": [
565+
{
566+
"steps": [
567+
{
568+
"goTo": "https://console.acme.com"
569+
},
570+
{
571+
"click": "Search"
572+
},
573+
{
574+
"type": "American Shorthair kittens"
575+
},
576+
{
577+
"checkLink": "https://docs.example.com"
578+
},
579+
{
580+
"screenshot": "search-results.png"
581+
}
582+
]
583+
}
584+
]
585+
}
586+
```
587+
418588
### Custom markup patterns
419589

420590
You can extend or override the default patterns by defining custom markup patterns in your configuration:
@@ -446,7 +616,7 @@ You can extend or override the default patterns by defining custom markup patter
446616

447617
#### Other file types
448618

449-
Doc Detective also includes default configurations for HTML and AsciiDoc files, though these only include inline statement patterns for test definitions and don't include markup patterns for detected tests:
619+
Doc Detective also includes default configurations for HTML and AsciiDoc files. These currently only include inline statement patterns for test definitions and don't include markup patterns for detected tests:
450620

451621
**HTML files** (`.html`, `.htm`):
452622

@@ -458,11 +628,15 @@ Doc Detective also includes default configurations for HTML and AsciiDoc files,
458628
- Uses AsciiDoc comment syntax for inline test statements
459629
- Example: `// (test { "testId": "my-test" })`
460630

631+
**DITA files** (`.dita`, `.ditamap`, `.xml`):
632+
633+
DITA includes both inline statement patterns (processing instructions and HTML comments) and markup patterns for detected tests. See the [DITA inline statements](#inline-json-or-yaml) and [default markup patterns](#detected-tests) sections above for complete documentation.
634+
461635
To add detected test functionality to HTML or AsciiDoc files, you would need to define custom markup patterns in your configuration similar to the Markdown examples above.
462636

463637
### Default actions
464638

465-
If you only need to perform simple steps, you can define actions using a shorthand of only specifying the action name. Doc Detective uses default actions, substituting the first capture group (or if there are no capture groups, the entire match) from the regex pattern into the most common location for the action. In the above example, the config generates a `goTo` action for every Markdown hyperlink preceded by a navigation verb.
639+
If you only need to perform basic steps, you can define actions using a shorthand of only specifying the action name. Doc Detective uses default actions, substituting the first capture group (or if there are no capture groups, the entire match) from the regex pattern into the most common location for the action. In the above example, the config generates a `goTo` action for every Markdown hyperlink preceded by a navigation verb.
466640

467641
The default actions are as follows:
468642

‎docs/references/schemas/config.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,14 @@ Field | Type | Description | Default
1010
$schema | string | Optional. JSON Schema for this object.<br/><br/>Accepted values: `https://raw.githubusercontent.com/doc-detective/common/refs/heads/main/dist/schemas/config_v3.schema.json` |
1111
configId | string | Optional. Identifier for the configuration. |
1212
configPath | string | ReadOnly. Path to the configuration file. |
13-
input | one of:<br/>- string<br/>- array of string | Optional. Path(s) to test specifications and documentation source files. May be paths to specific files or to directories to scan for files. | `.`
13+
input | one of:<br/>- string<br/>- array of string | Optional. Paths to test specifications and documentation source files. May be paths to specific files or to directories to scan for files. | `.`
1414
output | string | Optional. Path of the directory in which to store the output of Doc Detective commands. If a file path is specified, Doc Detective attempts to honor the file name specified, but file path behavior is controlled by the configured reporters. | `.`
1515
recursive | boolean | Optional. If `true` searches `input`, `setup`, and `cleanup` paths recursively for test specifications and source files. | `true`
1616
relativePathBase | string | Optional. Whether paths should be interpreted as relative to the current working directory (`cwd`) or to the file in which they're specified (`file`).<br/><br/>Accepted values: `cwd`, `file` | `file`
1717
loadVariables | string | Optional. Load environment variables from the specified `.env` file. |
1818
origin | string | Optional. Default protocol and domain to use for relative URLs. |
19-
beforeAny | one of:<br/>- string<br/>- array of string | Optional. Path(s) to test specifications to perform before those specified by `input`. Useful for setting up testing environments. |
20-
afterAll | one of:<br/>- string<br/>- array of string | Optional. Path(s) to test specifications to perform after those specified by `input`. Useful for cleaning up testing environments. |
19+
beforeAny | one of:<br/>- string<br/>- array of string | Optional. Paths to test specifications to perform before those specified by `input`. Useful for setting up testing environments. |
20+
afterAll | one of:<br/>- string<br/>- array of string | Optional. Paths to test specifications to perform after those specified by `input`. Useful for cleaning up testing environments. |
2121
detectSteps | boolean | Optional. Whether or not to detect steps in input files based on defined markup. | `true`
2222
allowUnsafeSteps | boolean | Optional. Whether or not to run potentially unsafe steps, such as those that might modify files or system state. |
2323
logLevel | string | Optional. Amount of detail to output when performing an operation.<br/><br/>Accepted values: `silent`, `error`, `warning`, `info`, `debug` | `info`

0 commit comments

Comments
 (0)