From a9dbdecbb3da0a152233c5342b9df0e6b286249e Mon Sep 17 00:00:00 2001 From: mukunda katta Date: Thu, 14 May 2026 19:06:28 -0700 Subject: [PATCH] docs: clarify automation compare output --- README.md | 6 +++--- docs/integrations.html | 2 +- examples/README.md | 5 +++++ tests/test_metadata.py | 20 ++++++++++++++++---- 4 files changed, 25 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index eed2e718..b5c2ad69 100644 --- a/README.md +++ b/README.md @@ -140,7 +140,7 @@ When you have a failed run and a known-good run for the same Browser Use task, use `browsertrace compare --json` to locate the first divergent action, URL, status, or error field. -For automation-oriented usage notes, see +For the complete automation recipe, see [JSON CLI checks for automation](examples/#json-cli-checks-for-automation). For compact AI/coding-agent troubleshooting context, use @@ -638,8 +638,8 @@ For concise contributor expectations and a welcoming baseline, read To choose the right bug, feature, integration, or cloud/team template, use the [issue template chooser](https://github.com/aaronlab/browsertrace/issues/new/choose). Before opening a PR, use the [pull request template](.github/PULL_REQUEST_TEMPLATE.md) -and include a linked issue and test commands. It also asks you to inspect -`git diff --stat` and `git diff --summary` for unexpected deleted or renamed files. +and include a linked issue and test commands, plus a quick `git diff --stat` and +`git diff --summary` review for unexpected deleted or renamed files. For security-sensitive reports or private trace data, follow [SECURITY.md](SECURITY.md) before sharing details publicly. diff --git a/docs/integrations.html b/docs/integrations.html index bdcca15e..c1582d92 100644 --- a/docs/integrations.html +++ b/docs/integrations.html @@ -347,7 +347,7 @@

AOS mapping research

Status and error steps/toolCallResult with isError partially mapped - Document the research-only toolCallResult result shape as run status, step status, error message/type when available, action/tool label, step id, and public export/redaction state; this remains a research mapping, not an AOS compliance claim. + A useful research-only toolCallResult result shape should include run status, step status, error type/message when available, action or tool label, step id, and redaction/export state; this is not an AOS compliance claim. Screenshot or future video artifact diff --git a/examples/README.md b/examples/README.md index f661f98e..a7e7cb2b 100644 --- a/examples/README.md +++ b/examples/README.md @@ -266,6 +266,11 @@ Expected output: - `browsertrace list --status failed --json` prints recent failed runs as JSON, including run IDs and status values you can feed into automation. - `browsertrace show --json` prints one run as JSON, including run details and step timeline data for that run. +When the local BrowserTrace UI is running, scripts, dashboards, or automation +checks can also call `GET /api/compare//` for +the same first-divergence JSON payload shown by +`browsertrace compare --json`. + For compact AI/coding-agent troubleshooting context, use [`docs/llms.txt`](../docs/llms.txt); it includes JSON CLI checks, project links, and prompts. diff --git a/tests/test_metadata.py b/tests/test_metadata.py index 1fa1234b..08b84c9a 100644 --- a/tests/test_metadata.py +++ b/tests/test_metadata.py @@ -665,13 +665,15 @@ def test_integrations_page_includes_aos_mapping_research_table(): assert rows["Action label or tool call"][2] == "partially mapped" assert rows["Status and error"][1] == "steps/toolCallResult with isError" assert rows["Status and error"][2] == "partially mapped" - assert "research-only toolCallResult result shape" in rows["Status and error"][3] + assert "research-only" in rows["Status and error"][3] + assert "toolCallResult" in rows["Status and error"][3] + assert "result shape" in rows["Status and error"][3] assert "run status" in rows["Status and error"][3] assert "step status" in rows["Status and error"][3] - assert "error message/type" in rows["Status and error"][3] - assert "action/tool label" in rows["Status and error"][3] + assert "error type/message" in rows["Status and error"][3] + assert "action or tool label" in rows["Status and error"][3] assert "step id" in rows["Status and error"][3] - assert "public export/redaction state" in rows["Status and error"][3] + assert "redaction/export state" in rows["Status and error"][3] assert "not an AOS compliance claim" in rows["Status and error"][3] assert rows["Screenshot or future video artifact"][1] == ( "FileWithUri preferred over inline FileWithBytes" @@ -1635,6 +1637,9 @@ def test_readme_links_contributor_guide_near_contributing(): assert "Before starting a good first issue" in contributing_section assert "comment on it first" in contributing_section assert "maintainers can treat it as claimed" in contributing_section + assert "[pull request template](.github/PULL_REQUEST_TEMPLATE.md)" in contributing_section + assert "git diff --stat" in contributing_section + assert "git diff --summary" in contributing_section assert "[good first issue queue]" in contributing_section assert good_first_issue_url in contributing_section assert contributing_section.count(good_first_issue_url) == 1 @@ -2558,6 +2563,10 @@ def test_readme_explains_isolated_trace_storage_near_install_tag(): "By default, BrowserTrace stores local traces under `~/.browsertrace/`; " "set `BROWSERTRACE_HOME` to use an isolated trace store" ) in install_section + assert ( + "[isolated trace storage recipe](examples/#testing-with-isolated-trace-storage)" + in install_section + ) assert 'pip install "browsertrace[ui]"' in install_section assert "hosted sharing" not in readme @@ -3168,6 +3177,9 @@ def test_examples_readme_includes_json_cli_checks_recipe(): assert "### JSON CLI checks for automation" in troubleshooting_section assert "scripts, CI, or AI/coding-agent troubleshooting" in troubleshooting_section + assert "GET /api/compare//" in troubleshooting_section + assert "first-divergence JSON payload" in troubleshooting_section + assert "browsertrace compare --json" in troubleshooting_section assert recipe in troubleshooting_section assert 'pip install "browsertrace[ui]"' in examples_readme assert "hosted sharing" not in examples_readme