xera

v0.21: HTML report enablement. xera-internal exec <TICKET> --reporter=html writes a Playwright HTML report under the run dir; xera show-report <TICKET> serves it (default 127.0.0.1:9323); xera-internal stage-auth [--role <r>] decrypts the stored web storageState into .xera/.auth/.cache/ so npx playwright test --ui (or any direct Playwright invocation) works against the same session. Plus XERA_HEADED=1 env on auth-setup / exec auth-refresh for interactive SSO / MFA.

v0.20: HTTP auth strategy alignment + AC display polish. xera doctor --strict no longer hard-fails on http.auth.strategy: 'none' (gates the per-role auth-file check on strategy); xera update --auth-strategy custom works; scaffolded mixed-shape auth-setup skips http when strategy is none (fresh xera init passes auth-setup + doctor --strict out of the box). Graph viewer + coverage CLI render AC labels 1-based (AC-1, AC-2, …) to match ticket-tracker convention.

v0.19: Web CONTRACT_DRIFT + self-heal. /xera-report now matches a web test's captured network calls against OpenAPI (opt-in xeraNetwork recorder) and flags CONTRACT_DRIFT per scenario on documented endpoints. When it fires, it can auto-rewrite a single spec.ts assertion to match the contract, re-run, and stage the fix (http-focused) — parallel to the v0.5 selector heal.

v0.18: Feature-from-OpenAPI. /xera-feature <KEY> --from-spec generates Gherkin directly from an OpenAPI document — no fetched ticket — with --tag / --operation / --path filters. Also: xera init now scaffolds a root AGENTS.md orienting any AI agent (never clobbering an existing one).

v0.16: GitHub Issues as an alternative to Jira (xera init --tracker github, ticket keys GH-<n>, no token required — uses the GitHub MCP or gh CLI). /xera-run first-run fix: the health gate is split into env-only Step 0 + ticket-specific Step 1.6 (after fetch), so a fresh ticket no longer deadlocks on its own missing artifacts.

v0.9: Adversarial exploration (experimental, opt-in). /xera-explore <TICKET> brainstorms negative / boundary / race / a11y / security-smell scenarios into a separate explore.feature, untouched by PO review of test.feature.

v0.8: Coverage gap & AC matrix. /xera-coverage reports area-level (UNCOVERED/STALE/COVERED) and AC-level gaps with risk weighting; /xera-fill-gap AI-drafts Gherkin for unsatisfied gaps. Release pipeline unified at a single fixed-group version via changesets — PR titles auto-generate changesets, the Version Packages PR ships every package in lockstep.

v0.7: HTTP API testing — @xera-ai/http adapter, xera init --shape api|mixed, pre-auth via xera:auth-setup, deterministic CONTRACT_DRIFT / RATE_LIMITED / AUTH_EXPIRED against captured HTTP traces.

Backed by a project knowledge graph (v0.6+) that links every ticket ↔ scenario ↔ POM ↔ SUT area ↔ AC, so xera can tell you when a test failure is actually an outdated assertion (not a real bug), what scenarios a ticket might break before you merge, and visualize the whole graph as a single self-contained HTML viewer.

Quickstart

Prereqs: Node ≥22, a supported AI coding agent (Claude Code, Cursor ≥1.6, or OpenAI Codex CLI), an issue tracker (Atlassian-connected MCP / Jira API token or GitHub MCP / gh CLI), and a web app and/or HTTP API to test.

Try it without writing tests of your own: FlowBoard is the official sample target (Fastify + React, both web and api shapes). xera-sample-app-tests is a worked xera consumer project pointed at it — and its graph is published live at xera-ai.github.io/xera-sample-app-tests. See the getting-started guide for the full clone-and-scaffold flow.

npm install -g @xera-ai/cli     # install once globally; or use npx to run without installing

mkdir my-tests && cd my-tests
xera init                       # interactive: answers shape + tracker + ~5 prompts; scaffolds CI workflow
# or fully non-interactive (Jira):
xera init -y --shape api --pk MYPROJ --ju https://myco.atlassian.net --au https://api.example.com --as bearer
# or with GitHub Issues (no token required — uses `gh` CLI or the GitHub MCP):
xera init -y --shape web --tracker github --gr xera-ai/xera --su https://staging.example.com
cp .env.example .env            # fill in credentials
npm install
# Web shape only: npx playwright install chromium
npx xera-internal auth-setup    # pre-authenticate roles (writes encrypted .xera/.auth/)
# Then open your coding agent in this directory:
#   Claude Code:       `claude`
#   Cursor:            open this folder in Cursor
#   OpenAI Codex CLI:  `codex`
> /xera-run SAMPLE-001          # web sample (if shape is web/mixed)
> /xera-run SAMPLE-HTTP-001     # api sample (if shape is api/mixed)
> /xera-run JIRA-123            # your first real ticket (Jira key shape)
> /xera-run GH-42               # …or a GitHub issue when tracker: github

What you get out of the box

Plus npm scripts auto-scaffolded for the project knowledge graph:

• xera:graph-snapshot — derive snapshot from event log
• xera:graph-render — write .xera/graph.html (single-file viewer)
• xera:graph-backfill — synthesize events from existing artifacts (pre-v0.6 projects)
• xera:graph-enrich --ticket <ID> — populate similarity edges via Claude
• xera:disputes — list QA-disputed classifications

CI workflow (.github/workflows/xera-graph.yml, scaffolded by xera init) renders the viewer on every PR and posts a sticky comment with the artifact link — managers click → open graph.html in a browser, no clone required.

Architecture

See the design spec for the v0.1 architecture and the v0.6 design for the project knowledge graph layer. In short:

• @xera-ai/cli — public CLI (init with --shape web|api|mixed --tracker jira|github, doctor [--strict [ticket]], samples remove, show-report <TICKET>)
• @xera-ai/core — config, artifact IO, 9-class classifier (PASS, REAL_BUG, TEST_BUG, FLAKY, SELECTOR_DRIFT, TEST_OUTDATED, CONTRACT_DRIFT, RATE_LIMITED, AUTH_EXPIRED), Jira + GitHub Issues client behind a unified IssueProvider interface, auth state, shared scrub rules, graph module, coverage module, xera-internal binary with 37 subcommands (incl. auth-setup, stage-auth, coverage-prepare, fill-gap-*, explore-*, openapi-resolve, feature-spec-prepare, contract-heal-prepare)
• @xera-ai/web — Playwright adapter, browser-driven (supports --grep per-scenario; opt-in xeraNetwork recorder feeds web CONTRACT_DRIFT detection)
• @xera-ai/http — v0.7 HTTP API adapter, no browser. Pre-auth helpers (defineHttpAuthSetup + presetHttpAuth), runtime newAuthedContext, OpenAPI loader for CONTRACT_DRIFT detection + extractOperations for /xera-feature --from-spec
• @xera-ai/skills — Claude Code skill .md files (dispatch by meta.json.adapter)
• @xera-ai/prompts — versioned LLM prompt templates including feature-from-openapi.md, script-from-feature-web.md + script-from-feature-http.md, and contract-heal.md

Documentation

• Quickstart + commands (this file)
• Configuration reference — including graph + cost telemetry + auto-impact config
• Troubleshooting
• Architecture — condensed dev overview
• Design specs — authoritative design docs (v0.1 core + v0.2/0.3/0.5/0.6 features)
• Implementation plans — task-by-task TDD plans for each release

Roadmap

License

Apache 2.0 — see LICENSE.

Contact

thanh@trinity-technology.com