@app-studio/qa-studio

Debug Studio and browser adapters for two explicit contracts.

State Fixture v3

A render-only component or screen state:

{
  "schemaVersion": 3,
  "kind": "state-fixture",
  "screen": "content/notes:NotesListPage",
  "outcome": "worst",
  "states": [{
    "id": "content/notes:empty",
    "summary": "A new workspace has no notes yet",
    "routes": [{ "match": "/notes", "method": "GET", "answer": { "items": [] } }],
    "persona": "connected",
    "viewport": { "preset": "desktop" }
  }]
}

The same fixture feeds component tests, Debug Studio, and qa state run --id. It contains no product actions and makes no end-to-end claim.

import { installState, statesFrom, type StateFixtureFile } from '@app-studio/qa-studio';

The React host supplies StateEntry[], renderState, persona setup, and optional store bootstrap. Deep links use ?state=<id> and the rendered boundary exposes data-state=<id>.

Browser adapters add qa-studio=agent by default. In that presentation, Debug Studio mounts only the selected application pane: no toolbar, state picker, catalog navigation, or human seed warning. Opening the Studio directly without that parameter keeps the full interactive shell. An application-owned adapter can opt back into it with studioPresentation: 'interactive'.

Original App Studio feature flows

The original specs/features/*.json files are executable. The core compiler joins feature.userExperience to optional specs/forms/*.json, separates each if condition from the nominal path, and materializes a portable flow for Playwright or wdio/Appium:

import { defineScenarioSuite } from '@app-studio/qa-studio/playwright';

defineScenarioSuite({
  test,
  expect,
  rootDir: process.cwd(),
  pattern: 'specs/features/*.json',
  forms: 'specs/forms/*.json',
  prepare: async ({ scenario }) => prepareFeatureWorld(scenario),
});

User actions operate the control named by the original eventId (or the form's exact data-testid). App actions assert routes, real requests and modal state. Explicit Scenario v3 files remain supported for non-generated repositories, but App Studio projects do not copy their flow into one.

QA_BROWSER_PROFILE=fast runs the same compiled feature flow and writes its machine-readable report without checkpoint media. The default proof profile keeps the strict visual evidence. Browser engine selection remains application-owned and is addressed through qa scenario run --engine ....

Targeted state browser adapter

defineStatesSuite({
  test,
  expect,
  rootDir: process.cwd(),
  pattern: 'src/features/**/states/*.state.json',
});

Lightpanda hosts should use @app-studio/qa-studio/puppeteer. Its runPuppeteerScenarioSuite and runPuppeteerStateSuite functions preserve the same JSON graph, request evidence and verdicts without Playwright Test's Chromium-only context emulation. The application still owns server startup, the CDP process, and its State Fixture preparation callback.

QA_STATE_ID narrows execution to one fixture. The CLI also sends QA_BROWSER_HEADLESS=true and QA_STUDIO_PRESENTATION=agent. The adapter waits for the real rendered boundary, checks non-empty DOM unless rendersNothing is declared, collects page errors, and reports fabricated API answers. It adds no dwell time, captions, or video requirement.