sniff-qa 0.6.1 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +2 -2
- package/CHANGELOG.md +96 -0
- package/NOTICE +1 -1
- package/README.md +109 -320
- package/dist/assert-budget-NBF3JYM7.js +9 -0
- package/dist/caps-G3ZGJI7B.js +21 -0
- package/dist/caps-G3ZGJI7B.js.map +1 -0
- package/dist/{chunk-LJYT4MD5.js → chunk-7ZOFYET5.js} +18 -97
- package/dist/chunk-7ZOFYET5.js.map +1 -0
- package/dist/chunk-EGANHIIE.js +91 -0
- package/dist/chunk-EGANHIIE.js.map +1 -0
- package/dist/chunk-GV27IOMC.js +106 -0
- package/dist/chunk-GV27IOMC.js.map +1 -0
- package/dist/chunk-GX36BPK7.js +161 -0
- package/dist/chunk-GX36BPK7.js.map +1 -0
- package/dist/chunk-NG2IGCAK.js +45 -0
- package/dist/chunk-NG2IGCAK.js.map +1 -0
- package/dist/cli/index.js +27 -16
- package/dist/cli/index.js.map +1 -1
- package/dist/crawl-ZXZRF4Q7.js +15 -0
- package/dist/crawl-ZXZRF4Q7.js.map +1 -0
- package/dist/crawl-command-RDWGHZC4.js +76 -0
- package/dist/crawl-command-RDWGHZC4.js.map +1 -0
- package/dist/{discover-Q363YJ5X.js → discover-QKGMYPHK.js} +15 -7
- package/dist/discover-QKGMYPHK.js.map +1 -0
- package/dist/{domain-NNL2PPRK.js → domain-UQ34YE4B.js} +1 -1
- package/dist/index.d.ts +15 -0
- package/dist/index.js +6 -2
- package/dist/index.js.map +1 -1
- package/dist/{loader-UG2XADG7.js → loader-Z2DUGG5Z.js} +18 -2
- package/dist/loader-Z2DUGG5Z.js.map +1 -0
- package/dist/mcp/server.d.ts +20 -1
- package/dist/mcp/server.js +37 -28
- package/dist/mcp/server.js.map +1 -1
- package/dist/{model-2DTSAX7T.js → model-SP6HJN6J.js} +4 -2
- package/dist/model-SP6HJN6J.js.map +1 -0
- package/dist/{persistence-RHUFBQAY.js → persistence-XLFJ5EY4.js} +6 -2
- package/dist/persistence-XLFJ5EY4.js.map +1 -0
- package/dist/{quality-run-LLBZZI7X.js → quality-run-YAURB242.js} +6 -5
- package/dist/{quality-run-LLBZZI7X.js.map → quality-run-YAURB242.js.map} +1 -1
- package/dist/redaction-CHAIVPCF.js +30 -0
- package/dist/redaction-CHAIVPCF.js.map +1 -0
- package/dist/{repo-analyzer-WK5WP7NT.js → repo-analyzer-4OURSITY.js} +1 -1
- package/dist/{report-IKRVVIW4.js → report-7FQFH4HW.js} +3 -3
- package/dist/{runner-HFJDHS2I.js → runner-QHSYX7J2.js} +1 -1
- package/dist/{runner-II7BPB63.js → runner-RDVVIGBU.js} +7 -2
- package/dist/runner-RDVVIGBU.js.map +1 -0
- package/dist/{unified-67Z6YA64.js → unified-YSOTPG5B.js} +12 -10
- package/dist/{unified-67Z6YA64.js.map → unified-YSOTPG5B.js.map} +1 -1
- package/dist/{update-baselines-UCAW3SDN.js → update-baselines-JYKUUIZG.js} +2 -2
- package/dist/write-report-6RJWN54I.js +31 -0
- package/dist/write-report-6RJWN54I.js.map +1 -0
- package/package.json +5 -4
- package/skills/sniff/SKILL.md +10 -10
- package/skills/sniff-fix/SKILL.md +3 -0
- package/skills/sniff-report/SKILL.md +3 -0
- package/dist/chunk-LJYT4MD5.js.map +0 -1
- package/dist/crawl-666NLYDC.js +0 -11
- package/dist/crawl-command-3OB4IUBU.js +0 -54
- package/dist/crawl-command-3OB4IUBU.js.map +0 -1
- package/dist/discover-Q363YJ5X.js.map +0 -1
- package/dist/loader-UG2XADG7.js.map +0 -1
- package/dist/model-2DTSAX7T.js.map +0 -1
- package/dist/persistence-RHUFBQAY.js.map +0 -1
- package/dist/runner-II7BPB63.js.map +0 -1
- /package/dist/{crawl-666NLYDC.js.map → assert-budget-NBF3JYM7.js.map} +0 -0
- /package/dist/{domain-NNL2PPRK.js.map → domain-UQ34YE4B.js.map} +0 -0
- /package/dist/{repo-analyzer-WK5WP7NT.js.map → repo-analyzer-4OURSITY.js.map} +0 -0
- /package/dist/{report-IKRVVIW4.js.map → report-7FQFH4HW.js.map} +0 -0
- /package/dist/{runner-HFJDHS2I.js.map → runner-QHSYX7J2.js.map} +0 -0
- /package/dist/{update-baselines-UCAW3SDN.js.map → update-baselines-JYKUUIZG.js.map} +0 -0
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sniff",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.0",
|
|
4
4
|
"description": "Autonomous QA scanner via sniff-qa: walks your running app in a real browser and reports real bugs (broken pages/links, console/network errors, broken forms, state-loss, empty/placeholder data, bad loading/error states, responsive + a11y) with reproduction proof, severity, confidence, and a fix. No API key.",
|
|
5
5
|
"author": {
|
|
6
|
-
"name": "Adam
|
|
6
|
+
"name": "Adam Boudjemaa",
|
|
7
7
|
"url": "https://github.com/Aboudjem/sniff"
|
|
8
8
|
},
|
|
9
9
|
"homepage": "https://github.com/Aboudjem/sniff",
|
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.8.0] - 2026-09-02
|
|
11
|
+
|
|
12
|
+
Three capability additions (MCP tool gating, authenticated walks, assertion budgets), a Neon Noir
|
|
13
|
+
visual identity, a rewritten README with four refreshed translations, and an installer that
|
|
14
|
+
delegates to the Vercel skills CLI. The scanner's findings and their wording are unchanged.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- **`--caps` for the MCP server.** Five capabilities (`scan`, `walk`, `discover`, `report`,
|
|
19
|
+
`install`) narrow the registered tool set and the unified `sniff` tool's `mode` enum. The default
|
|
20
|
+
grants all five, so an existing config keeps its exact tool list and registration order. Unknown or
|
|
21
|
+
empty lists exit 1 on stderr. Logic lives in `src/mcp/caps.ts`; 14 tests, three of which drive a
|
|
22
|
+
real MCP client over `InMemoryTransport` and assert the actual `tools/list` result.
|
|
23
|
+
- **`--storage-state <path>` for walking a logged-in app.** Threaded through `browserConfigSchema`,
|
|
24
|
+
the CLI flag, both crawl contexts, `BrowserRunner`, and the MCP walk. Cookie values, localStorage
|
|
25
|
+
values, JSON string leaves inside them, indexedDB strings, percent-encoded forms, and
|
|
26
|
+
`Authorization` header values are redacted from progress output, screenshot filenames, the returned
|
|
27
|
+
report, `saveResults`, and `saveReport`. Screenshot pixels are out of scope and stay unredacted.
|
|
28
|
+
21 tests, including one that plants four tokens across a report and asserts each appears zero times
|
|
29
|
+
in the written HTML and JSON.
|
|
30
|
+
- **An `assert` block in `sniff.config`.** `maxCritical`, `maxHigh`, `maxMedium`, `maxLow`,
|
|
31
|
+
`maxInfo`, and `maxTotal` cap findings by severity. Additive only: it can turn a pass into a
|
|
32
|
+
failure, never the reverse, and an absent block behaves exactly as before. Enforced on the command
|
|
33
|
+
line by the walk, the public `sniff scan`, the browser mode, and discovery. 31 tests.
|
|
34
|
+
- **Neon Noir visual identity.** New `hero-dark.svg` and `hero-light.svg` for the README first
|
|
35
|
+
screen, `logo-mark.png` and `logo-mark-512.png` as a square mark, and a rebuilt 1280x640
|
|
36
|
+
`social-preview.png`. `demo.svg`, `features-dark.svg`, `features-light.svg`, `how-it-works.svg`,
|
|
37
|
+
`logo-dark.svg`, `logo-light.svg`, and `social-preview.svg` were rebuilt in the new palette.
|
|
38
|
+
- **New docs**: `docs/editors.md`, `docs/authenticated-walks.md`, `docs/assert-budgets.md`,
|
|
39
|
+
`docs/comparison.md`, and `docs/faq.md`.
|
|
40
|
+
|
|
41
|
+
### Changed
|
|
42
|
+
|
|
43
|
+
- **`install.sh` delegates to the Vercel skills CLI** by default
|
|
44
|
+
(`npx --yes skills@1.5.23 add Aboudjem/sniff -a <agent> -y`). All 13 platform ids map to agent
|
|
45
|
+
codes that exist in the live supported-agents table, which also corrects four skills directories
|
|
46
|
+
the hand-maintained table had wrong. The clone-and-symlink path stays reachable as `--legacy` and
|
|
47
|
+
is selected automatically when `npx` is missing. `--update`, `--uninstall`, and `--no-mcp` work on
|
|
48
|
+
both paths.
|
|
49
|
+
- **README rewritten** from 452 lines to 180, to the plugin skeleton: one install block above the
|
|
50
|
+
first heading, one editor table in place of an eight-row matrix and seven per-editor `<details>`
|
|
51
|
+
blocks, and every image path absolute so it renders on npmjs.com. The comparison table, the metrics
|
|
52
|
+
history, and the long FAQ moved to `docs/comparison.md` and `docs/faq.md`.
|
|
53
|
+
- **All four translations** (`READMEs/zh-CN.md`, `ja.md`, `es.md`, `fr.md`) rewritten from the new
|
|
54
|
+
English source.
|
|
55
|
+
- **Plugin manifests** (`.claude-plugin`, `.cursor-plugin`, `.copilot-plugin`), `server.json`,
|
|
56
|
+
`package.json`, and `package-lock.json` all moved to 0.8.0 together. Previously `package.json` and
|
|
57
|
+
`server.json` sat at 0.7.1 while the three manifests read 0.7.0.
|
|
58
|
+
- **`skills/sniff-fix/SKILL.md` and `skills/sniff-report/SKILL.md`** now say in their bodies that
|
|
59
|
+
they are invoked by the `sniff` skill's own flow, that `user-invocable: false` is honored only by
|
|
60
|
+
Claude Code, and that other agents may surface them as standalone commands.
|
|
61
|
+
|
|
62
|
+
### Removed
|
|
63
|
+
|
|
64
|
+
- `.github/assets/sniff-diagram.svg`. `how-it-works.svg` draws the same five-step flow, and its name
|
|
65
|
+
was dropped from the copy loop in `.github/workflows/deploy-pages.yml`.
|
|
66
|
+
- The Star History block, the three social badges, and the built-on credit list from the README
|
|
67
|
+
footer.
|
|
68
|
+
|
|
69
|
+
### Fixed
|
|
70
|
+
|
|
71
|
+
- `READMEs/fr.md`: the French translation carried injected placeholder text and a corrupted install
|
|
72
|
+
command from an earlier machine-translation pass. All four translations are now generated from the
|
|
73
|
+
current English README, with code blocks, asset URLs, and commands verbatim.
|
|
74
|
+
- Em-dashes removed from `package.json`, `src/mcp/server.ts`, `src/mcp/handlers.ts`,
|
|
75
|
+
`src/cli/index.ts`, `src/cli/commands/crawl-command.ts`, `src/cli/commands/discover.ts`, and
|
|
76
|
+
`src/report/model.ts`.
|
|
77
|
+
|
|
78
|
+
## [0.7.0] - 2026-05-29
|
|
79
|
+
|
|
80
|
+
Portability and discoverability layer: a multi-CLI installer, auto-discovery manifests, a GitHub Pages demo, and localized READMEs, on top of the earlier documentation polish. No change to the scanner engine or its findings.
|
|
81
|
+
|
|
82
|
+
### Added
|
|
83
|
+
|
|
84
|
+
- Multi-CLI installer: `install.sh` and `install.ps1` symlink the `/sniff`, `/sniff-fix`, and `/sniff-report` skills into a target CLI's skills directory, with `--update` and `--uninstall` and a one-line curl install. The MCP server stays the universal fallback.
|
|
85
|
+
- Auto-discovery manifests: `.cursor-plugin/plugin.json` and `.copilot-plugin/plugin.json`, mirroring `.claude-plugin/plugin.json`.
|
|
86
|
+
- GitHub Pages demo: `site/index.html` plus `.github/workflows/deploy-pages.yml`, reusing the existing demo assets and a sample report.
|
|
87
|
+
- README: a language-switcher row, a multi-platform install matrix with a one-line curl, an npm downloads badge, and a Star History chart.
|
|
88
|
+
- Localized READMEs under `READMEs/` for zh-CN, ja, es, and fr (machine-assisted; English stays the source of truth).
|
|
89
|
+
- Demo video: `.github/assets/demo.gif` (hero) plus an `.mp4` and an embed guide.
|
|
90
|
+
|
|
91
|
+
### Changed
|
|
92
|
+
|
|
93
|
+
- Rebuilt the features and hero SVGs around the flow-walk model, and removed emoji from them.
|
|
94
|
+
- Named the slash commands and MCP tools in the README.
|
|
95
|
+
|
|
96
|
+
### Removed
|
|
97
|
+
|
|
98
|
+
- Stale pre-0.6.0 SVG assets and the internal rebuild docs.
|
|
99
|
+
|
|
100
|
+
### Fixed
|
|
101
|
+
|
|
102
|
+
- `.github/FUNDING.yml`: corrected the GitHub Sponsors handle to `Aboudjem` (the previous value did not resolve).
|
|
103
|
+
- Animated SVGs now respect `prefers-reduced-motion`.
|
|
104
|
+
- Removed sentence-break em-dashes from the docs.
|
|
105
|
+
|
|
10
106
|
## [0.6.1] - 2026-05-28
|
|
11
107
|
|
|
12
108
|
Alignment release: no behaviour changes. Fixes the release pipeline so future tags can publish to npm,
|
package/NOTICE
CHANGED
|
@@ -5,7 +5,7 @@ This product includes software developed by Adam Boudj.
|
|
|
5
5
|
|
|
6
6
|
If you use Sniff in your project, a mention or attribution is appreciated:
|
|
7
7
|
- In your README, docs, or project credits
|
|
8
|
-
- "QA powered by Sniff (https://github.com/
|
|
8
|
+
- "QA powered by Sniff (https://github.com/Aboudjem/sniff)"
|
|
9
9
|
|
|
10
10
|
Third-party licenses:
|
|
11
11
|
- Playwright (Apache-2.0) - https://playwright.dev
|
package/README.md
CHANGED
|
@@ -1,392 +1,181 @@
|
|
|
1
1
|
<picture>
|
|
2
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/
|
|
3
|
-
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/
|
|
4
|
-
<img alt="
|
|
2
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/hero-dark.svg">
|
|
3
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/hero-light.svg">
|
|
4
|
+
<img alt="sniff" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/hero-light.svg" width="100%">
|
|
5
5
|
</picture>
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
|
-
<a href="https://www.npmjs.com/package/sniff-qa"><img src="https://img.shields.io/npm/v/sniff-qa?color=
|
|
9
|
-
<a href="
|
|
10
|
-
<a href="
|
|
11
|
-
<a href="https://
|
|
12
|
-
<a href="https://github.com/Aboudjem/10x"><img src="https://img.shields.io/badge/10x-marketplace-ef4444?style=flat-square" alt="10x marketplace"></a>
|
|
13
|
-
<a href="https://github.com/Aboudjem/sniff/stargazers"><img src="https://img.shields.io/github/stars/Aboudjem/sniff?style=flat-square&color=ef4444" alt="Stars"></a>
|
|
8
|
+
<a href="https://www.npmjs.com/package/sniff-qa"><img src="https://img.shields.io/npm/v/sniff-qa?style=flat-square&color=FF006E&logo=npm&label=npm" alt="npm version"></a>
|
|
9
|
+
<a href="https://github.com/Aboudjem/sniff/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Aboudjem/sniff/ci.yml?style=flat-square&color=00D4FF&label=CI" alt="CI"></a>
|
|
10
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-7C3AED?style=flat-square" alt="License Apache 2.0"></a>
|
|
11
|
+
<a href="https://github.com/Aboudjem/sniff/stargazers"><img src="https://img.shields.io/github/stars/Aboudjem/sniff?style=flat-square&color=2BE8C8" alt="Stars"></a>
|
|
14
12
|
</p>
|
|
15
13
|
|
|
16
|
-
<p align="center"><b>
|
|
14
|
+
<p align="center"><b>English</b> · <a href="READMEs/zh-CN.md">简体中文</a> · <a href="READMEs/ja.md">日本語</a> · <a href="READMEs/es.md">Español</a> · <a href="READMEs/fr.md">Français</a></p>
|
|
17
15
|
|
|
18
|
-
<p align="center">
|
|
19
|
-
<a href="#get-started">Get started</a> ·
|
|
20
|
-
<a href="#what-it-finds">What it finds</a> ·
|
|
21
|
-
<a href="#why-you-can-trust-it">Why trust it</a> ·
|
|
22
|
-
<a href="#how-it-works">How it works</a> ·
|
|
23
|
-
<a href="#demo">Demo</a> ·
|
|
24
|
-
<a href="#faq">FAQ</a>
|
|
25
|
-
</p>
|
|
26
|
-
|
|
27
|
-
<picture>
|
|
28
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/sniff-diagram.svg">
|
|
29
|
-
<img alt="Sniff flow: your running app -> headless browser walk -> findings with proof" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/sniff-diagram.svg" width="100%">
|
|
30
|
-
</picture>
|
|
31
|
-
|
|
32
|
-
---
|
|
33
|
-
|
|
34
|
-
## What is this?
|
|
35
|
-
|
|
36
|
-
Sniff is an autonomous QA scanner. You point it at a running web app and it **walks your app's real user flows in a real (headless) browser** — clicking buttons, filling forms, following links — and reports what's actually broken.
|
|
16
|
+
<p align="center"><b>Point it at your running app. It walks your real user flows in a real browser and tells you what is actually broken, with proof.</b></p>
|
|
37
17
|
|
|
38
|
-
|
|
18
|
+
<p align="center"><a href="#what-it-does">What it does</a> · <a href="#install">Install</a> · <a href="#use-it">Use it</a> · <a href="#what-you-get">What you get</a> · <a href="#works-in-your-editor">Works in your editor</a> · <a href="#good-to-know">Good to know</a></p>
|
|
39
19
|
|
|
40
|
-
|
|
20
|
+
<img alt="sniff walking a buggy app and streaming findings with severity, confidence, steps to reproduce, and a fix" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/demo.gif" width="100%">
|
|
41
21
|
|
|
42
22
|
```bash
|
|
43
|
-
|
|
23
|
+
claude plugin marketplace add Aboudjem/10x
|
|
24
|
+
claude plugin install sniff@10x
|
|
44
25
|
```
|
|
45
26
|
|
|
46
|
-
|
|
27
|
+
## What it does
|
|
47
28
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
29
|
+
Most linters read your source without ever running your app, and end-to-end frameworks ask you to
|
|
30
|
+
write and maintain the tests yourself. sniff opens your running app in a real browser, clicks and
|
|
31
|
+
fills things like a user would, and judges what actually happened.
|
|
51
32
|
|
|
52
|
-
|
|
33
|
+
- **It finds 12 classes of bugs**, from HTTP 500 routes and dead links to placeholder data, dead
|
|
34
|
+
submit buttons, forms wiped by the back button, stuck spinners, and mobile overflow.
|
|
35
|
+
- **It proves every one.** Every finding carries the route and the ordered steps that produced it,
|
|
36
|
+
plus the screenshot and the console or network excerpt the check captured. No steps, no finding.
|
|
37
|
+
- **It has been measured.** On a fixture app planted with 21 bugs across all 12 classes, plus a
|
|
38
|
+
clean control page, sniff finds 21 of 21 and reports nothing on the control page.
|
|
53
39
|
|
|
54
|
-
|
|
40
|
+
## Install
|
|
55
41
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
### 1. Start your app
|
|
42
|
+
The block above is the Claude Code path, through the [10x marketplace](https://github.com/Aboudjem/10x).
|
|
43
|
+
For any other agent, the Vercel skills CLI installs the same three skills:
|
|
59
44
|
|
|
60
45
|
```bash
|
|
61
|
-
|
|
46
|
+
npx skills add Aboudjem/sniff
|
|
62
47
|
```
|
|
63
48
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
In another terminal:
|
|
49
|
+
To use it as a plain command line tool, with no editor involved:
|
|
67
50
|
|
|
68
51
|
```bash
|
|
69
|
-
npx sniff-qa --url http://localhost:3000
|
|
52
|
+
npx sniff-qa --url http://localhost:3000
|
|
70
53
|
```
|
|
71
54
|
|
|
72
|
-
|
|
55
|
+
The npm package is `sniff-qa` and the binary it installs is `sniff`. Do not run `npx sniff`, which
|
|
56
|
+
is an unrelated package.
|
|
73
57
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
> **Found bugs? It exits non-zero — on purpose.** A walk that finds issues exits with code `1` so CI fails the build; it is **not** a crash (you'll see a `✓ Scan complete` line). Pass `--fail-on none` to always exit `0`.
|
|
58
|
+
<details>
|
|
59
|
+
<summary>Node version, project install, and CI</summary>
|
|
79
60
|
|
|
80
|
-
|
|
61
|
+
Node.js 22 or newer. `npm install -D sniff-qa` adds it to a project's devDependencies, and
|
|
62
|
+
`npx sniff-qa ci` writes a GitHub Actions workflow with browser caching and report artifacts.
|
|
63
|
+
</details>
|
|
81
64
|
|
|
82
|
-
|
|
65
|
+
## Use it
|
|
83
66
|
|
|
84
|
-
|
|
67
|
+
**1. Start your app,** with whatever dev server your project already uses.
|
|
85
68
|
|
|
86
69
|
```bash
|
|
87
|
-
|
|
70
|
+
npm run dev
|
|
88
71
|
```
|
|
89
72
|
|
|
90
|
-
**
|
|
73
|
+
**2. Walk it,** from a second terminal. sniff auto-detects a dev server on the common ports, so
|
|
74
|
+
`--url` is optional, but passing it takes the guesswork out.
|
|
91
75
|
|
|
92
76
|
```bash
|
|
93
|
-
npx sniff-qa
|
|
77
|
+
npx sniff-qa --url http://localhost:3000
|
|
94
78
|
```
|
|
95
79
|
|
|
96
|
-
|
|
80
|
+
**3. Read the findings.** They print grouped by severity. Below is an abridged real run against this
|
|
81
|
+
repo's own planted-bug fixture, from `npx sniff-qa --url http://localhost:4321 --ci --max-pages 12`:
|
|
97
82
|
|
|
98
|
-
|
|
83
|
+
```text
|
|
84
|
+
sniff v0.8.0 walking http://localhost:4321
|
|
85
|
+
|
|
86
|
+
26 findings (+1 low-confidence hidden; use --all)
|
|
99
87
|
|
|
100
|
-
|
|
88
|
+
CRITICAL (1)
|
|
89
|
+
• [confirmed] Page returns HTTP 500
|
|
90
|
+
/crash (route/broken-page)
|
|
91
|
+
- Navigate to /crash
|
|
92
|
+
- Server responded with HTTP 500
|
|
93
|
+
fix: The route throws server-side. Check the server logs/handler for this path and return a valid page or a proper error page.
|
|
94
|
+
shot: sniff-reports/crawl/_crash-desktop.png
|
|
101
95
|
|
|
102
|
-
|
|
96
|
+
✓ Scan complete: 26 issue(s) found. Exit code 1 so CI fails on bugs; pass --fail-on none to always exit 0.
|
|
97
|
+
```
|
|
103
98
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
| 1 | **Broken pages / routes** | 4xx/5xx responses, blank renders, crash screens |
|
|
107
|
-
| 2 | **Broken links** | Dead internal and external links |
|
|
108
|
-
| 3 | **Console & network errors** | Uncaught exceptions and failed requests *during interaction* |
|
|
109
|
-
| 4 | **Empty & fake data** | Missing data, plus placeholders like `lorem ipsum`, `TODO`, `test@test.com` |
|
|
110
|
-
| 5 | **Broken forms** | Dead submit buttons, validation that never fires |
|
|
111
|
-
| 6 | **State loss** | Fill a form, hit back, and it's wiped |
|
|
112
|
-
| 7 | **Flow regressions / dead-ends** | A journey that can't be completed |
|
|
113
|
-
| 8 | **Bad loading & error states** | Infinite spinners, missing error states |
|
|
114
|
-
| 9 | **Broken async outcomes** | Submitted but no success feedback (flagged "needs out-of-band verification") |
|
|
115
|
-
| 10 | **Responsive issues** | Overflow and tiny tap targets (a 375px mobile pass) |
|
|
116
|
-
| 11 | **Accessibility** | Missing alt text and labels, contrast — via [axe-core](https://github.com/dequelabs/axe-core) |
|
|
117
|
-
| 12 | **Unclear primary actions** | The main call-to-action is buried or ambiguous |
|
|
99
|
+
Add `--report` for a self-contained HTML page you can send to someone. Run `npx sniff-qa doctor` if
|
|
100
|
+
the environment looks wrong.
|
|
118
101
|
|
|
119
|
-
|
|
102
|
+
<img alt="How sniff works: crawl, act, assert, prove, report" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/how-it-works.svg" width="100%">
|
|
120
103
|
|
|
121
|
-
|
|
122
|
-
- **A severity** — so you fix the right thing first.
|
|
123
|
-
- **A confidence** — `confirmed`, `likely`, or `uncertain`. Uncertain findings are hidden by default; add `--all` to see them.
|
|
124
|
-
- **A suggested fix.**
|
|
104
|
+
## What you get
|
|
125
105
|
|
|
126
106
|
<picture>
|
|
127
107
|
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/features-dark.svg">
|
|
128
108
|
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/features-light.svg">
|
|
129
|
-
<img alt="The
|
|
109
|
+
<img alt="The 12 classes of bugs sniff finds" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/features-light.svg" width="100%">
|
|
130
110
|
</picture>
|
|
131
111
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
Most scanners drown you in false positives until you stop reading them. Sniff is built the opposite way.
|
|
137
|
-
|
|
138
|
-
We measured it on a fixture app planted with **21 bugs across all 12 classes**, plus a clean control page that should produce zero findings:
|
|
112
|
+
- **A terminal report** grouped by severity, each finding with steps, a fix, and a screenshot path.
|
|
113
|
+
- **A shareable file**, a self-contained HTML report with `--report` or JSON with `--json`.
|
|
114
|
+
- **An exit code**, non-zero when findings reach the `--fail-on` severity, so CI fails on real bugs.
|
|
115
|
+
- **A confidence label** on each. `uncertain` is hidden from the terminal unless you pass `--all`.
|
|
139
116
|
|
|
140
|
-
|
|
141
|
-
|:--|:--|:--|
|
|
142
|
-
| Bugs found | 9 / 21 (43%) | **21 / 21 (100%)** |
|
|
143
|
-
| Precision | ~13% | **100%** |
|
|
144
|
-
| False positives | 125 | **0** |
|
|
145
|
-
| Findings on the clean page | — | **0** |
|
|
146
|
-
| Flagship command | crashed | works |
|
|
117
|
+
New in 0.8.0:
|
|
147
118
|
|
|
148
|
-
|
|
119
|
+
- `--caps scan,report` narrows the MCP server to the source scan and the saved-results reader, with
|
|
120
|
+
no browser launch and no browser download.
|
|
121
|
+
- `--storage-state auth.json` walks a logged-in app. Cookie and token values from that file are
|
|
122
|
+
redacted from the text of every written report, though not from screenshot pixels.
|
|
123
|
+
- An `assert` block in `sniff.config` caps findings by severity (`maxCritical`, `maxHigh`,
|
|
124
|
+
`maxTotal`), enforced on the command line by the walk, the source scan, and discovery.
|
|
149
125
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
- A first-party **noise filter** drops the junk that isn't your bug — favicons, analytics, hot-module-reload chatter, expected auth redirects, engine aborts.
|
|
153
|
-
- Accessibility findings are backed by **axe-core**, which is zero-false-positive by design.
|
|
154
|
-
- **Uncertain findings are suppressed by default** (use `--all` to see them).
|
|
155
|
-
- A broken page is reported **once**, not re-flagged on every link that points to it.
|
|
156
|
-
|
|
157
|
-
If Sniff can't prove a bug, it doesn't claim one.
|
|
158
|
-
|
|
159
|
-
---
|
|
126
|
+
## Works in your editor
|
|
160
127
|
|
|
161
|
-
|
|
128
|
+
Works in Claude Code, Cursor, Codex, Copilot, Gemini CLI, and 70+ other agents through
|
|
129
|
+
`npx skills add`. The skills are Markdown, so they run on whatever model your editor points at.
|
|
162
130
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
|
166
|
-
|
|
167
|
-
|
|
|
168
|
-
|
|
|
169
|
-
|
|
|
170
|
-
| Accessibility (axe-core) | **Yes** | No | **Yes** | Manual | Some |
|
|
171
|
-
| Empty / placeholder / fake data | **Yes** | No | No | No | No |
|
|
172
|
-
| State-loss (back-button wipes a form) | **Yes** | No | No | Manual | Manual |
|
|
173
|
-
| One-shot reproduction proof per finding | **Yes** | No | Partial | No | Varies |
|
|
174
|
-
| Self-contained HTML report | **Yes** | No | Partial | No | Dashboard |
|
|
175
|
-
| Runs locally, no account, no API key | **Yes** | Yes | Yes | Yes | No (service) |
|
|
176
|
-
|
|
177
|
-
What Sniff uniquely does in one command: catch **empty/placeholder data**, **state-loss**, and **broken async outcomes** — and hand you a single proof report — with **no scripts to write and no service to sign up for**.
|
|
178
|
-
|
|
179
|
-
---
|
|
180
|
-
|
|
181
|
-
## Commands
|
|
182
|
-
|
|
183
|
-
```
|
|
184
|
-
sniff Walk your app (auto-detects the dev server). The default.
|
|
185
|
-
sniff --url <url> Walk a specific URL
|
|
186
|
-
sniff scan Source-only scan, no browser (placeholders, TODOs, dead links, etc.)
|
|
187
|
-
sniff report Show the results from the last run
|
|
188
|
-
sniff doctor Check your environment (Node, browser, config, dev server)
|
|
189
|
-
sniff ci Generate a GitHub Actions workflow
|
|
190
|
-
sniff fix Auto-fix safe issues (console.log, debugger, etc.)
|
|
191
|
-
sniff --help Show every command and flag
|
|
192
|
-
sniff --version Show the version
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
### Useful flags
|
|
196
|
-
|
|
197
|
-
| Flag | What it does |
|
|
198
|
-
|:-----|:-------------|
|
|
199
|
-
| `--url <url>` | Walk this URL instead of auto-detecting |
|
|
200
|
-
| `--report` | Write a self-contained HTML report to `sniff-reports/sniff-report.html` |
|
|
201
|
-
| `--all` | Also show low-confidence (`uncertain`) findings |
|
|
202
|
-
| `--max-pages <n>` | Cap how many pages to walk (default: 25) |
|
|
203
|
-
| `--no-mobile` | Skip the 375px responsive pass |
|
|
204
|
-
| `--headed` | Show the browser window while it walks |
|
|
205
|
-
| `--json` | Machine-readable JSON output |
|
|
206
|
-
| `--ci` | CI mode (stable output, non-interactive) |
|
|
207
|
-
| `--fail-on <sev>` | Exit non-zero on findings at or above this severity |
|
|
208
|
-
|
|
209
|
-
---
|
|
210
|
-
|
|
211
|
-
## Demo
|
|
212
|
-
|
|
213
|
-
A real run against a buggy app — 21 real issues, zero false positives, every finding with severity, confidence, reproduction steps, and a fix:
|
|
214
|
-
|
|
215
|
-
<img alt="Sniff walking a buggy app and reporting 21 real issues with zero false positives" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/demo.svg" width="100%">
|
|
216
|
-
|
|
217
|
-
---
|
|
218
|
-
|
|
219
|
-
## Use it from your AI editor
|
|
220
|
-
|
|
221
|
-
Sniff ships as an MCP server too. Add it once, then just ask your assistant *"scan this project for bugs"* or *"walk my app."* If your app is running, Sniff auto-detects it — you don't have to pass a URL.
|
|
222
|
-
|
|
223
|
-
**One unified `sniff` tool, three modes:**
|
|
224
|
-
|
|
225
|
-
- `walk` — **recommended.** Walks your running app's real flows (the flow-walk above).
|
|
226
|
-
- `scan` — source-only scan, no browser.
|
|
227
|
-
- `report` — show the last run's results.
|
|
228
|
-
|
|
229
|
-
(`run` and `discover` are legacy modes kept for back-compat.)
|
|
131
|
+
| Agent | One-line install |
|
|
132
|
+
|:--|:--|
|
|
133
|
+
| Claude Code | `claude plugin install sniff@10x` |
|
|
134
|
+
| Any of 70+ agents | `npx skills add Aboudjem/sniff` |
|
|
135
|
+
| Codex, Gemini CLI, OpenCode, Pi | `./install.sh codex` |
|
|
136
|
+
| VS Code (Copilot) | `./install.sh copilot` |
|
|
137
|
+
| Everything else | see [docs/editors.md](docs/editors.md) |
|
|
230
138
|
|
|
231
139
|
<details>
|
|
232
|
-
<summary
|
|
233
|
-
|
|
234
|
-
One-command plugin install from the [10x marketplace](https://github.com/Aboudjem/10x):
|
|
235
|
-
|
|
236
|
-
```bash
|
|
237
|
-
claude plugin marketplace add Aboudjem/10x
|
|
238
|
-
claude plugin install sniff@10x
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
Or add just the MCP server:
|
|
140
|
+
<summary>Add it as an MCP server instead</summary>
|
|
242
141
|
|
|
243
142
|
```bash
|
|
244
143
|
claude mcp add sniff-qa npx -- -y sniff-qa --mcp
|
|
245
|
-
```
|
|
246
|
-
</details>
|
|
247
|
-
|
|
248
|
-
<details>
|
|
249
|
-
<summary><b>Cursor</b></summary>
|
|
250
|
-
|
|
251
|
-
Add to `~/.cursor/mcp.json`:
|
|
252
|
-
|
|
253
|
-
```json
|
|
254
|
-
{ "mcpServers": { "sniff-qa": { "command": "npx", "args": ["-y", "sniff-qa", "--mcp"] } } }
|
|
255
|
-
```
|
|
256
|
-
</details>
|
|
257
|
-
|
|
258
|
-
<details>
|
|
259
|
-
<summary><b>VS Code (Copilot)</b></summary>
|
|
260
|
-
|
|
261
|
-
Add to `.vscode/mcp.json`:
|
|
262
|
-
|
|
263
|
-
```json
|
|
264
|
-
{ "servers": { "sniff-qa": { "type": "stdio", "command": "npx", "args": ["-y", "sniff-qa", "--mcp"] } } }
|
|
265
|
-
```
|
|
266
|
-
</details>
|
|
267
|
-
|
|
268
|
-
<details>
|
|
269
|
-
<summary><b>Codex CLI</b></summary>
|
|
270
|
-
|
|
271
|
-
```bash
|
|
272
144
|
codex mcp add sniff-qa -- npx -y sniff-qa --mcp
|
|
273
145
|
```
|
|
274
|
-
</details>
|
|
275
146
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
Add to `~/.gemini/mcp_config.json`:
|
|
280
|
-
|
|
281
|
-
```json
|
|
282
|
-
{ "mcpServers": { "sniff-qa": { "command": "npx", "args": ["-y", "sniff-qa", "--mcp"] } } }
|
|
283
|
-
```
|
|
147
|
+
Cursor, VS Code, Gemini CLI, Windsurf, Continue, OpenCode, and Zed take the same command as a JSON
|
|
148
|
+
or TOML entry. Every per-editor snippet is in [docs/editors.md](docs/editors.md).
|
|
284
149
|
</details>
|
|
285
150
|
|
|
286
|
-
|
|
287
|
-
<summary><b>Windsurf</b></summary>
|
|
151
|
+
## Good to know
|
|
288
152
|
|
|
289
|
-
|
|
153
|
+
> [!IMPORTANT]
|
|
154
|
+
> No API key, no account, no signup, and no AI provider unless you set one up yourself. Walking and
|
|
155
|
+
> scanning never edit your source. `sniff fix` is the only command that rewrites code, and only when
|
|
156
|
+
> you run it.
|
|
290
157
|
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
158
|
+
> [!NOTE]
|
|
159
|
+
> A walk clicks buttons and submits real forms, so it can create real data. Point it at a dev or
|
|
160
|
+
> staging app, not at production. The first walk also downloads a Chromium build and caches it, so
|
|
161
|
+
> that one run needs internet access.
|
|
295
162
|
|
|
296
|
-
|
|
297
|
-
|
|
163
|
+
- **It wants a running app.** With no dev server up it falls back to a source-only scan and tells
|
|
164
|
+
you how to start the real walk. `npx sniff-qa scan` runs that scan on purpose.
|
|
165
|
+
- **Dead-link checking follows external links,** so a walk makes requests to the third-party URLs
|
|
166
|
+
your own pages already link to.
|
|
167
|
+
- **A walk that finds bugs exits 1** on purpose, so CI fails the build. That is not a crash.
|
|
168
|
+
`--fail-on none` turns off the severity gate, though an `assert` budget can still fail the run.
|
|
298
169
|
|
|
299
|
-
|
|
170
|
+
## Learn more
|
|
300
171
|
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
> The first browser-based walk downloads Chromium (~165 MB). Over MCP, Sniff returns a structured `needsSetup` payload instead of blocking the editor on a long download — run the install it shows you, then ask again.
|
|
172
|
+
- [docs/editors.md](docs/editors.md), install and MCP snippets for every supported agent
|
|
173
|
+
- [docs/authenticated-walks.md](docs/authenticated-walks.md), walking a logged-in app with `--storage-state`
|
|
174
|
+
- [docs/assert-budgets.md](docs/assert-budgets.md), capping findings by severity in `sniff.config`
|
|
175
|
+
- [docs/comparison.md](docs/comparison.md), how sniff differs from linters, link checkers, and E2E frameworks
|
|
176
|
+
- [docs/faq.md](docs/faq.md), the questions this page does not answer
|
|
177
|
+
- [CHANGELOG.md](CHANGELOG.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [LICENSE](LICENSE)
|
|
308
178
|
|
|
309
179
|
---
|
|
310
180
|
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
1. **Find the app.** Sniff auto-detects your running dev server (or you pass `--url`).
|
|
314
|
-
2. **Walk the flows.** It opens pages in a headless browser and interacts with them like a user — clicking, filling forms, following links — across desktop and a 375px mobile pass.
|
|
315
|
-
3. **Watch everything.** It records console errors, failed network requests, broken renders, missing feedback, and accessibility issues as it goes.
|
|
316
|
-
4. **Filter the noise.** The first-party noise filter and axe-core drop the false positives; uncertain findings are held back.
|
|
317
|
-
5. **Report with proof.** Each surviving finding gets a severity, a confidence, reproduction steps, a screenshot, and a suggested fix — in the terminal and an optional HTML report.
|
|
318
|
-
|
|
319
|
-
<img alt="How sniff works: crawl, act, assert, prove, report" src="https://raw.githubusercontent.com/Aboudjem/sniff/main/.github/assets/how-it-works.svg" width="100%">
|
|
320
|
-
|
|
321
|
-
---
|
|
322
|
-
|
|
323
|
-
## CI integration
|
|
324
|
-
|
|
325
|
-
Run Sniff in your pipeline and fail the build on real bugs:
|
|
326
|
-
|
|
327
|
-
```bash
|
|
328
|
-
npx sniff-qa --ci --fail-on high
|
|
329
|
-
```
|
|
330
|
-
|
|
331
|
-
Generate a ready-to-commit GitHub Actions workflow:
|
|
332
|
-
|
|
333
|
-
```bash
|
|
334
|
-
npx sniff-qa ci
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
This writes `.github/workflows/sniff.yml` with browser caching and report artifacts.
|
|
338
|
-
|
|
339
|
-
---
|
|
340
|
-
|
|
341
|
-
## FAQ
|
|
342
|
-
|
|
343
|
-
**Does it work without a dev server?**
|
|
344
|
-
Sniff is built to walk a *running* app, so that's where it shines. If no server is running, it doesn't fail silently — it runs a source-only scan and tells you exactly how to start the real walk (start your dev server or pass `--url`). You can also run `npx sniff-qa scan` to get the source scan on purpose.
|
|
345
|
-
|
|
346
|
-
**What gets downloaded on first run?**
|
|
347
|
-
The first time Sniff opens a browser, it downloads a Chromium build (~165 MB, one-time, then cached). You'll see the progress, and you need internet access for that first run. Nothing else is installed and no account is created.
|
|
348
|
-
|
|
349
|
-
**Do I need an API key?**
|
|
350
|
-
No. Sniff runs entirely on your machine with no API key and no signup. Your code and your app never leave your computer.
|
|
351
|
-
|
|
352
|
-
**How is it different from a linter?**
|
|
353
|
-
A linter reads your source files and never runs your app, so it can't see a dead submit button, an infinite spinner, a wiped form, or a 500 page. Sniff opens your real app, interacts with it, and reports what actually broke — with a screenshot and steps to reproduce.
|
|
354
|
-
|
|
355
|
-
**How is it different from Playwright codegen (or writing E2E tests)?**
|
|
356
|
-
Playwright codegen records a script that *you* author and maintain; it tests only the path you clicked. Sniff writes nothing for you to maintain — it explores your flows on its own and judges the outcome, catching things a recorded happy-path never checks (empty/placeholder data, state-loss, missing success feedback).
|
|
357
|
-
|
|
358
|
-
**Will it change my code?**
|
|
359
|
-
No, not during a walk. Walking and scanning are read-only. The separate `sniff fix` command applies safe auto-fixes (like stray `console.log`/`debugger`) and only when you run it.
|
|
360
|
-
|
|
361
|
-
**What stacks does it work with?**
|
|
362
|
-
Any web app you can open in a browser — React, Next.js, Vue, Svelte, Angular, Remix, SvelteKit, Astro, plain HTML, and more. It walks the rendered app, so the framework doesn't matter for the browser checks.
|
|
363
|
-
|
|
364
|
-
---
|
|
365
|
-
|
|
366
|
-
## Works first-class in
|
|
367
|
-
|
|
368
|
-
Claude Code · Cursor · VS Code (Copilot) · Codex · Gemini CLI · Windsurf · Continue.dev — via the MCP server (command `npx`, args `["-y", "sniff-qa", "--mcp"]`) or the CLI directly.
|
|
369
|
-
|
|
370
|
-
---
|
|
371
|
-
|
|
372
|
-
## Contributing
|
|
373
|
-
|
|
374
|
-
Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
375
|
-
|
|
376
|
-
---
|
|
377
|
-
|
|
378
|
-
<p align="center">
|
|
379
|
-
<sub>
|
|
380
|
-
Built on <a href="https://playwright.dev">Playwright</a> · <a href="https://github.com/dequelabs/axe-core">axe-core</a> · <a href="https://developer.chrome.com/docs/lighthouse">Lighthouse</a> · <a href="https://github.com/mapbox/pixelmatch">pixelmatch</a> · <a href="https://zod.dev">Zod</a> · <a href="https://github.com/modelcontextprotocol/typescript-sdk">MCP SDK</a>
|
|
381
|
-
</sub>
|
|
382
|
-
</p>
|
|
383
|
-
|
|
384
|
-
<p align="center">
|
|
385
|
-
<a href="https://www.linkedin.com/in/adam-boudjemaa/"><img src="https://img.shields.io/badge/LinkedIn-0A66C2?style=flat-square&logo=linkedin&logoColor=white" alt="LinkedIn"></a>
|
|
386
|
-
<a href="https://x.com/AdamBoudj"><img src="https://img.shields.io/badge/X-000000?style=flat-square&logo=x&logoColor=white" alt="X"></a>
|
|
387
|
-
<a href="https://adam-boudjemaa.com/"><img src="https://img.shields.io/badge/Website-ef4444?style=flat-square&logo=googlechrome&logoColor=white" alt="Website"></a>
|
|
388
|
-
</p>
|
|
389
|
-
|
|
390
|
-
<p align="center">
|
|
391
|
-
<sub>Built by <a href="https://github.com/Aboudjem">Adam Boudjemaa</a> · <a href="LICENSE">Apache 2.0</a></sub>
|
|
392
|
-
</p>
|
|
181
|
+
<p align="center"><sub>Built by <a href="https://github.com/Aboudjem">Adam Boudjemaa</a> · <a href="LICENSE">Apache 2.0</a> · standing on <a href="https://playwright.dev">Playwright</a> and <a href="https://github.com/dequelabs/axe-core">axe-core</a></sub></p>
|