@amedia/argus

AI-powered root-cause analysis of failed Playwright test traces.

Argus parses a Playwright trace.zip, distills the signal (assertion error, last URL, recent actions, console/page errors, failed network requests), and asks Gemini to connect those signals into a short root-cause summary for an on-call engineer.

v1 is Gemini-only and emits Slack mrkdwn. See Roadmap.

Install

npm install @amedia/argus

Requires Node ≥ 18. @playwright/test is an optional peer (only its JSON report format is consumed — argus does not run tests).

Library API

import { analyzeTrace, parseTraceZip } from '@amedia/argus';

// Full pipeline: report -> failed specs -> parse traces -> Gemini summaries
const summaries = await analyzeTrace({
  reportPath: './reports/report.json',
  apiKey: process.env.GEMINI_API_KEY!,
  model: 'gemini-3.1-pro-preview', // required — model names rotate
});
// => { "completes purchase": "*Likely cause:* ...", ... }

// Or just parse a trace.zip into structured signals (no AI):
const parsed = await parseTraceZip('./test-results/checkout/trace.zip');

Also exported: summarize, failedSpecs, lastResultForSpec, tracePathFromResult, projectFromSpec, and all types.

CLI

Two env-driven binaries for CI use:

| Bin | Purpose | |---|---| | argus-analyze | Read report → summarize failed traces → write summaries.json | | argus-build-field | Encode summaries as a base64 Slack mrkdwn blob for GitHub Actions |

Environment variables:

| Var | Default | Used by | |---|---|---| | REPORT_PATH | ./reports/report.json | analyze | | SUMMARIES_PATH | ./summaries.json | analyze, build-field | | GEMINI_API_KEY | — (required; skips if absent) | analyze | | GEMINI_MODEL | — (required; skips if absent) | analyze | | GITHUB_OUTPUT | — (set by Actions) | build-field |

Both bins exit 0 even on error — analysis is best-effort and must not fail a CI job.

GitHub Actions

- name: Analyze failed traces
  if: always()
  env:
    REPORT_PATH: reports/report.json
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
    GEMINI_MODEL: gemini-3.1-pro-preview
  run: npx -p @amedia/argus argus-analyze

- name: Build Slack field
  id: ai
  if: always()
  run: npx -p @amedia/argus argus-build-field
  # exposes step output `ai_summary` (base64 Slack mrkdwn)

Roadmap

• Pluggable AI provider — abstract behind a SummaryProvider interface so Anthropic / OpenAI can plug in alongside the default Gemini provider.
• Neutral output + optional Slack formatter — return structured { title, summary }[] and ship formatSlackBlock() as an opt-in helper, so non-Slack consumers can use raw summaries.

License

Apache-2.0 © Amedia AS. Published to the @amedia npm org with public access — no auth required to install.