From 6be90f2783e49e68c8d765a5acf66f793301df89 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Wed, 11 Mar 2026 21:50:44 +0000 Subject: [PATCH] Document test detection enhancements and source location tracking --- .../contribute/repos/doc-detective-common.md | 43 +++++++++++++++++++ fern/pages/docs/tests/detected.mdx | 31 ++++++++++++- fern/pages/reference/schemas/common.md | 1 + .../reference/schemas/source-location.md | 35 +++++++++++++++ 4 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 fern/pages/reference/schemas/source-location.md diff --git a/fern/pages/contribute/repos/doc-detective-common.md b/fern/pages/contribute/repos/doc-detective-common.md index d850a23..0aa4f33 100644 --- a/fern/pages/contribute/repos/doc-detective-common.md +++ b/fern/pages/contribute/repos/doc-detective-common.md @@ -7,3 +7,46 @@ title: doc-detective-common The source code lives in the [`doc-detective`](https://github.com/doc-detective/doc-detective) monorepo under `src/common/`, but the package is still published independently to NPM. This package doesn't depend on any other Doc Detective packages. + +## Public exports + +The package exports the following types and utilities: + +### Types + +- `Specification`: TypeScript type for test specifications +- `Test`: TypeScript type for test objects +- `Step`: TypeScript type for step objects +- `Context`: TypeScript type for context objects +- `Config`: TypeScript type for configuration objects +- `Report`: TypeScript type for report objects +- `FileType`: TypeScript type for file type definitions + +### Utilities + +- `schemas`: All JSON schemas for validation +- `validate()`: Validate objects against Doc Detective schemas +- `detectTests()`: Detect tests from documentation content +- `defaultFileTypes`: Default file type definitions for Markdown, HTML, AsciiDoc, and DITA + +### Example usage + +```javascript +import { + detectTests, + defaultFileTypes, + validate +} from "doc-detective-common"; + +// Detect tests from Markdown content +const tests = await detectTests({ + content: "Click **Submit** to continue.", + fileType: defaultFileTypes.markdown +}); + +// Validate a test specification +const result = validate({ + schemaKey: "spec_v3", + object: mySpec +}); +``` diff --git a/fern/pages/docs/tests/detected.mdx b/fern/pages/docs/tests/detected.mdx index 6c8400f..55553c1 100644 --- a/fern/pages/docs/tests/detected.mdx +++ b/fern/pages/docs/tests/detected.mdx @@ -3,7 +3,7 @@ title: Detected tests description: Automatically generate tests based on your documentation source files. --- -Doc Detective can automatically generate tests based on your documentation source files and your `fileTypes` configuration. Detected tests are useful for large, complex test suites that you want to keep in sync with your documentation. Test detection works by setting `detectSteps` to `true` and defining markup patterns and associated actions in the `fileTypes.markup` array in your [config](/reference/schemas/config), which Doc Detective uses to extract steps from your doc source files. You can define multiple test patterns in your config to extract different types of tests from your documentation. +Doc Detective can automatically generate tests based on your documentation source files and your `fileTypes` configuration. Detected tests are useful for large, complex test suites that you want to keep in sync with your documentation. Test detection is enabled by default (`detectSteps: true`) and uses markup patterns and associated actions defined in the `fileTypes.markup` array in your [config](/reference/schemas/config) to extract steps from your doc source files. You can define multiple test patterns in your config to extract different types of tests from your documentation. Detected tests are useful for keeping your tests in sync with your documentation. When you update your documentation, Doc Detective automatically updates the tests based on the new content. Detected tests are generated automatically. You can't edit detected tests directly, but you can update your config or documentation source files to change the tests. @@ -20,6 +20,35 @@ Detected tests provide several advantages: Combine detected tests with [inline tests](./inline-tests) for comprehensive test coverage with minimal manual effort. +## Source location tracking + +Detected steps include source location metadata that identifies where each step was found in your documentation. This information is useful for debugging failed tests and understanding which parts of your documentation triggered specific test steps. + +Each detected step includes a `location` object with: + +- **line**: The 1-indexed line number where the step was detected +- **startIndex**: The 0-indexed character offset where the step begins +- **endIndex**: The 0-indexed character offset where the step ends + +For example, a detected step might include: + +```json +{ + "click": "Search", + "location": { + "line": 5, + "startIndex": 42, + "endIndex": 58 + } +} +``` + + + +The `location` property is read-only system metadata. You can't set it manually in your test specifications. + + + ## Default markup patterns Doc Detective includes default markup patterns for Markdown and DITA files. For comprehensive information about each input format and their patterns, see [Input formats](/docs/input-formats/overview). diff --git a/fern/pages/reference/schemas/common.md b/fern/pages/reference/schemas/common.md index 11826f1..d7d3697 100644 --- a/fern/pages/reference/schemas/common.md +++ b/fern/pages/reference/schemas/common.md @@ -19,6 +19,7 @@ unsafe | boolean | Optional. Whether or not the step may be unsafe. Unsafe steps outputs | object(Outputs (step)) | Optional. Outputs from step processes and user-defined expressions. Use the `outputs` object to reference outputs in subsequent steps. If a user-defined output matches the key for a step-defined output, the user-defined output takes precedence. | ``{}`` variables | object(Variables (step)) | Optional. Environment variables to set from user-defined expressions. | ``{}`` breakpoint | boolean | Optional. Whether or not this step should act as a breakpoint when debugging is enabled. When `true`, execution will pause at this step when debug mode is enabled. | `false` +location | object([Source Location](/reference/schemas/source-location)) | ReadOnly. Source location where this step was detected in the original file. This is system-populated metadata for [detected tests](/docs/tests/detected) and should not be set manually. | ## Examples diff --git a/fern/pages/reference/schemas/source-location.md b/fern/pages/reference/schemas/source-location.md new file mode 100644 index 0000000..78b5619 --- /dev/null +++ b/fern/pages/reference/schemas/source-location.md @@ -0,0 +1,35 @@ +--- +title: "Source Location" +--- + +Source location metadata for [detected tests](/docs/tests/detected). This object identifies where a step was detected in a documentation source file. + +## Referenced In + +- [Common](/reference/schemas/common) + +## Fields + +Field | Type | Description | Default +:-- | :-- | :-- | :-- +line | integer | Required. 1-indexed line number in the source file where the step was detected. Minimum: 1 | +startIndex | integer | Required. 0-indexed character offset from the start of the source file where the step begins. Minimum: 0 | +endIndex | integer | Required. 0-indexed character offset from the start of the source file where the step ends (exclusive). Minimum: 0 | + +## Examples + +```json +{ + "line": 5, + "startIndex": 42, + "endIndex": 58 +} +``` + +```json +{ + "line": 12, + "startIndex": 156, + "endIndex": 203 +} +```