@sitelensapi/qa-smoke

Shared SiteLens smoke QA step schema, parser, and Playwright executor used by @sitelensapi/mcp (local runs) and sitelens-api (cloud saved flows).

Install

This package is normally installed as a dependency of @sitelensapi/mcp. Direct install (advanced / API integrators):

npm install @sitelensapi/qa-smoke

Requires playwright as a peer dependency (>=1.49.0).

Usage

import { parseQaSmokeStep, executeQaSmokeSteps, qaSmokeStepSchema } from "@sitelensapi/qa-smoke";

See docs/sitelens-agent-smoke-qa-v1.md for the shared step vocabulary (including selectOption, Tier 1/2 interactions, storage, screenshot, network request.json / response.json, and bundled network trigger). Design notes: docs/network-observation-assertions.md.

Optional @sitelensapi/observe integration (Browser DevTools Observability)

This package has an optional workspace:* dependency on @sitelensapi/observe. Pass a BrowserEventSession (or any object structurally matching QaSmokeBrowserEventSession) to executeQaSmokeSteps(page, viewport, steps, { browserEventSession }) to unlock:

• Lookback network waits — waitForRequest / waitForResponse / expectNetwork / captureResponse match via session.waitForNetwork, so an exchange already captured in the session buffer resolves immediately instead of racing a fresh Playwright listener.
• Richer network matchers — optional host, filename, query fields on network steps.
• Observation/console/diagnostics steps — observation.boundary, observation.configure, waitForConsole, expectConsole, expectNoConsole, expectNoPageErrors, expectPageError, expectNoFailedRequests, expectNoBrowserDiagnostics (all require a session and throw a clear error without one).
• Downloads / WebSocket steps (opt-in) — expectDownload, waitForWebSocket, expectWebSocket also require the session's capture policy to opt into categories.downloads / categories.websockets (verbose capture mode, or an explicit custom policy); with the category disabled no matching events are ever recorded, so these steps simply time out.
• Auto-attached diagnostics on failure — a failed step's log entry gets a capped diagnosticsFindings summary from analyzeBrowserDiagnostics.

Without a session, everything works exactly as before (Playwright-only fallback). See docs/network-observation-assertions.md (Phase 6) for details.

Monorepo

pnpm --filter @sitelensapi/qa-smoke run build
pnpm --filter @sitelensapi/qa-smoke test
pnpm --filter @sitelensapi/qa-smoke run pack:check

License

See repository root for license terms before publishing.