@amedia/argus

@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.