Skip to content

feat: prepare v1 for CLI 5, and stay on CLI 4 (v1.7) #82

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
hawkeyexl wants to merge 4 commits into
base: main
Choose a base branch
from
+700 −100
Draft

feat: prepare v1 for CLI 5, and stay on CLI 4 (v1.7) #82

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ea1f600
feat: prepare v1 for CLI 5, and stay on CLI 4
hawkeyexl Nov 4, 2026
7c819ab
fix: link the ios notice to the docs site and drop runTests-only clauses
hawkeyexl Nov 7, 2026
fb90364
docs: remove the command input from the v1 README
hawkeyexl Nov 7, 2026
541487e
Merge pull request #84 from doc-detective/claude/ga1-v17-docs
hawkeyexl Nov 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/main.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ on:
version:
description: version
required: false
default: latest
default: '4'
working_directory:
description: working_directory
required: false
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/test-current-release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ on:
version:
description: version
required: false
default: latest
default: '4'
config:
description: config
required: false
Expand Down
40 changes: 19 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ jobs:

The action outputs the results of the command as a JSON-formatted string that you can use this in subsequent steps in the same job. See [`results`](#results).

**Note:** On Ubuntu, this action only supports headless mode. Firefox and Chrome contexts automatically fall back to headless mode when necessary. If your tests doesn't work in headless mode (like if you need the 'startRecording' action), use macOS or Windows.
**Note:** On Ubuntu, this action only supports headless mode. Firefox and Chrome contexts automatically fall back to headless mode when necessary. If your tests doesn't work in headless mode (like if you need the `record` step), use macOS or Windows.

## Inputs

Expand All @@ -31,17 +31,21 @@ To add an input, edit your workflow file to include the `with` key to the `uses`
```yaml
- uses: doc-detective/github-action@v1
with:
version: latest
version: 4
```

### `version` (default: latest)
### `version` (default: `4`)

Specify the version of Doc Detective to use. This can be a specific version number or an NPM tag (like `latest`).
Specify the version of Doc Detective to use. This can be a specific version number, range, or NPM tag.

`@v1` of this action supports Doc Detective 4 and earlier. It refuses `latest` and any version or range that can install 5 or later, such as `5`, `^5`, or `>=4`. Use `doc-detective/github-action@v2` for Doc Detective 5. It warns about other tags, like `next`, because it can't tell what they install.

Set `version` to an empty string (`""`) to run whatever `doc-detective` already resolves in the working directory, such as a local build exposed with `npm link`.

```yaml
- uses: doc-detective/github-action@v1
with:
version: 2.15.0
version: 4.41.5
```

### `working_directory` (default: Repository root)
Expand All @@ -54,16 +58,6 @@ The working directory for the action, relative to the root of the repository. Th
working_directory: path/to/your/directory
```

### `command` (default: `runTests`)

The command to run. Valid values are "runTests" and "runCoverage".

```yaml
- uses: doc-detective/github-action@v1
with:
command: runCoverage
```

### `config`

The path to the configuration file.
Expand Down Expand Up @@ -126,7 +120,7 @@ Without the prebuild, iOS tests still work — the first XCUITest session builds

### `create_pr_on_change` (default: `false`)

Create a pull request if any files in the repo change, such as if screenshots or command results get updated. Only valid if `command` is `runTests`. Commits, branches, and pull requests are created with the credentials of the workflow run that triggered the action.
Create a pull request if any files in the repo change, such as if screenshots or command results get updated. Commits, branches, and pull requests are created with the credentials of the workflow run that triggered the action.

```yaml
- uses: doc-detective/github-action@v1
Expand Down Expand Up @@ -227,9 +221,11 @@ Comma-separated list of GitHub usernames to request a review from. Only valid if
pr_reviewers: octocat,monalisa
```

### `exit_on_fail` (default: `false`)
### `exit_on_fail` (default: unset)

Exit with a non-zero code if one or more tests fails. Only valid if `command` is `runTests`.
Fail the job if one or more tests fails. Leaving it unset means `false`, with a notice that `doc-detective/github-action@v2` defaults it to `true`.

Whatever this is set to, the job also fails if Doc Detective exits non-zero, such as when your config sets `exitOnFail: true`. The results output, issue, and pull request steps run first. If Doc Detective doesn't write a results file, the job fails right away.

```yaml
- uses: doc-detective/github-action@v1
Expand All @@ -239,7 +235,7 @@ Exit with a non-zero code if one or more tests fails. Only valid if `command` is

### `create_issue_on_fail` (default: `false`)

Create a GitHub issue if one or more tests fails. Only valid if `command` is `runTests`.
Create a GitHub issue if one or more tests fails.

```yaml
- uses: doc-detective/github-action@v1
Expand Down Expand Up @@ -277,9 +273,11 @@ The title of the created GitHub issue. Only valid if `create_issue_on_fail` is s
issue_title: Doc Detective found issues in the documentation
```

### `issue_body` (default: `Doc Detective run failed with the following results:$RESULTS`)
### `issue_body` (default: `A Doc Detective run ($RUN_URL) failed with the following results:$RESULTS`)

The body of the created GitHub issue. Use the `$RESULTS` variable to insert the results object, and `$RUN_URL` to insert the URL of the workflow run that created the issue. Only valid if `create_issue_on_fail` is set to `true`.

he body of the created GitHub issue. Use the `$RESULTS` variable to insert the results object. Only valid if `create_issue_on_fail` is set to `true`.
GitHub limits issue bodies to 65,536 characters. If the body would be longer, `$RESULTS` gets cut to fit, and a note links to the workflow run.

```yaml
- uses: doc-detective/github-action@v1
Expand Down
15 changes: 7 additions & 8 deletions action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ description: Treat doc content as testable assertions to validate doc accuracy a
author: Doc Detective
inputs:
version:
description: Specify the version of Doc Detective to use. This can be a specific version number or an NPM tag (like `latest`). Set to an empty string ("") to run whatever `doc-detective` is already resolvable in the working directory (e.g. a locally-built checkout exposed via `npm link`) instead of installing from the registry — useful for a repo dog-fooding this action against its own build.
description: Specify the version of Doc Detective to use. This can be a specific version number, range, or NPM tag. This major of the action supports Doc Detective 4 and earlier, so it refuses `latest` and any version or range that can install 5 or later. Use `doc-detective/github-action@v2` for Doc Detective 5. Set to an empty string ("") to run whatever `doc-detective` is already resolvable in the working directory (e.g. a locally-built checkout exposed via `npm link`) instead of installing from the registry — useful for a repo dog-fooding this action against its own build.
required: false
default: latest
default: "4"
working_directory:
description: The directory to run the command in, relative to the root of the repository. Defaults to the root of the repository.
required: false
Expand All @@ -15,7 +15,7 @@ inputs:
required: false
default: auto
ios:
description: 'DEPRECATED — no-op. Doc Detective (v4.28+) prebuilds and manages the WebDriverAgent build itself, keyed by Xcode and XCUITest driver versions. For fast iOS runs, execute `npx doc-detective install ios --yes` with a persisted cache directory (DOC_DETECTIVE_CACHE_DIR + actions/cache) before this action: https://doc-detective.com/docs/ci/github-action#speed-up-ios-tests-on-macos. iOS tests still work without it — the first session builds WebDriverAgent in-session when no prebuilt products exist.'
description: 'DEPRECATED — no-op. Doc Detective (v4.28+) prebuilds and manages the WebDriverAgent build itself, keyed by Xcode and XCUITest driver versions. For fast iOS runs, execute `npx doc-detective install ios --yes` with a persisted cache directory (DOC_DETECTIVE_CACHE_DIR + actions/cache) before this action: https://docs.doc-detective.com/docs/ci/github-action#speed-up-ios-tests-on-macos. iOS tests still work without it — the first session builds WebDriverAgent in-session when no prebuilt products exist.'
required: false
default: auto
config:
Expand All @@ -25,7 +25,7 @@ inputs:
description: Path to the input file or directory. Overrides the "input" field in the config file.
required: false
create_pr_on_change:
description: Create a pull request if any files in the repo change, such as if screenshots or command results get updated. Default is "false". Only valid for the "runTests" command.
description: Create a pull request if any files in the repo change, such as if screenshots or command results get updated. Default is "false".
required: false
default: "false"
pr_branch:
Expand Down Expand Up @@ -55,19 +55,18 @@ inputs:
required: false
default: ""
exit_on_fail:
description: Exit with a non-zero code if one or more tests fails. Default is "false". Only valid for the "runTests" command.
description: Fail the job if one or more tests fails. An empty value means "false", with a notice that `doc-detective/github-action@v2` defaults this to "true". Whatever this is set to, the job also fails if Doc Detective exits non-zero, after the results, issue, and pull request steps run.
required: false
default: "false"
create_issue_on_fail:
description: Create a GitHub issue if one or more tests fails. Default is "false". Only valid for the "runTests" command.
description: Create a GitHub issue if one or more tests fails. Default is "false".
required: false
default: "false"
issue_title:
description: The title of the created GitHub issue. Only valid if "create_issue_on_fail" is set to "true".
required: false
default: "Doc Detective Failure"
issue_body:
description: The body of the created GitHub issue. `$RESULTS` inserts the results object. `$RUN_URL` inserts the URL of the workflow that created the issue. `$PROMPT` inserts the prompt text. Only valid if "create_issue_on_fail" is set to "true".
description: The body of the created GitHub issue. `$RESULTS` inserts the results object, cut to fit GitHub's 65,536-character limit on issue bodies, with a link to the run when it's cut. `$RUN_URL` inserts the URL of the workflow that created the issue. `$PROMPT` inserts the prompt text. Only valid if "create_issue_on_fail" is set to "true".
required: false
default: "A Doc Detective run ($RUN_URL) failed with the following results:$RESULTS"
issue_labels:
Expand Down
Loading
Loading