argusqa-os 9.5.9 → 9.6.1
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/README.md +384 -1112
- package/glama.json +5 -1
- package/package.json +3 -3
- package/src/cli/init.js +8 -4
- package/src/cli/pr-validate.js +309 -0
- package/src/mcp-server.js +64 -2
- package/src/orchestration/dispatcher.js +1 -1
- package/src/orchestration/env-comparison.js +0 -1
- package/src/orchestration/orchestrator.js +5 -5
- package/src/orchestration/report-processor.js +1 -1
- package/src/orchestration/slack-notifier.js +1 -1
- package/src/orchestration/watch-mode.js +0 -4
- package/src/server/index.js +24 -2
- package/src/server/slash-command-handler.js +0 -1
- package/src/utils/a11y-deep-analyzer.js +0 -2
- package/src/utils/baseline-manager.js +3 -3
- package/src/utils/codebase-analyzer.js +3 -3
- package/src/utils/content-analyzer.js +1 -1
- package/src/utils/flow-runner.js +4 -4
- package/src/utils/github-reporter.js +1 -2
- package/src/utils/har-recorder.js +19 -14
- package/src/utils/pr-diff-analyzer.js +121 -0
- package/src/utils/route-discoverer.js +1 -1
- package/src/utils/security-analyzer.js +1 -1
- package/src/utils/seo-analyzer.js +1 -1
- package/src/utils/session-persistence.js +1 -1
- package/src/utils/visual-diff-analyzer.js +9 -4
package/README.md
CHANGED
|
@@ -1,1112 +1,384 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
#
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
#
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
|
83
|
-
|
|
|
84
|
-
| **
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
|
123
|
-
|
|
124
|
-
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
|
240
|
-
|
|
241
|
-
|
|
|
242
|
-
|
|
|
243
|
-
|
|
|
244
|
-
|
|
|
245
|
-
|
|
|
246
|
-
|
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
|
260
|
-
|
|
|
261
|
-
|
|
|
262
|
-
|
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
|
267
|
-
|
|
|
268
|
-
|
|
|
269
|
-
|
|
|
270
|
-
|
|
|
271
|
-
|
|
|
272
|
-
|
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
|
277
|
-
|
|
|
278
|
-
|
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
|
283
|
-
|
|
|
284
|
-
|
|
|
285
|
-
|
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
|
323
|
-
|
|
324
|
-
| **
|
|
325
|
-
| **
|
|
326
|
-
| **
|
|
327
|
-
| **
|
|
328
|
-
| **
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
|
337
|
-
|
|
338
|
-
|
|
|
339
|
-
|
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
## Prerequisites
|
|
386
|
-
|
|
387
|
-
| Requirement | Version | Notes |
|
|
388
|
-
| --- | --- | --- |
|
|
389
|
-
| Node.js | v20.19+ | Required by Chrome DevTools MCP |
|
|
390
|
-
| Chrome | Stable (current) | Must be installed |
|
|
391
|
-
| Claude Code | Latest | `npm install -g @anthropic-ai/claude-code` |
|
|
392
|
-
| Slack workspace | — | **Optional** — only needed if you want Slack reports. Without it, Argus generates a local `report.html` instead |
|
|
393
|
-
|
|
394
|
-
---
|
|
395
|
-
|
|
396
|
-
## One-Time Setup
|
|
397
|
-
|
|
398
|
-
### Option A — MCP Server (Claude Code / any MCP client)
|
|
399
|
-
|
|
400
|
-
No local install required. `npx` auto-downloads `argusqa-os` on first use.
|
|
401
|
-
|
|
402
|
-
#### 1. Register both MCP servers
|
|
403
|
-
|
|
404
|
-
Add to `.mcp.json` in your project root:
|
|
405
|
-
|
|
406
|
-
```json
|
|
407
|
-
{
|
|
408
|
-
"mcpServers": {
|
|
409
|
-
"chrome-devtools": {
|
|
410
|
-
"command": "npx",
|
|
411
|
-
"args": ["-y", "chrome-devtools-mcp@latest"]
|
|
412
|
-
},
|
|
413
|
-
"argus": {
|
|
414
|
-
"command": "npx",
|
|
415
|
-
"args": ["-y", "argusqa-os"]
|
|
416
|
-
}
|
|
417
|
-
}
|
|
418
|
-
}
|
|
419
|
-
```
|
|
420
|
-
|
|
421
|
-
Or via Claude Code CLI:
|
|
422
|
-
|
|
423
|
-
```bash
|
|
424
|
-
claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
|
|
425
|
-
claude mcp add argus -- npx -y argusqa-os
|
|
426
|
-
```
|
|
427
|
-
|
|
428
|
-
#### 2. Environment variables
|
|
429
|
-
|
|
430
|
-
Create a `.env` file in your project root:
|
|
431
|
-
|
|
432
|
-
```env
|
|
433
|
-
TARGET_DEV_URL=http://localhost:3000
|
|
434
|
-
TARGET_STAGING_URL=https://staging.example.com # optional — enables argus_compare
|
|
435
|
-
```
|
|
436
|
-
|
|
437
|
-
#### 3. Start Chrome with remote debugging
|
|
438
|
-
|
|
439
|
-
```bash
|
|
440
|
-
# macOS
|
|
441
|
-
open -a "Google Chrome" --args --remote-debugging-port=9222 --headless=new
|
|
442
|
-
|
|
443
|
-
# Windows (PowerShell)
|
|
444
|
-
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --headless=new --no-sandbox --disable-gpu --user-data-dir="$env:TEMP\chrome-argus"
|
|
445
|
-
|
|
446
|
-
# Linux
|
|
447
|
-
google-chrome --remote-debugging-port=9222 --headless=new --no-sandbox
|
|
448
|
-
```
|
|
449
|
-
|
|
450
|
-
#### 4. Slack notifications (optional)
|
|
451
|
-
|
|
452
|
-
> Skip to use local `report.html` mode — Argus generates a self-contained HTML report when Slack is not configured.
|
|
453
|
-
|
|
454
|
-
1. [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → name it **BugBot**
|
|
455
|
-
2. **OAuth & Permissions** → Bot Token Scopes: `chat:write`, `files:write`, `files:read`
|
|
456
|
-
3. Install to workspace → copy **Bot User OAuth Token** (`xoxb-...`) to `.env` as `SLACK_BOT_TOKEN`
|
|
457
|
-
4. Create `#bugs-critical`, `#bugs-warnings`, `#bugs-digest` and `/invite @BugBot` in each
|
|
458
|
-
|
|
459
|
-
```env
|
|
460
|
-
SLACK_BOT_TOKEN=xoxb-...
|
|
461
|
-
SLACK_CHANNEL_CRITICAL=C0000000000
|
|
462
|
-
SLACK_CHANNEL_WARNINGS=C0000000001
|
|
463
|
-
SLACK_CHANNEL_DIGEST=C0000000002
|
|
464
|
-
```
|
|
465
|
-
|
|
466
|
-
---
|
|
467
|
-
|
|
468
|
-
### Option B — npm Package (dev dependency / CI/CD)
|
|
469
|
-
|
|
470
|
-
#### 1. Install
|
|
471
|
-
|
|
472
|
-
```bash
|
|
473
|
-
npm install --save-dev argusqa-os
|
|
474
|
-
```
|
|
475
|
-
|
|
476
|
-
#### 2. Environment variables
|
|
477
|
-
|
|
478
|
-
Run the interactive wizard to auto-generate `.env` and `src/config/targets.js`:
|
|
479
|
-
|
|
480
|
-
```bash
|
|
481
|
-
npx argus
|
|
482
|
-
```
|
|
483
|
-
|
|
484
|
-
The wizard detects your framework (Next.js / React Router), discovers routes from `sitemap.xml` and your file structure, and optionally collects Slack and GitHub credentials.
|
|
485
|
-
|
|
486
|
-
**Alternative — manual setup:** Create a `.env` with `TARGET_DEV_URL` and optionally `TARGET_STAGING_URL`.
|
|
487
|
-
|
|
488
|
-
#### 3. Start Chrome with remote debugging
|
|
489
|
-
|
|
490
|
-
Same as Option A — see above.
|
|
491
|
-
|
|
492
|
-
#### 4. Slack notifications (optional)
|
|
493
|
-
|
|
494
|
-
Same as Option A — see above.
|
|
495
|
-
|
|
496
|
-
---
|
|
497
|
-
|
|
498
|
-
### Option C — Clone the Repository (full source / contributors)
|
|
499
|
-
|
|
500
|
-
#### 1. Clone and install
|
|
501
|
-
|
|
502
|
-
```bash
|
|
503
|
-
git clone https://github.com/ironclawdevs27/Argus.git
|
|
504
|
-
cd Argus
|
|
505
|
-
npm install
|
|
506
|
-
npm run setup # creates reports/ directory
|
|
507
|
-
```
|
|
508
|
-
|
|
509
|
-
#### 2. Environment variables
|
|
510
|
-
|
|
511
|
-
**Recommended — use the interactive setup wizard:**
|
|
512
|
-
|
|
513
|
-
```bash
|
|
514
|
-
npm run init
|
|
515
|
-
```
|
|
516
|
-
|
|
517
|
-
**Alternative — manual setup:**
|
|
518
|
-
|
|
519
|
-
```bash
|
|
520
|
-
cp .env.example .env
|
|
521
|
-
```
|
|
522
|
-
|
|
523
|
-
Open `.env` and fill in:
|
|
524
|
-
|
|
525
|
-
```env
|
|
526
|
-
TARGET_DEV_URL=http://localhost:3000
|
|
527
|
-
TARGET_STAGING_URL=https://staging.example.com # leave blank → CSS-only analysis mode
|
|
528
|
-
|
|
529
|
-
# Slack — OPTIONAL. Omit to get a local report.html instead.
|
|
530
|
-
# SLACK_BOT_TOKEN=xoxb-...
|
|
531
|
-
# SLACK_SIGNING_SECRET=...
|
|
532
|
-
# SLACK_CHANNEL_CRITICAL=C0000000000
|
|
533
|
-
# SLACK_CHANNEL_WARNINGS=C0000000001
|
|
534
|
-
# SLACK_CHANNEL_DIGEST=C0000000002
|
|
535
|
-
```
|
|
536
|
-
|
|
537
|
-
#### 3. Configure routes
|
|
538
|
-
|
|
539
|
-
If you ran `npm run init` — skip this step.
|
|
540
|
-
|
|
541
|
-
Otherwise, edit [src/config/targets.js](src/config/targets.js):
|
|
542
|
-
|
|
543
|
-
```js
|
|
544
|
-
export const routes = [
|
|
545
|
-
{ path: '/', name: 'Home', critical: true, waitFor: 'main' },
|
|
546
|
-
{ path: '/login', name: 'Login', critical: true, waitFor: 'form' },
|
|
547
|
-
{ path: '/dashboard', name: 'Dashboard', critical: true, waitFor: '[data-testid="dashboard"]' },
|
|
548
|
-
{ path: '/settings', name: 'Settings', critical: false, waitFor: null },
|
|
549
|
-
];
|
|
550
|
-
```
|
|
551
|
-
|
|
552
|
-
- `critical: true` — errors on this route go to `#bugs-critical`
|
|
553
|
-
- `waitFor` — CSS selector Argus waits for before capturing (signals the page is ready)
|
|
554
|
-
|
|
555
|
-
#### 4. Connect Chrome DevTools MCP to Claude Code
|
|
556
|
-
|
|
557
|
-
```bash
|
|
558
|
-
claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
|
|
559
|
-
```
|
|
560
|
-
|
|
561
|
-
Verify — ask Claude: *"List all open Chrome pages"* — you should see your tabs.
|
|
562
|
-
|
|
563
|
-
#### 5. Start Chrome with remote debugging
|
|
564
|
-
|
|
565
|
-
Same as Option A — see above.
|
|
566
|
-
|
|
567
|
-
#### 6. Slack notifications (optional)
|
|
568
|
-
|
|
569
|
-
Same as Option A — see above.
|
|
570
|
-
|
|
571
|
-
---
|
|
572
|
-
|
|
573
|
-
## Running Argus
|
|
574
|
-
|
|
575
|
-
### Option A — Via MCP (Claude Code / any MCP client)
|
|
576
|
-
|
|
577
|
-
Ask Claude directly — no terminal needed.
|
|
578
|
-
|
|
579
|
-
**Available tools:**
|
|
580
|
-
|
|
581
|
-
| Tool | What it does |
|
|
582
|
-
| --- | --- |
|
|
583
|
-
| `argus_audit` | Fast QA pass — JS errors, network failures, accessibility, SEO, security, CSS, content |
|
|
584
|
-
| `argus_audit_full` | Deep QA pass — adds Lighthouse, responsive layout checks across 4 viewports, memory leak detection, hover-state bug detection, and accessibility tree snapshot |
|
|
585
|
-
| `argus_compare` | Diff dev vs staging — screenshots, findings delta, environment regressions |
|
|
586
|
-
| `argus_last_report` | Return the last saved JSON report without re-running a scan |
|
|
587
|
-
| `argus_watch_snapshot` | Snapshot the currently open Chrome tab without navigating — raw console + network capture |
|
|
588
|
-
| `argus_get_context` | Capture everything broken on the open tab, formatted as a diagnostic context for Claude to diagnose and suggest fixes |
|
|
589
|
-
| `argus_design_audit` | Figma design-to-implementation fidelity audit — 13 finding types across color, typography, spacing, per-corner radius, position drift, stroke, shadow (color+spread), opacity, gap, and text content |
|
|
590
|
-
| `argus_visual_diff` | Screenshot baseline comparison — first call saves baseline; subsequent calls detect pixel regressions. Pass `updateBaseline: true` to reset. |
|
|
591
|
-
|
|
592
|
-
**`argus_audit`** — fast audit of any URL:
|
|
593
|
-
|
|
594
|
-
```text
|
|
595
|
-
Run argus_audit on http://localhost:3000/checkout
|
|
596
|
-
Run argus_audit on http://localhost:3000/login with critical: true
|
|
597
|
-
```
|
|
598
|
-
|
|
599
|
-
**`argus_audit_full`** — deep audit with Lighthouse + memory + responsive checks:
|
|
600
|
-
|
|
601
|
-
```text
|
|
602
|
-
Run argus_audit_full on http://localhost:3000/dashboard
|
|
603
|
-
```
|
|
604
|
-
|
|
605
|
-
**`argus_compare`** — dev vs staging diff (reads `TARGET_DEV_URL` and `TARGET_STAGING_URL` from `.env`):
|
|
606
|
-
|
|
607
|
-
```text
|
|
608
|
-
Run argus_compare
|
|
609
|
-
```
|
|
610
|
-
|
|
611
|
-
**`argus_last_report`** — retrieve last audit without re-running Chrome:
|
|
612
|
-
|
|
613
|
-
```text
|
|
614
|
-
Run argus_last_report
|
|
615
|
-
```
|
|
616
|
-
|
|
617
|
-
**`argus_watch_snapshot`** — snapshot the currently open tab without navigating. Useful when the page is in an authenticated or post-interaction state that navigation would reset:
|
|
618
|
-
|
|
619
|
-
```text
|
|
620
|
-
Run argus_watch_snapshot
|
|
621
|
-
Run argus_watch_snapshot with url: http://localhost:3000
|
|
622
|
-
```
|
|
623
|
-
|
|
624
|
-
**`argus_get_context`** — when your app is stuck or throwing errors, run this to capture everything that's broken and feed it to Claude for diagnosis:
|
|
625
|
-
|
|
626
|
-
```text
|
|
627
|
-
Run argus_get_context
|
|
628
|
-
```
|
|
629
|
-
|
|
630
|
-
Then follow with: *"Here's the context — what's causing these errors and how do I fix them?"*
|
|
631
|
-
|
|
632
|
-
---
|
|
633
|
-
|
|
634
|
-
### Option B & C — Via CLI / npm scripts
|
|
635
|
-
|
|
636
|
-
**Available commands:**
|
|
637
|
-
|
|
638
|
-
| Command | What it does |
|
|
639
|
-
| --- | --- |
|
|
640
|
-
| `npm run crawl` | Multi-page batch audit of all routes in `targets.js` |
|
|
641
|
-
| `npm run compare` | Dev vs staging diff (or CSS analysis if no `TARGET_STAGING_URL`) |
|
|
642
|
-
| `npm run watch` | Passive monitor — polls the open Chrome tab every 1s, no navigation |
|
|
643
|
-
| `npm run report:html` | Generate `reports/report.html` from the latest JSON audit |
|
|
644
|
-
| `npm run server` | Start the Slack slash command + interaction server (port 3001) |
|
|
645
|
-
| `npm run init` | Interactive setup wizard — generates `.env` + `targets.js` |
|
|
646
|
-
| `npm run test:unit` | Run 61 unit tests (no Chrome required) |
|
|
647
|
-
| `npm run test:harness` | Run 129-block correctness harness (requires Chrome) |
|
|
648
|
-
|
|
649
|
-
**`npm run crawl`** — full audit of all configured routes:
|
|
650
|
-
|
|
651
|
-
```bash
|
|
652
|
-
npm run crawl
|
|
653
|
-
```
|
|
654
|
-
|
|
655
|
-
Reports are saved to `reports/` as JSON files. Run `npm run report:html` after any crawl for a portable `reports/report.html` with all screenshots inlined — useful for sharing with designers or reviewing offline.
|
|
656
|
-
|
|
657
|
-
**`npm run compare`** — dev vs staging diff:
|
|
658
|
-
|
|
659
|
-
```bash
|
|
660
|
-
npm run compare
|
|
661
|
-
```
|
|
662
|
-
|
|
663
|
-
When `TARGET_STAGING_URL` is not set, automatically switches to **CSS analysis mode** — cascade overrides, component style leaks, unused rules, and React inline style conflicts on the dev environment only.
|
|
664
|
-
|
|
665
|
-
**`npm run watch`** — passive monitoring (polls every 1s, no navigation):
|
|
666
|
-
|
|
667
|
-
Attaches to whatever Chrome tab is open and reports new issues in real time without navigating anywhere. Use this while developing.
|
|
668
|
-
|
|
669
|
-
```text
|
|
670
|
-
Requires 2 terminals:
|
|
671
|
-
Terminal 1 — your app (npm start / npm run dev)
|
|
672
|
-
Terminal 2 — npm run watch
|
|
673
|
-
```
|
|
674
|
-
|
|
675
|
-
Steps:
|
|
676
|
-
1. Open Chrome and navigate to your app
|
|
677
|
-
2. Terminal 1: start your application
|
|
678
|
-
3. Terminal 2: `npm run watch` — Argus begins polling
|
|
679
|
-
4. Develop normally — console errors, network failures (4xx/5xx), CORS blocks, and auth failures print in real time
|
|
680
|
-
5. `Ctrl+C` — stops the monitor and writes `reports/report.html`
|
|
681
|
-
|
|
682
|
-
```bash
|
|
683
|
-
# Attribute findings to a specific URL:
|
|
684
|
-
npm run watch http://localhost:4000
|
|
685
|
-
```
|
|
686
|
-
|
|
687
|
-
| Variable | Default | Description |
|
|
688
|
-
| --- | --- | --- |
|
|
689
|
-
| `ARGUS_WATCH_INTERVAL_MS` | `1000` | Poll interval in milliseconds |
|
|
690
|
-
| `TARGET_DEV_URL` | `http://localhost:3000` | URL attributed to findings when none passed |
|
|
691
|
-
|
|
692
|
-
**`npm run report:html`** — generate HTML dashboard from last audit:
|
|
693
|
-
|
|
694
|
-
```bash
|
|
695
|
-
npm run report:html
|
|
696
|
-
# → reports/report.html (all findings + inline screenshots, portable, no server needed)
|
|
697
|
-
```
|
|
698
|
-
|
|
699
|
-
---
|
|
700
|
-
|
|
701
|
-
### Option D — From Slack (on-demand)
|
|
702
|
-
|
|
703
|
-
```text
|
|
704
|
-
/argus-retest https://staging.example.com/checkout
|
|
705
|
-
```
|
|
706
|
-
|
|
707
|
-
BugBot responds immediately, runs the test, and posts results back. Detailed bug reports go to `#bugs-critical`. See [Slack Slash Command Setup](#slack-slash-command-setup) for configuration.
|
|
708
|
-
|
|
709
|
-
---
|
|
710
|
-
|
|
711
|
-
## CSS Analysis Mode
|
|
712
|
-
|
|
713
|
-
When `TARGET_STAGING_URL` is not set in `.env`, `npm run compare` automatically switches to **CSS analysis mode** instead of comparing two environments.
|
|
714
|
-
|
|
715
|
-
**What it analyzes on your dev environment:**
|
|
716
|
-
|
|
717
|
-
| Check | What it catches |
|
|
718
|
-
| --- | --- |
|
|
719
|
-
| **Cascade overrides** | Same CSS property declared multiple times on an element; `!important` flagged as warning |
|
|
720
|
-
| **Component style leaks** | BEM selector (`.card__title`) found in a stylesheet that doesn't belong to that component |
|
|
721
|
-
| **Unused rules** | CSS selectors that match no element on the current page |
|
|
722
|
-
| **CSS Modules** | Detects hashed class names; extracts readable component names (`Button`, `Card`, etc.) |
|
|
723
|
-
| **React inline style conflicts** | `style=""` attribute overriding a stylesheet declaration on the same element |
|
|
724
|
-
| **SCSS source maps** | Traces compiled CSS back to original `.scss` files where source maps are available |
|
|
725
|
-
|
|
726
|
-
**API frequency analysis** also runs automatically:
|
|
727
|
-
|
|
728
|
-
| Call count | Severity | Likely cause |
|
|
729
|
-
| --- | --- | --- |
|
|
730
|
-
| 2 calls | info | Possible prefetch + actual — verify intentional |
|
|
731
|
-
| 3–4 calls | warning | Double-fetch — check `useEffect` deps or component re-mounts |
|
|
732
|
-
| 5+ calls | critical | Runaway loop — missing cleanup, infinite re-render |
|
|
733
|
-
|
|
734
|
-
---
|
|
735
|
-
|
|
736
|
-
## Performance Budgets
|
|
737
|
-
|
|
738
|
-
Argus enforces these thresholds on every crawl:
|
|
739
|
-
|
|
740
|
-
| Metric | Threshold | Severity |
|
|
741
|
-
| --- | --- | --- |
|
|
742
|
-
| LCP (Largest Contentful Paint) | < 2500ms | warning |
|
|
743
|
-
| CLS (Cumulative Layout Shift) | < 0.1 | warning |
|
|
744
|
-
| FID / TBT (interaction latency) | < 100ms | warning |
|
|
745
|
-
| TTFB (Time to First Byte) | < 800ms | warning |
|
|
746
|
-
|
|
747
|
-
Violations are reported as individual warning bugs with the measured value.
|
|
748
|
-
|
|
749
|
-
---
|
|
750
|
-
|
|
751
|
-
## Lighthouse Suite
|
|
752
|
-
|
|
753
|
-
Runs all four Lighthouse categories on every route:
|
|
754
|
-
|
|
755
|
-
- **Accessibility** — score < 50 → `critical`; score < 90 → `warning`
|
|
756
|
-
- **Performance** — score < 90 → `warning`
|
|
757
|
-
- **SEO** — score < 90 → `warning`
|
|
758
|
-
- **Best Practices** — score < 90 → `warning`
|
|
759
|
-
|
|
760
|
-
Individual failing audit items (e.g., missing alt text, low contrast, render-blocking resources) are surfaced as separate findings alongside the category score.
|
|
761
|
-
|
|
762
|
-
---
|
|
763
|
-
|
|
764
|
-
## Slack Channel Routing
|
|
765
|
-
|
|
766
|
-
> **Slack is optional.** When `SLACK_BOT_TOKEN` is not set, Argus skips Slack entirely and
|
|
767
|
-
> auto-generates a local `report.html` (all findings + inline screenshots) and opens it in
|
|
768
|
-
> the default browser. No Slack setup needed to start using Argus.
|
|
769
|
-
|
|
770
|
-
When Slack **is** configured, findings are routed by severity:
|
|
771
|
-
|
|
772
|
-
| Severity | Channel | When |
|
|
773
|
-
| --- | --- | --- |
|
|
774
|
-
| `critical` | `#bugs-critical` | JS exceptions, HTTP 5xx, blank page, auth failure, API called 5+ times, Lighthouse accessibility < 50, auth token in storage/URL, responsive overflow, slow API > 3s, payload > 2MB, > 100 detached DOM nodes, CORS policy violations, `debugger;` statements in production code, blocked mixed content (HTTP resource on HTTPS page) |
|
|
775
|
-
| `warning` | `#bugs-warnings` | Visual regression > 0.5%, HTTP 4xx, CSS overrides with `!important`, API called 3–4×, Lighthouse scores < 90, missing SEO/OG tags, missing security headers, placeholder content, touch targets too small, slow API > 1s, payload > 500KB, > 10 detached DOM nodes, redirect chains > 2 hops, broken links, sync XHR, `document.write`, long tasks > 50ms, SW registration failures, duplicate `id` attributes, passive mixed content (images/audio on HTTPS page) |
|
|
776
|
-
| `info` | `#bugs-digest` | Console warnings, unused CSS rules, API summaries, CSS Modules detection, empty data lists, responsive screenshot grid, missing cache headers on static assets |
|
|
777
|
-
|
|
778
|
-
Each message includes:
|
|
779
|
-
|
|
780
|
-
- Severity badge + affected URL + timestamp
|
|
781
|
-
- AI-generated description
|
|
782
|
-
- Inline screenshot (uploaded directly to Slack — no external hosting)
|
|
783
|
-
- **View Page**, **Acknowledge**, and **Retest** action buttons
|
|
784
|
-
|
|
785
|
-
---
|
|
786
|
-
|
|
787
|
-
## Slack Slash Command Setup
|
|
788
|
-
|
|
789
|
-
To use `/argus-retest` from Slack, you need to expose the Argus server publicly.
|
|
790
|
-
|
|
791
|
-
### Step 1 — Start the server
|
|
792
|
-
|
|
793
|
-
```bash
|
|
794
|
-
npm run server
|
|
795
|
-
```
|
|
796
|
-
|
|
797
|
-
Server runs on port 3001.
|
|
798
|
-
|
|
799
|
-
### Step 2 — Expose with Cloudflare Tunnel
|
|
800
|
-
|
|
801
|
-
Download [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) (free, no account needed), then:
|
|
802
|
-
|
|
803
|
-
```bash
|
|
804
|
-
cloudflared tunnel --url http://localhost:3001
|
|
805
|
-
```
|
|
806
|
-
|
|
807
|
-
Alternatively, with no install at all (SSH tunnel):
|
|
808
|
-
|
|
809
|
-
```bash
|
|
810
|
-
ssh -R 80:localhost:3001 nokey@localhost.run
|
|
811
|
-
```
|
|
812
|
-
|
|
813
|
-
Copy the public HTTPS URL that appears.
|
|
814
|
-
|
|
815
|
-
### Step 3 — Configure Slack App
|
|
816
|
-
|
|
817
|
-
1. [api.slack.com/apps](https://api.slack.com/apps) → BugBot → **Slash Commands** → Create New Command:
|
|
818
|
-
- Command: `/argus-retest`
|
|
819
|
-
- Request URL: `https://your-public-url/slack/commands`
|
|
820
|
-
- Description: `Run Argus regression test on a URL`
|
|
821
|
-
- Usage hint: `<url>`
|
|
822
|
-
|
|
823
|
-
2. **Interactivity & Shortcuts** → Enable → Request URL: `https://your-public-url/slack/interactions`
|
|
824
|
-
|
|
825
|
-
3. **OAuth & Permissions** → **Reinstall to Workspace**
|
|
826
|
-
|
|
827
|
-
### Step 4 — Test
|
|
828
|
-
|
|
829
|
-
```text
|
|
830
|
-
/argus-retest http://localhost:3000
|
|
831
|
-
```
|
|
832
|
-
|
|
833
|
-
BugBot should reply within 3 seconds with a "running" acknowledgement, then post results.
|
|
834
|
-
|
|
835
|
-
---
|
|
836
|
-
|
|
837
|
-
## GitHub Actions CI Setup
|
|
838
|
-
|
|
839
|
-
### Add secrets to your repository
|
|
840
|
-
|
|
841
|
-
Go to GitHub repo → **Settings** → **Secrets and variables** → **Actions** → add:
|
|
842
|
-
|
|
843
|
-
| Secret name | Required | Value |
|
|
844
|
-
| --- | --- | --- |
|
|
845
|
-
| `SLACK_BOT_TOKEN` | No | Your `xoxb-...` token. **Omit entirely to use Slack-optional mode** — Argus generates `report.html` instead |
|
|
846
|
-
| `SLACK_SIGNING_SECRET` | No* | From Slack App → Basic Information (only needed for `/argus-retest` slash command) |
|
|
847
|
-
| `SLACK_CHANNEL_CRITICAL` | No* | Channel ID (required when Slack is configured) |
|
|
848
|
-
| `SLACK_CHANNEL_WARNINGS` | No* | Channel ID (required when Slack is configured) |
|
|
849
|
-
| `SLACK_CHANNEL_DIGEST` | No* | Channel ID (required when Slack is configured) |
|
|
850
|
-
| `TARGET_STAGING_URL` | Yes | Your staging base URL |
|
|
851
|
-
| `GITHUB_TOKEN` | No | For C2 PR integration — auto-injected by GitHub Actions as `secrets.GITHUB_TOKEN` |
|
|
852
|
-
| `GITHUB_REPOSITORY` | No | For C2 PR integration — `owner/repo` format (e.g., `acme/my-app`) |
|
|
853
|
-
|
|
854
|
-
> **C2 PR integration**: when `GITHUB_TOKEN` and `GITHUB_REPOSITORY` are set, Argus posts a PR comment and commit status check for every crawl. `GITHUB_PR_NUMBER` is injected automatically by the workflow from `github.event.pull_request.number`. The included workflow does not wire these up by default — add them to the `env:` block in `.github/workflows/argus.yml` if you want PR-level comments.
|
|
855
|
-
|
|
856
|
-
The workflow at [.github/workflows/argus.yml](.github/workflows/argus.yml) runs:
|
|
857
|
-
|
|
858
|
-
- On every push to `main` / `master`
|
|
859
|
-
- Daily at 6 AM UTC (before the team starts work)
|
|
860
|
-
- Manually via **Actions** → **Run workflow** (with optional URL override)
|
|
861
|
-
|
|
862
|
-
If critical issues are found, the pipeline **fails** — preventing silent regressions from being missed.
|
|
863
|
-
|
|
864
|
-
---
|
|
865
|
-
|
|
866
|
-
## Project Structure
|
|
867
|
-
|
|
868
|
-
```text
|
|
869
|
-
argus/
|
|
870
|
-
├── .env # Your secrets (never commit this)
|
|
871
|
-
├── .env.example # Template — copy to .env
|
|
872
|
-
├── .gitignore
|
|
873
|
-
├── package.json
|
|
874
|
-
├── README.md
|
|
875
|
-
├── .claude/
|
|
876
|
-
│ └── settings.json # Claude Code permission config (auto-approve node/npm/reports)
|
|
877
|
-
├── .github/
|
|
878
|
-
│ └── workflows/
|
|
879
|
-
│ └── argus.yml # CI pipeline
|
|
880
|
-
├── .vscode/
|
|
881
|
-
│ └── mcp.json # Chrome DevTools MCP config for VS Code
|
|
882
|
-
├── .mcp.json # Argus MCP server registration — exposes all 8 tools to Claude: argus_audit/argus_audit_full/argus_compare/argus_last_report/argus_watch_snapshot/argus_get_context/argus_design_audit/argus_visual_diff
|
|
883
|
-
├── src/
|
|
884
|
-
│ ├── argus.js # Single-page audit entry point
|
|
885
|
-
│ ├── batch-runner.js # Multi-page batch audit
|
|
886
|
-
│ ├── mcp-server.js # Argus MCP server — argus_audit / argus_audit_full / argus_compare / argus_last_report / argus_watch_snapshot / argus_get_context / argus_design_audit / argus_visual_diff
|
|
887
|
-
│ ├── adapters/
|
|
888
|
-
│ │ └── browser.js # CdpBrowserAdapter — facade over all chrome-devtools-mcp calls
|
|
889
|
-
│ ├── domain/
|
|
890
|
-
│ │ └── finding.js # createFinding() factory — canonical finding shape
|
|
891
|
-
│ ├── registry.js # Analyzer plugin registry — registerCheap/registerExpensive/getCheap/getExpensive/clearAll
|
|
892
|
-
│ ├── config/
|
|
893
|
-
│ │ ├── targets.js # Routes to test, thresholds, config
|
|
894
|
-
│ │ └── schema.js # Zod validation schema; validateConfig() called inside runCrawl()
|
|
895
|
-
│ ├── orchestration/
|
|
896
|
-
│ │ ├── crawl-and-report.js # Backward-compat re-export shell → orchestrator + report-processor + dispatcher
|
|
897
|
-
│ │ ├── orchestrator.js # Crawl loop, route/flow crawl, runCrawl()
|
|
898
|
-
│ │ ├── report-processor.js # Dedup → severity overrides → baseline → JSON write
|
|
899
|
-
│ │ ├── dispatcher.js # Slack / GitHub / HTML dispatch
|
|
900
|
-
│ │ ├── env-comparison.js # Dev vs staging diff + CSS analysis mode
|
|
901
|
-
│ │ ├── watch-mode.js # Passive browser monitoring (WatchSession + runWatchMode)
|
|
902
|
-
│ │ └── slack-notifier.js # Slack Block Kit dispatcher
|
|
903
|
-
│ ├── server/
|
|
904
|
-
│ │ ├── index.js # Express server (port 3001)
|
|
905
|
-
│ │ ├── slash-command-handler.js # /argus-retest handler
|
|
906
|
-
│ │ └── interaction-handler.js # Acknowledge + Retest button handler
|
|
907
|
-
│ ├── utils/
|
|
908
|
-
│ │ ├── css-analyzer.js # CSS analysis script injected into the browser
|
|
909
|
-
│ │ ├── seo-analyzer.js # SEO checks: meta, OG tags, h1, canonical, viewport
|
|
910
|
-
│ │ ├── security-analyzer.js # Security: localStorage tokens, eval(), headers, cookies
|
|
911
|
-
│ │ ├── content-analyzer.js # Content quality: null text, placeholders, broken images
|
|
912
|
-
│ │ ├── responsive-analyzer.js # Responsive: overflow + touch targets at 4 breakpoints
|
|
913
|
-
│ │ ├── memory-analyzer.js # Memory leaks: V8 heap snapshot + heap growth
|
|
914
|
-
│ │ ├── logger.js # Pino structured logger — childLogger(module)│ │ ├── retry.js # withRetry() exponential backoff — navigate/fill only; Number.isFinite guard│ │ ├── telemetry.js # OTel tracing + metrics — startSpan() / recordFinding() / recordFlaky() / recordNewFindings(); no-op default│ │ ├── session-manager.js # Auth: backward-compat re-export barrel│ │ ├── session-persistence.js # Auth: saveSession (mkdirSync+atomic write), restoreSession, hasSession, clearSession│ │ ├── login-orchestrator.js # Auth: runLoginFlow, refreshSession + lock file│ │ ├── baseline-manager.js # Baselines: loadBaseline, saveBaseline, applyBaseline, appendTrend
|
|
915
|
-
│ │ ├── flakiness-detector.js # Flakiness: mergeRunResults — confirmed vs flaky per double-crawl
|
|
916
|
-
│ │ ├── flow-runner.js # User flow assertions: runFlow / runAllFlows — assert DSL
|
|
917
|
-
│ │ ├── html-reporter.js # HTML dashboard: generateHtmlReport() + npm run report:html (D7.1 / D7.7)
|
|
918
|
-
│ │ ├── parallel-crawler.js # chunkArray sharding utility (ARGUS_CONCURRENCY=N parallel crawl)
|
|
919
|
-
│ │ ├── contract-validator.js # API contract validation: validateSchema, matchesContract (D7.4)
|
|
920
|
-
│ │ ├── severity-overrides.js # Severity policy overrides: applyOverrides (D7.5)
|
|
921
|
-
│ │ ├── slack-guard.js # Slack-optional guard: isSlackConfigured() (D7.7)
|
|
922
|
-
│ │ ├── hover-analyzer.js # Hover-state bug detection — aria-haspopup + data-tooltip (D8.1)
|
|
923
|
-
│ │ ├── snapshot-analyzer.js # Accessibility tree snapshot — missing names, labels, landmarks, heading hierarchy, ARIA state (D8.2 + v6)
|
|
924
|
-
│ │ ├── issues-analyzer.js # Chrome DevTools Issues panel — CSP/deprecated/cookie issues
|
|
925
|
-
│ │ ├── network-timing-analyzer.js # HAR timing analysis — slow third-party detection
|
|
926
|
-
│ │ ├── keyboard-analyzer.js # Keyboard Tab-walk — focus_visible_missing, focus_lost
|
|
927
|
-
│ │ ├── theme-analyzer.js # A7: Theme & Dark Mode detection — emulateColorScheme, prefers-color-scheme mismatches
|
|
928
|
-
│ │ ├── design-fidelity-analyzer.js # D9: Figma design token vs DOM comparison — 13 mismatch finding types
|
|
929
|
-
│ │ ├── web-vitals-analyzer.js # Sprint 9: LCP/CLS/FCP/TTI/TTFB via Performance API + bundle size regression
|
|
930
|
-
│ │ ├── visual-diff-analyzer.js # A8: Visual regression baseline comparison (pixelmatch)
|
|
931
|
-
│ │ ├── a11y-deep-analyzer.js # A12: axe-core 4.12 injection + CVD color blind simulation (protanopia/deuteranopia)
|
|
932
|
-
│ │ ├── har-recorder.js # N1: HAR network baseline — record + diff all requests per route
|
|
933
|
-
│ │ ├── motion-analyzer.js # A9: Motion & Animation — prefers-reduced-motion + autoplay detection
|
|
934
|
-
│ │ ├── font-analyzer.js # A10: Font Loading — FOIT/FOUT/fallback/slow/suboptimal-format detection
|
|
935
|
-
│ │ ├── form-analyzer.js # A11: Form Validation — required/autocomplete/aria/validation gaps
|
|
936
|
-
│ │ ├── codebase-analyzer.js # Codebase cross-reference — env vars, feature flags, dead routes (C1)
|
|
937
|
-
│ │ ├── github-reporter.js # GitHub PR comment + commit status + Check Runs (C2) — createCheckRun/completeCheckRun/generateReleaseNotes
|
|
938
|
-
│ │ ├── route-discoverer.js # Auto route discovery — sitemap + Next.js + React Router (C3)
|
|
939
|
-
│ │ ├── diff.js # pixelmatch screenshot + DOM/network diff utilities
|
|
940
|
-
│ │ ├── mcp-parsers.js # Text-format parsers for list_console_messages + list_network_requests (v9)
|
|
941
|
-
│ │ └── mcp-client.js # Headless JSON-RPC MCP client for CI mode
|
|
942
|
-
│ └── cli/
|
|
943
|
-
│ └── init.js # argus init setup wizard — detect framework, discover routes, write .env + targets.js (C4)
|
|
944
|
-
├── test/
|
|
945
|
-
│ └── unit/ # Vitest unit tests — no Chrome required
|
|
946
|
-
│ ├── finding.test.js # createFinding() — fields, throws, frozen, extra fields (8 tests)
|
|
947
|
-
│ ├── config-schema.test.js # validateConfig() + ConfigSchema.safeParse (8 tests)
|
|
948
|
-
│ ├── report-processor.test.js # deduplicateFindings + rebuildSummary (11 tests)
|
|
949
|
-
│ ├── flakiness-detector.test.js # findingKey normalization + mergeRunResults (13 tests)
|
|
950
|
-
│ ├── baseline-manager.test.js # loadBaseline/saveBaseline/applyBaseline (9 tests)
|
|
951
|
-
│ └── flow-runner.test.js # normalizeArray (pure) + runFlow mock browser (11 tests)
|
|
952
|
-
├── landing/ # Product landing page (React 19 + Vite 8 + Tailwind + Framer Motion 12)
|
|
953
|
-
│ ├── src/
|
|
954
|
-
│ │ ├── App.jsx # Single-page app — hero, features, comparison, waitlist + enterprise modals
|
|
955
|
-
│ │ └── supabase.js # Supabase client factory (null-safe when env vars missing)
|
|
956
|
-
│ ├── public/
|
|
957
|
-
│ │ ├── favicon.svg # SVG favicon — purple ring + dot
|
|
958
|
-
│ │ ├── argus-poster.png # Video poster fallback (1918×1078)
|
|
959
|
-
│ │ ├── og-image-v2.jpg # OG social card — 1200×630 JPEG, branded overlay, black-outlined stat numbers
|
|
960
|
-
│ │ ├── robots.txt # Allows all crawlers; Sitemap reference
|
|
961
|
-
│ │ └── sitemap.xml # Canonical URL for argus-qa.com/
|
|
962
|
-
│ ├── index.html # Vite entry; OG/Twitter/JSON-LD SEO tags; canonical; favicon
|
|
963
|
-
│ ├── package.json
|
|
964
|
-
│ ├── .env.example # VITE_SUPABASE_URL + VITE_SUPABASE_ANON_KEY template
|
|
965
|
-
│ └── README.md # Setup guide, Supabase SQL schema, env vars, deployment
|
|
966
|
-
├── scripts/
|
|
967
|
-
│ └── dispatch-report.js # Standalone Slack re-dispatch script (re-posts last report.json to Slack)
|
|
968
|
-
├── test-harness/ # Fixture server + test runner (135 blocks, 616 hard assertions, 62 fixture pages)
|
|
969
|
-
│ ├── README.md
|
|
970
|
-
│ ├── server.js # Express fixture server (ports 3100 dev / 3101 staging)
|
|
971
|
-
│ ├── harness-config.js # Route definitions + expected findings
|
|
972
|
-
│ ├── validate.js # Test runner — 136 numbered blocks ([80]–[84] MCP/createFinding/withRetry/watch/init, [85]–[93] Sprint 0.5 Tier 3, [94]–[126] gap-close, [127] A7 theme, [128] D9 design fidelity, [129] Sprint 9 Web Vitals, [130] A8 Visual Regression, [131] A12 axe-core, [132] N1 HAR, [133] A9 Motion, [134] A10 Font, [135] A11 Form, [136] Sprint 6 Check Runs)
|
|
973
|
-
│ ├── pages/ # 62 fixture HTML pages (one per detection category)
|
|
974
|
-
│ ├── nextjs-fixture/ # Next.js app structure for C3 discovery tests (10 files)
|
|
975
|
-
│ ├── source-fixture/ # Minimal app.js for C1 codebase-analyzer tests (env var audit)
|
|
976
|
-
│ └── static/
|
|
977
|
-
│ └── button-styles.css # BEM card selectors in button file → component leak
|
|
978
|
-
└── reports/ # Output: JSON reports + screenshots (gitignored)
|
|
979
|
-
├── baselines/
|
|
980
|
-
│ ├── <branch>.json # Per-route finding keys — per git branch (D7.2)
|
|
981
|
-
│ └── <branch>-trends.json # Append-only run history per branch (D7.2)
|
|
982
|
-
└── .gitkeep
|
|
983
|
-
```
|
|
984
|
-
|
|
985
|
-
---
|
|
986
|
-
|
|
987
|
-
## Key Technical Decisions
|
|
988
|
-
|
|
989
|
-
| Decision | Choice | Reason |
|
|
990
|
-
| --- | --- | --- |
|
|
991
|
-
| Screenshot comparison | pixelmatch + AI classification | pixelmatch is fast and deterministic; Claude removes false positives from anti-aliasing and dynamic content |
|
|
992
|
-
| Slack API | Bot API, not Incoming Webhooks | Bot API supports file uploads, message updates, interactive buttons, and threads |
|
|
993
|
-
| File uploads | `files.getUploadURLExternal` + PUT + `files.completeUploadExternal` | `files.upload` is deprecated; pre-signed URL requires PUT — POST silently produces broken files |
|
|
994
|
-
| CSS analysis | Script injected via `evaluate_script` | Runs in page context so it sees the live computed styles, CSS Modules hashes, and React fiber properties |
|
|
995
|
-
| Responsive viewport | `emulate` (not `resize_page`) | `resize_page` only resizes the browser window and does not update CSS viewport width — `emulate` is the correct API |
|
|
996
|
-
| Viewport width measurement | `document.documentElement.clientWidth` | After `emulate` with mobile flag, `window.innerWidth` returns the legacy layout viewport (~952px), not the device width |
|
|
997
|
-
| V8 heap snapshot | `take_heapsnapshot({ filePath })` → read from disk | The MCP tool writes JSON to disk (not inline); parse with `JSON.parse(fs.readFileSync(filePath))` then delete the temp file |
|
|
998
|
-
| Detached DOM detection | Walk flat `nodes` array for "Detached " prefix in strings table | Chrome serializes detached elements as "Detached HTMLDivElement" etc.; secondary check on `detachedness === 2` (Chrome 90+) |
|
|
999
|
-
| Baseline finding key | `type::message[:100]::status` | Excludes timestamps and dynamic URL path IDs; message truncated to 100 chars to handle slight wording variations; `::status` suffix only added when non-null |
|
|
1000
|
-
| Baseline alert filter | `isNew === true` (strict) | Only findings explicitly marked new by `applyBaseline` are dispatched to Slack — prevents stale re-dispatch if baseline-manager is not called (fails silently rather than spamming) |
|
|
1001
|
-
| Flakiness routing | `severity: 'info'` for flaky findings | Downgrading severity means existing `dispatchToSlack` routing sends them to the info digest with zero routing changes — only the `:zap: _flaky_` label needed |
|
|
1002
|
-
| Private `findingKey` per module | Each of `baseline-manager.js` and `flakiness-detector.js` has its own copy | Avoids coupling two independently-useful modules via a shared export for a trivial 3-line function |
|
|
1003
|
-
| Runtime anti-pattern injection | `addScriptToEvaluateOnNewDocument` via MCP | Scripts registered this way run in the new page context before any page script — intercepts `XMLHttpRequest.open`, `document.write`, and `navigator.serviceWorker.register` before the page can call them |
|
|
1004
|
-
| CORS error detection | `list_console_messages` + text match, not in-page intercept | CORS errors are generated by the browser itself, not by page JS — `console.error` patcher misses them; the MCP console log captures them |
|
|
1005
|
-
| Long task detection | `PerformanceObserver({ entryTypes: ['longtask'] })` injected before load | Only the duration is included in the finding message (not `startTime`) — ensures identical tasks on two crawl runs produce the same dedup key |
|
|
1006
|
-
| CI MCP client | JSON-RPC over stdio | In CI there's no Claude Code agent — the headless client replaces it with the same API surface |
|
|
1007
|
-
| Node.js | v20.19+ | Minimum required by Chrome DevTools MCP |
|
|
1008
|
-
|
|
1009
|
-
---
|
|
1010
|
-
|
|
1011
|
-
## Known MCP Tool Limitations
|
|
1012
|
-
|
|
1013
|
-
The Chrome DevTools MCP behavioral constraints below cause **3 permanent test failures** in the harness (`623/626` pass). These are MCP-layer restrictions — they cannot be fixed in Argus code. `validate.js` now exits with code 0 when only these 3 failures remain, making the CI harness gate reliable.
|
|
1014
|
-
|
|
1015
|
-
> **`type_text` clarification**: `type_text` does fire DOM `input` events when the element is properly focused first with `mcp.click({ uid })`. Always use uid-based focus — passing `{ selector }` to `mcp.click` silently does nothing.
|
|
1016
|
-
|
|
1017
|
-
| Tool | Constraint | Impact |
|
|
1018
|
-
| --- | --- | --- |
|
|
1019
|
-
| `drag` | Uses mouse simulation, **not** HTML5 DnD API | `dragstart`/`dragover`/`drop` events never fire |
|
|
1020
|
-
| `list_console_messages({ types: ['issue'] })` | Issues panel returns empty even when violations exist | CSP and deprecated-API detection is unreliable |
|
|
1021
|
-
|
|
1022
|
-
These constraints are documented with workarounds in [SKILL.md §10](SKILL.md).
|
|
1023
|
-
|
|
1024
|
-
The harness passes **623/626** assertions (exits 0). The 3 failures are the permanent MCP-limited ones listed above.
|
|
1025
|
-
|
|
1026
|
-
---
|
|
1027
|
-
|
|
1028
|
-
## Environment Variables Reference
|
|
1029
|
-
|
|
1030
|
-
| Variable | Required | Description |
|
|
1031
|
-
| --- | --- | --- |
|
|
1032
|
-
| `SLACK_BOT_TOKEN` | No | `xoxb-...` Bot User OAuth Token. **Omit to enable Slack-optional mode** — Argus generates `report.html` and opens it in the browser instead |
|
|
1033
|
-
| `SLACK_SIGNING_SECRET` | No* | Verifies slash command / interaction requests from Slack (required only when using `/argus-retest`) |
|
|
1034
|
-
| `SLACK_CHANNEL_CRITICAL` | No* | Channel ID for critical bugs (required when Slack is configured) |
|
|
1035
|
-
| `SLACK_CHANNEL_WARNINGS` | No* | Channel ID for warnings (required when Slack is configured) |
|
|
1036
|
-
| `SLACK_CHANNEL_DIGEST` | No* | Channel ID for info / daily digest (required when Slack is configured) |
|
|
1037
|
-
| `TARGET_DEV_URL` | Yes | Base URL of your dev environment |
|
|
1038
|
-
| `TARGET_STAGING_URL` | No | Base URL of staging. If blank → CSS analysis mode |
|
|
1039
|
-
| `SCREENSHOT_DIFF_THRESHOLD` | No | Pixel diff % to flag (default: `0.5`) |
|
|
1040
|
-
| `REPORT_OUTPUT_DIR` | No | Where to write reports (default: `./reports`) |
|
|
1041
|
-
| `ARGUS_CONCURRENCY` | No | Number of parallel MCP clients for route crawling (default: `1` = sequential) |
|
|
1042
|
-
| `PORT` | No | Server port (default: `3001`) |
|
|
1043
|
-
| `ARGUS_LOG_LEVEL` | No | Pino log level — `trace`, `debug`, `info`, `warn`, `error`, `fatal` (default: `info`) |
|
|
1044
|
-
| `ARGUS_LOG_PRETTY` | No | Set to `1` for human-readable log output instead of JSON (dev mode) |
|
|
1045
|
-
| `ARGUS_RETRY_ATTEMPTS` | No | Max retry attempts for `navigate`/`fill` MCP calls (default: `3`) |
|
|
1046
|
-
| `OTEL_EXPORTER_OTLP_ENDPOINT` | No | OTLP collector endpoint — enables span/metric export to Jaeger, Grafana Tempo, Datadog, etc. |
|
|
1047
|
-
| `ARGUS_OTEL_CONSOLE` | No | Set to `1` to print OTel spans to stdout without an OTLP endpoint (dev tracing) |
|
|
1048
|
-
| `ARGUS_WATCH_INTERVAL_MS` | No | Watch mode poll interval in milliseconds (default: `1000`) |
|
|
1049
|
-
| `ARGUS_WATCH_UI_PORT` | No | Watch mode web dashboard port (default: `3002`) |
|
|
1050
|
-
| `ARGUS_SOURCE_DIR` | No | Path to your app's source directory — enables codebase cross-reference (env var detection, feature flag leakage, dead routes) |
|
|
1051
|
-
| `ARGUS_ENV_FILE` | No | Path to your app's `.env` file — C1 cross-references env vars used in source code against this file to detect missing declarations |
|
|
1052
|
-
| `GITHUB_TOKEN` | No | GitHub personal access token — required for PR comment + commit status integration |
|
|
1053
|
-
| `GITHUB_REPOSITORY` | No | Repository in `owner/repo` format — required for GitHub PR integration |
|
|
1054
|
-
| `GITHUB_SHA` | No | Commit SHA for the commit status check — injected automatically by GitHub Actions (`${{ github.sha }}`) |
|
|
1055
|
-
| `GITHUB_PR_NUMBER` | No | PR number for comment targeting — set via `${{ github.event.pull_request.number }}` in your workflow |
|
|
1056
|
-
| `ARGUS_REPORT_URL` | No | Full URL to the hosted HTML report — linked from the GitHub commit status check |
|
|
1057
|
-
|
|
1058
|
-
---
|
|
1059
|
-
|
|
1060
|
-
## Troubleshooting
|
|
1061
|
-
|
|
1062
|
-
### Chrome DevTools MCP not connecting
|
|
1063
|
-
|
|
1064
|
-
```bash
|
|
1065
|
-
claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
|
|
1066
|
-
# Then restart Claude Code
|
|
1067
|
-
```
|
|
1068
|
-
|
|
1069
|
-
### Slack messages not posting
|
|
1070
|
-
|
|
1071
|
-
- Confirm `SLACK_BOT_TOKEN` starts with `xoxb-` (not `xoxp-`, `xoxe-`, or `xapp-`)
|
|
1072
|
-
- Verify BugBot is invited to each channel: `/invite @BugBot`
|
|
1073
|
-
- Check token scopes: `chat:write`, `files:write`, `files:read`
|
|
1074
|
-
|
|
1075
|
-
### Screenshots not appearing in Slack messages
|
|
1076
|
-
|
|
1077
|
-
- The upload uses a pre-signed URL that requires `PUT`, not `POST` — if you see a broken image, check that the Slack token has `files:write` scope and the channel is correct
|
|
1078
|
-
|
|
1079
|
-
### Slash command returns "dispatch_failed"
|
|
1080
|
-
|
|
1081
|
-
- Your tunnel URL has changed (Cloudflare Tunnel / localhost.run URLs change on restart)
|
|
1082
|
-
- Update the Request URL in Slack App → Slash Commands and reinstall
|
|
1083
|
-
|
|
1084
|
-
### CSS analysis returns empty results
|
|
1085
|
-
|
|
1086
|
-
- Page may be behind auth — make sure you're logged in on the Chrome instance Argus is controlling
|
|
1087
|
-
- Cross-origin stylesheets (CDN fonts, third-party widgets) can't be read due to browser security restrictions — this is expected
|
|
1088
|
-
|
|
1089
|
-
### Screenshots are blank
|
|
1090
|
-
|
|
1091
|
-
- Page hasn't finished loading — increase `pageSettleMs` in `src/config/targets.js`
|
|
1092
|
-
- Add a `waitFor` selector for that route
|
|
1093
|
-
|
|
1094
|
-
### CI pipeline fails immediately
|
|
1095
|
-
|
|
1096
|
-
- Chrome may not be starting fast enough — increase the `sleep 3` after Chrome launch to `sleep 5` in `.github/workflows/argus.yml`
|
|
1097
|
-
|
|
1098
|
-
---
|
|
1099
|
-
|
|
1100
|
-
## How Argus Differs From Playwright / Cypress
|
|
1101
|
-
|
|
1102
|
-
Argus is not a replacement for unit or E2E tests. It's a complementary layer:
|
|
1103
|
-
|
|
1104
|
-
| | Playwright / Cypress | Argus |
|
|
1105
|
-
| --- | --- | --- |
|
|
1106
|
-
| **Tests** | Your logic and API contracts | What the user actually sees |
|
|
1107
|
-
| **Catches** | Regression in behaviour | CSS drift, visual regressions, API redundancy, console noise, perf budgets |
|
|
1108
|
-
| **Runs** | In your test suite | Continuously, on the live running app |
|
|
1109
|
-
| **Setup** | Write test files | Configure routes in `targets.js` |
|
|
1110
|
-
| **Output** | Pass / fail | Structured Slack reports with screenshots and action buttons |
|
|
1111
|
-
|
|
1112
|
-
They complement each other — Argus catches what test suites miss.
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# Argus — AI-Powered Automated QA
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/argusqa-os)
|
|
6
|
+
[](https://glama.ai/mcp/servers/ironclawdevs27/Argus)
|
|
7
|
+
[](test-harness/)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
|
|
10
|
+
**Argus catches the bugs your test suite misses — visual regressions, API loops, CSS drift, console noise, accessibility failures, and more — and delivers rich reports to Slack (or a local HTML dashboard).**
|
|
11
|
+
|
|
12
|
+
[Quick Start](#quick-start) · [Features](#what-argus-catches) · [Setup](#full-setup) · [MCP Tools](#mcp-tools) · [CLI Commands](#cli-commands) · [Troubleshooting](#troubleshooting) · [Full Reference](REFERENCE.md)
|
|
13
|
+
|
|
14
|
+
</div>
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Quick Start
|
|
19
|
+
|
|
20
|
+
> **No install required.** `npx` auto-downloads Argus on first run.
|
|
21
|
+
|
|
22
|
+
**Step 1 — Add to `.mcp.json`** in your project root:
|
|
23
|
+
|
|
24
|
+
```json
|
|
25
|
+
{
|
|
26
|
+
"mcpServers": {
|
|
27
|
+
"chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] },
|
|
28
|
+
"argus": { "command": "npx", "args": ["-y", "argusqa-os"] }
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Or via Claude Code CLI:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
|
|
37
|
+
claude mcp add argus -- npx -y argusqa-os
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**Step 2 — Start Chrome with remote debugging:**
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# macOS
|
|
44
|
+
open -a "Google Chrome" --args --remote-debugging-port=9222 --headless=new
|
|
45
|
+
|
|
46
|
+
# Windows (PowerShell)
|
|
47
|
+
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --headless=new --no-sandbox --disable-gpu --user-data-dir="$env:TEMP\chrome-argus"
|
|
48
|
+
|
|
49
|
+
# Linux
|
|
50
|
+
google-chrome --remote-debugging-port=9222 --headless=new --no-sandbox
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
**Step 3 — Run an audit:**
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
Run argus_audit on http://localhost:3000
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Argus scans your app and either posts findings to Slack or opens a local `report.html`. That's it.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## What Argus Catches
|
|
64
|
+
|
|
65
|
+
31 analysis engines, 138 distinct issue types, zero test-file maintenance:
|
|
66
|
+
|
|
67
|
+
| Category | What it detects |
|
|
68
|
+
|---|---|
|
|
69
|
+
| **JavaScript** | Uncaught exceptions, unhandled promise rejections, `console.error` on critical routes |
|
|
70
|
+
| **Network & API** | HTTP 5xx, 401/403 auth failures, duplicate API calls (infinite loops), 4xx errors, broken links |
|
|
71
|
+
| **Performance** | LCP > 2500ms, CLS > 0.1, TTFB > 800ms, slow APIs > 1s/3s, payloads > 500KB/2MB, JS bundles > 500KB |
|
|
72
|
+
| **Accessibility** | axe-core (80+ WCAG rules), color-blind simulation, missing ARIA, keyboard focus, heading hierarchy |
|
|
73
|
+
| **SEO** | Missing meta description, OG tags, canonical, viewport, h1 |
|
|
74
|
+
| **Security** | Auth tokens in localStorage/URL, `eval()`, missing CSP/X-Frame-Options, CSP violations |
|
|
75
|
+
| **CSS** | Cascade overrides, component style leaks, unused rules, React inline style conflicts |
|
|
76
|
+
| **Content** | `null`/`undefined` as visible text, lorem ipsum, broken images, empty data lists |
|
|
77
|
+
| **Responsive** | Horizontal overflow at 375px/768px, touch targets < 44×44px |
|
|
78
|
+
| **Memory** | Detached DOM nodes via V8 heap snapshot, heap growth across navigation |
|
|
79
|
+
| **Visual** | Pixel-level screenshot regression via pixelmatch (≥0.1% warning, ≥5% critical) |
|
|
80
|
+
| **Figma** | Design-to-implementation fidelity — 13 property types (color, spacing, typography, shadows, etc.) |
|
|
81
|
+
| **Forms** | Missing `required`, `autocomplete`, `aria-describedby`; unlabelled inputs |
|
|
82
|
+
| **Fonts** | FOIT, FOUT, missing fallbacks, slow loads > 1s, suboptimal formats |
|
|
83
|
+
| **Motion** | `prefers-reduced-motion` violations, `autoplay` without pause controls |
|
|
84
|
+
| **Network baseline** | New requests, missing requests, status-code regressions vs saved HAR baseline |
|
|
85
|
+
| **Environment diff** | Dev vs staging — screenshot diff, DOM changes, console/network regressions |
|
|
86
|
+
|
|
87
|
+
> All findings are classified as `critical` / `warning` / `info` and routed to the right Slack channel — or surfaced in the local HTML report. For per-finding severity tables and detection methods, see [REFERENCE.md](REFERENCE.md).
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## MCP Tools
|
|
92
|
+
|
|
93
|
+
Ask Claude (or any MCP client) — no terminal required:
|
|
94
|
+
|
|
95
|
+
| Tool | Description |
|
|
96
|
+
|---|---|
|
|
97
|
+
| `argus_audit` | Fast pass — JS, network, accessibility, SEO, security, CSS, content |
|
|
98
|
+
| `argus_audit_full` | Deep pass — adds Lighthouse, responsive checks, memory leak detection, hover-state bugs |
|
|
99
|
+
| `argus_compare` | Diff dev vs staging — screenshots, findings delta, environment regressions |
|
|
100
|
+
| `argus_get_context` | Capture everything broken on the open tab for Claude to diagnose |
|
|
101
|
+
| `argus_watch_snapshot` | Snapshot the open tab without navigating (preserves auth/form state) |
|
|
102
|
+
| `argus_last_report` | Return last JSON report without re-running |
|
|
103
|
+
| `argus_design_audit` | Figma URL → 13 design-token finding types (color, spacing, typography, shadows, etc.) |
|
|
104
|
+
| `argus_visual_diff` | Screenshot baseline comparison. Pass `updateBaseline: true` to reset. |
|
|
105
|
+
| `argus_pr_validate` | Fetch GitHub PR diff → map changed files to affected routes → targeted audit → `{ blocked, findings }` |
|
|
106
|
+
|
|
107
|
+
**Example prompts:**
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
Run argus_audit on http://localhost:3000/checkout
|
|
111
|
+
Run argus_audit_full on http://localhost:3000/dashboard
|
|
112
|
+
Run argus_compare
|
|
113
|
+
Run argus_get_context
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Full Setup
|
|
119
|
+
|
|
120
|
+
### Prerequisites
|
|
121
|
+
|
|
122
|
+
| Requirement | Version |
|
|
123
|
+
|---|---|
|
|
124
|
+
| Node.js | v20.19+ |
|
|
125
|
+
| Chrome | Stable (desktop or headless) |
|
|
126
|
+
| Claude Code | Latest (`npm install -g @anthropic-ai/claude-code`) |
|
|
127
|
+
| Slack workspace | **Optional** — omit for local `report.html` mode |
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
### Option A — MCP Server *(recommended for Claude Code users)*
|
|
132
|
+
|
|
133
|
+
No local install needed. Use the [Quick Start](#quick-start) above, then add your target URL:
|
|
134
|
+
|
|
135
|
+
```env
|
|
136
|
+
# .env in your project root
|
|
137
|
+
TARGET_DEV_URL=http://localhost:3000
|
|
138
|
+
TARGET_STAGING_URL=https://staging.example.com # optional — enables argus_compare
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
**Optional — Slack notifications:**
|
|
142
|
+
|
|
143
|
+
1. [api.slack.com/apps](https://api.slack.com/apps) → Create New App → name it **BugBot**
|
|
144
|
+
2. OAuth & Permissions → Bot Token Scopes: `chat:write`, `files:write`, `files:read`
|
|
145
|
+
3. Install to workspace → copy the `xoxb-...` token
|
|
146
|
+
4. Create channels `#bugs-critical`, `#bugs-warnings`, `#bugs-digest` and run `/invite @BugBot` in each
|
|
147
|
+
|
|
148
|
+
```env
|
|
149
|
+
SLACK_BOT_TOKEN=xoxb-...
|
|
150
|
+
SLACK_CHANNEL_CRITICAL=C0000000000
|
|
151
|
+
SLACK_CHANNEL_WARNINGS=C0000000001
|
|
152
|
+
SLACK_CHANNEL_DIGEST=C0000000002
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
> Without Slack: Argus auto-generates `reports/report.html` and opens it in your browser — zero extra config.
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
### Option B — npm Package (CI / dev dependency)
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
npm install --save-dev argusqa-os
|
|
163
|
+
npx argus init # interactive wizard — detects framework, discovers routes, writes .env
|
|
164
|
+
npm run crawl # run after Chrome is started
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
### Option C — Clone the Repository (contributors / full source)
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
git clone https://github.com/ironclawdevs27/Argus.git
|
|
173
|
+
cd Argus
|
|
174
|
+
npm install
|
|
175
|
+
npm run init # interactive setup wizard
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
**Manual setup (skip the wizard):**
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
cp .env.example .env
|
|
182
|
+
# Fill in TARGET_DEV_URL and optional Slack tokens
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Then configure your routes in [src/config/targets.js](src/config/targets.js):
|
|
186
|
+
|
|
187
|
+
```js
|
|
188
|
+
export const routes = [
|
|
189
|
+
{ path: '/', name: 'Home', critical: true, waitFor: 'main' },
|
|
190
|
+
{ path: '/login', name: 'Login', critical: true, waitFor: 'form' },
|
|
191
|
+
{ path: '/dashboard', name: 'Dashboard', critical: true, waitFor: '[data-testid="dashboard"]' },
|
|
192
|
+
{ path: '/settings', name: 'Settings', critical: false, waitFor: null },
|
|
193
|
+
];
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
- `critical: true` — errors on this route go to `#bugs-critical`
|
|
197
|
+
- `waitFor` — CSS selector Argus waits for before capturing (signals page-ready)
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## CLI Commands
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
npm run crawl # Batch audit of all configured routes
|
|
205
|
+
npm run compare # Dev vs staging diff (CSS-only if no staging URL)
|
|
206
|
+
npm run watch # Passive monitor — polls open Chrome tab every 1s
|
|
207
|
+
npm run report:html # Generate reports/report.html from last JSON audit
|
|
208
|
+
npm run server # Start Slack slash-command server (port 3001)
|
|
209
|
+
npm run init # Interactive setup wizard
|
|
210
|
+
npm run test:unit # 61 unit tests — no Chrome required
|
|
211
|
+
npm run test:harness # 138-block correctness harness — requires Chrome
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
**Watch mode** — live monitoring as you develop:
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
# Terminal 1: start your app
|
|
218
|
+
npm run dev
|
|
219
|
+
|
|
220
|
+
# Terminal 2: start Argus watcher
|
|
221
|
+
npm run watch
|
|
222
|
+
# Ctrl+C → stops monitor and writes reports/report.html
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
**Slack slash command** (on-demand from any channel):
|
|
226
|
+
|
|
227
|
+
```
|
|
228
|
+
/argus-retest https://staging.example.com/checkout
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
To expose the server via tunnel: `cloudflared tunnel --url http://localhost:3001` (free, no account required). Set the resulting URL as the Request URL in Slack App → Slash Commands.
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## GitHub Actions CI
|
|
236
|
+
|
|
237
|
+
Add to your repo's secrets (Settings → Secrets → Actions):
|
|
238
|
+
|
|
239
|
+
| Secret | Required | Value |
|
|
240
|
+
|---|---|---|
|
|
241
|
+
| `TARGET_STAGING_URL` | Yes | Your staging base URL |
|
|
242
|
+
| `SLACK_BOT_TOKEN` | No | `xoxb-...` token (omit for HTML-only mode) |
|
|
243
|
+
| `SLACK_CHANNEL_CRITICAL` | No* | Channel ID (needed when Slack is configured) |
|
|
244
|
+
| `SLACK_CHANNEL_WARNINGS` | No* | Channel ID |
|
|
245
|
+
| `SLACK_CHANNEL_DIGEST` | No* | Channel ID |
|
|
246
|
+
| `GITHUB_TOKEN` | No | Auto-injected by Actions for PR comments + Check Runs |
|
|
247
|
+
|
|
248
|
+
The included [workflow](.github/workflows/argus.yml) runs on push to `main`, daily at 6 AM UTC, and on manual trigger. If critical issues are found, the pipeline fails.
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Environment Variables
|
|
253
|
+
|
|
254
|
+
<details>
|
|
255
|
+
<summary>Full reference (click to expand)</summary>
|
|
256
|
+
|
|
257
|
+
| Variable | Default | Description |
|
|
258
|
+
|---|---|---|
|
|
259
|
+
| `TARGET_DEV_URL` | — | **Required.** Base URL of your dev environment |
|
|
260
|
+
| `TARGET_STAGING_URL` | — | Staging URL — enables `argus_compare`; omit for CSS-only mode |
|
|
261
|
+
| `SLACK_BOT_TOKEN` | — | `xoxb-...` token. Omit for local `report.html` mode |
|
|
262
|
+
| `SLACK_SIGNING_SECRET` | — | For `/argus-retest` slash command verification |
|
|
263
|
+
| `SLACK_CHANNEL_CRITICAL` | — | Channel ID for critical bugs |
|
|
264
|
+
| `SLACK_CHANNEL_WARNINGS` | — | Channel ID for warnings |
|
|
265
|
+
| `SLACK_CHANNEL_DIGEST` | — | Channel ID for info / daily digest |
|
|
266
|
+
| `PORT` | `3001` | Slack slash-command server port |
|
|
267
|
+
| `REPORT_OUTPUT_DIR` | `./reports` | Where to write JSON reports |
|
|
268
|
+
| `ARGUS_CONCURRENCY` | `1` | Parallel MCP clients for route crawling |
|
|
269
|
+
| `ARGUS_LOG_LEVEL` | `info` | `trace` / `debug` / `info` / `warn` / `error` |
|
|
270
|
+
| `ARGUS_LOG_PRETTY` | — | Set `1` for human-readable logs in dev |
|
|
271
|
+
| `ARGUS_RETRY_ATTEMPTS` | `3` | Max retries for `navigate`/`fill` MCP calls |
|
|
272
|
+
| `ARGUS_WATCH_INTERVAL_MS` | `1000` | Watch mode poll interval (ms) |
|
|
273
|
+
| `ARGUS_WATCH_UI_PORT` | `3002` | Watch mode web dashboard port |
|
|
274
|
+
| `ARGUS_SOURCE_DIR` | — | App source path — enables env-var / feature-flag / dead-route analysis |
|
|
275
|
+
| `ARGUS_ENV_FILE` | — | Path to app `.env` for codebase cross-reference |
|
|
276
|
+
| `SCREENSHOT_DIFF_THRESHOLD` | `0.5` | Pixel diff % threshold for environment comparison |
|
|
277
|
+
| `GITHUB_TOKEN` | — | For PR comments + Check Runs |
|
|
278
|
+
| `GITHUB_REPOSITORY` | — | `owner/repo` format |
|
|
279
|
+
| `GITHUB_PR_NUMBER` | — | Auto-injected by Actions from PR context |
|
|
280
|
+
| `ARGUS_CRITICAL_THRESHOLD` | `1` | New criticals before blocking merge (0 = never block) |
|
|
281
|
+
| `ARGUS_DIFF_IMAGE_URL` | — | Visual diff image URL to embed in PR comment |
|
|
282
|
+
| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP collector for Jaeger / Grafana Tempo |
|
|
283
|
+
| `FIGMA_API_TOKEN` | — | Required for `argus_design_audit` |
|
|
284
|
+
| `FONT_SLOW_MS` | `1000` | Slow web font load threshold (ms) |
|
|
285
|
+
| `A11Y_CONTRAST_AA` | `4.5` | WCAG AA min contrast ratio for CVD simulation |
|
|
286
|
+
|
|
287
|
+
</details>
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
## Troubleshooting
|
|
292
|
+
|
|
293
|
+
**Chrome DevTools MCP not connecting**
|
|
294
|
+
```bash
|
|
295
|
+
claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
|
|
296
|
+
# Restart Claude Code after adding
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
**Slack messages not posting**
|
|
300
|
+
- Token must start with `xoxb-` (not `xoxp-`, `xoxe-`, or `xapp-`)
|
|
301
|
+
- Run `/invite @BugBot` in each channel
|
|
302
|
+
- Required scopes: `chat:write`, `files:write`, `files:read`
|
|
303
|
+
|
|
304
|
+
**Screenshots are blank**
|
|
305
|
+
- Page hasn't settled — increase `pageSettleMs` in `src/config/targets.js` or add a `waitFor` selector for the route
|
|
306
|
+
|
|
307
|
+
**`/argus-retest` returns "dispatch_failed"**
|
|
308
|
+
- Tunnel URL changed — update the Request URL in Slack App → Slash Commands and reinstall
|
|
309
|
+
|
|
310
|
+
**CSS analysis returns empty results**
|
|
311
|
+
- Page may be behind auth — ensure you're logged in on the Chrome instance Argus is controlling
|
|
312
|
+
|
|
313
|
+
**CI pipeline fails immediately**
|
|
314
|
+
- Chrome may not start fast enough — increase `sleep 3` to `sleep 5` in [.github/workflows/argus.yml](.github/workflows/argus.yml)
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## How Argus Differs From Playwright / Cypress
|
|
319
|
+
|
|
320
|
+
Argus is a **complementary layer**, not a replacement for unit or E2E tests:
|
|
321
|
+
|
|
322
|
+
| | Playwright / Cypress | Argus |
|
|
323
|
+
|---|---|---|
|
|
324
|
+
| **Purpose** | Test your logic and API contracts | Catch what the user actually sees |
|
|
325
|
+
| **What it catches** | Regressions in behavior | CSS drift, visual regressions, API loops, console noise, perf budgets |
|
|
326
|
+
| **When it runs** | In your test suite | Continuously, on the live running app |
|
|
327
|
+
| **Setup** | Write test files | Configure routes in `targets.js` |
|
|
328
|
+
| **Output** | Pass / fail | Structured Slack reports with screenshots |
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
## Known Limitations
|
|
333
|
+
|
|
334
|
+
3 permanent test failures (`641/644`) are MCP-layer restrictions — not fixable in Argus code:
|
|
335
|
+
|
|
336
|
+
| Tool | Constraint |
|
|
337
|
+
|---|---|
|
|
338
|
+
| `drag` | Uses mouse simulation, not HTML5 DnD — `dragstart`/`dragover`/`drop` events never fire |
|
|
339
|
+
| `list_console_messages({ types: ['issue'] })` | Issues panel returns empty even when violations exist |
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## Project Structure
|
|
344
|
+
|
|
345
|
+
```
|
|
346
|
+
src/
|
|
347
|
+
argus.js — single-page audit entry point
|
|
348
|
+
mcp-server.js — 9 MCP tools exposed to Claude / any MCP client
|
|
349
|
+
orchestration/ — crawl loop, Slack/GitHub dispatch, env comparison, watch mode
|
|
350
|
+
utils/ — 30+ analysis engines (accessibility, security, performance, etc.)
|
|
351
|
+
adapters/browser.js — CdpBrowserAdapter — wraps all chrome-devtools-mcp calls
|
|
352
|
+
config/targets.js — routes, thresholds, auth steps
|
|
353
|
+
cli/init.js — argus init interactive setup wizard
|
|
354
|
+
test-harness/ — 138-block correctness harness, 62 fixture pages
|
|
355
|
+
test/unit/ — 61 Vitest unit tests (no Chrome required)
|
|
356
|
+
landing/ — Product landing page (React 19 + Vite + Tailwind)
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
Full source map → [CLAUDE.md](CLAUDE.md) · MCP/DSL reference → [SKILL.md](SKILL.md)
|
|
360
|
+
|
|
361
|
+
---
|
|
362
|
+
|
|
363
|
+
## Contributing
|
|
364
|
+
|
|
365
|
+
1. Fork the repo and create a branch
|
|
366
|
+
2. `npm run test:unit` — verify without Chrome (61 tests)
|
|
367
|
+
3. `npm run test:harness` — full integration coverage (requires Chrome on port 9222)
|
|
368
|
+
4. Open a PR — Argus audits itself via the CI workflow
|
|
369
|
+
|
|
370
|
+
---
|
|
371
|
+
|
|
372
|
+
## License
|
|
373
|
+
|
|
374
|
+
MIT © [ironclawdevs27](https://github.com/ironclawdevs27)
|
|
375
|
+
|
|
376
|
+
---
|
|
377
|
+
|
|
378
|
+
<div align="center">
|
|
379
|
+
|
|
380
|
+
*Argus Panoptes — the all-seeing giant of Greek mythology who never slept.*
|
|
381
|
+
|
|
382
|
+
[argus-qa.com](https://argus-qa.com) · [npm](https://www.npmjs.com/package/argusqa-os) · [MCP Registry](https://glama.ai/mcp/servers/ironclawdevs27/Argus)
|
|
383
|
+
|
|
384
|
+
</div>
|