@ihyeon/flow-qa 0.1.2 → 0.2.0

package/docs/mobile.md

@@ -0,0 +1,59 @@
+# User-configured iOS and Android targets
+
+Mobile targets require Flow QA `0.2.0` or later and Node.js 24.8 or later. The web demo remains a browser demo; it is not proof of a mobile run.
+
+## Write cases now, connect an app later
+
+Choose **Mobile** on the scenario screen, describe the flow, and generate or download a planning prompt. You do not need to register an app or device to author, validate, compile, or save cases. A mobile suite has `"platform": "mobile"`; existing suites without a platform remain web suites.
+
+With the installed CLI:
+
+```sh
+npm install -g @ihyeon/flow-qa@0.2.0
+flow-qa init ./my-qa
+# Write your mobile flow in my-qa/flows/my-flow.md first.
+flow-qa plan flows/my-flow.md --platform mobile --prompt-only --workspace ./my-qa
+```
+
+Use your chosen AI tool to produce JSON from the prompt, then review and save it under `my-qa/cases/`. Alternatively, configure a planner and omit `--prompt-only`. Neither option needs the target app's source code. Product behavior and accessible element names must still be supplied; unknown expectations remain questions.
+
+## Register an app when ready
+
+In **Connections**, select **iOS** or **Android**, then enter a target name, the installed app's bundle/package ID, and an explicit device name or ID. Register multiple targets to use one mobile suite on both platforms when their accessible labels and expected behavior agree. Use separate suites where the two apps behave differently.
+
+CLI examples below contain placeholders; replace them with your own app and devices:
+
+```sh
+flow-qa connect my-ios --platform ios --bundle-id com.example.app --device "QA iPhone" --workspace ./my-qa
+flow-qa connect my-android --platform android --bundle-id com.example.app --device emulator-5554 --workspace ./my-qa
+flow-qa run cases/my-flow.json --target my-ios --workspace ./my-qa
+flow-qa run cases/my-flow.json --target my-android --workspace ./my-qa
+```
+
+Saving a target only writes configuration. It does not contact a model, boot a device, install an app, or start a test. You can update a saved target by saving the same target name again. The UI checks the reviewed app, platform, and device before dispatching a run; changed settings require another review.
+
+For an iOS simulator, prepare Xcode, an installed simulator runtime, a booted simulator, and a simulator build of the app installed on it. For Android, prepare the Android SDK and a booted emulator or an authorized connected device with the app installed. Physical iOS devices additionally need pairing, Developer Mode, and signing of the upstream automation runner. Follow the [mobile engine's setup instructions](https://e2e.tester.army/docs/mobile#physical-devices) for device-specific requirements.
+
+Flow QA does not download SDKs, create or boot simulators, or install application builds. A missing or unavailable selected device blocks the run; a saved target is not evidence of a working device or app. For physical device IDs that the underlying engine resolves by name, the device name must be unique after case and whitespace normalization; ambiguous selection blocks the run. Chromium is only required for web targets.
+
+## Native steps
+
+| Step | Behavior |
+| --- | --- |
+| `launchApp` | Launch the app registered in the selected target |
+| `click` | Tap an accessible element |
+| `fill` | Enter text in an accessible input |
+| `back` | Use the engine's app back navigation |
+| `swipe` | Swipe the viewport `up`, `down`, `left`, or `right` |
+| `assertVisible`, `assertText` | Check accessible elements and their text |
+| `act`, `assertAgent` | Use the separately configured agent model for an action or judgment |
+
+The compiler launches the configured app at the start of each runnable case unless the first step is already `launchApp`. It does not clear app data or create login state. A launch is not a fresh account/session. The web-only `open` path and `assertUrl` steps are rejected in mobile suites, and native steps are rejected in web suites.
+
+Native `testId` locators use iOS accessibility identifiers or Android resource IDs. Accessibility exposure depends on the app framework. Fixed steps need no model; natural-language steps require a compatible tool/image-capable agent. A WebView's exposed native controls may be usable, but this path does not provide a browser DOM session or prove JavaScript bridge behavior.
+
+## Results and proof boundaries
+
+Mobile reports record platform, app ID, and device rather than a fabricated URL. They use the same case statuses, attempt details, and approved screenshot/text evidence handling as web reports. Comparing different apps, platforms, or configured devices does not produce a direct regression verdict.
+
+Configuration, compilation, mocked runtime tests, and browser UI tests establish the integration behavior. Successful iOS and Android execution still requires recorded results on the user's chosen devices and apps. Flow QA does not supply app-specific cases, accounts, build artifacts, or a device farm.

package/docs/releases.md

@@ -2,11 +2,20 @@
 
 The alpha entries below are historical release records. They document earlier package versions and checks.
 
-## Automated npm releases
+## 0.2.0: configurable mobile targets
+
+Adds native iOS/Android target settings, mobile case authoring before device setup, platform-aware compilation and execution, and app/device identity in review and reports. Users register an installed app and a prepared device when ready; no product-specific app is bundled. Existing web settings and suites remain readable. Node.js 24.8 or later is required by the mobile runtime. Actual native-device success requires a user-selected app and device. See [mobile setup and verification limits](mobile.md).
+
+Locally verified on macOS with Node.js 24.14.1 on 2026-10-12: 89 tests, type checking, UI syntax and design-system audit, package build and fresh tarball installation. Chromium smoke preserved web pass/failure/unavailable classifications and English/Korean UI behavior. The installed package can create a mobile prompt, validate and compile mobile cases before target setup, and save iOS/Android settings. Native generated code was type-checked against the installed SDK; device selection and blocking were tested with inventory fixtures. These checks did not execute a native app or call a model.
+
+- Package: [`@ihyeon/flow-qa@0.2.0`](https://www.npmjs.com/package/@ihyeon/flow-qa/v/0.2.0)
+- Release: [GitHub 0.2.0](https://github.com/hyeonse-swing/flow-qa/releases/tag/v0.2.0)
+
+## Automated npm and GitHub releases
 
 A push to `main` publishes only when `package.json` changes to a new plain `X.Y.Z` version. Pull requests and pushes without a version change run verification without publishing. The package and lockfile versions must agree; the version must increase, and registry errors stop the release. Rerunning a successful publication skips the existing immutable npm version.
 
-The `publish` job in [ci.yml](../.github/workflows/ci.yml) waits for the full verification job, then publishes through npm trusted publishing (OIDC). It uses the `latest` tag and checks the published package with a fresh consumer installation and three real Chromium demo cases. No npm token is stored in GitHub secrets.
+The `publish` job in [ci.yml](../.github/workflows/ci.yml) waits for the full verification matrix on Ubuntu and macOS, then publishes through npm trusted publishing (OIDC). It uses the `latest` tag, requires the registry's `gitHead` to match the workflow commit, and checks the published package with a fresh consumer installation and three real Chromium demo cases. The commit check also applies when retrying an already published version. No npm token is stored in GitHub secrets. After the published package passes its consumer smoke check, a separate job creates the matching GitHub tag and release at the exact verified commit. It preserves existing releases and rejects a tag pointing to another commit. Rerunning an older release does not replace a newer latest release.
 
 For the next release, update the release notes and current installation examples, then bump the version before committing and pushing:
 
@@ -15,10 +24,20 @@ npm version patch --no-git-tag-version
 npm run check
 ```
 
-Push the version change to `main` and check the **Verify release** workflow. A successful verification job alone does not confirm publication: the publish job and its registry smoke check must also pass. Retry a transient failure by rerunning the same workflow; do not reuse a published version for different package contents.
+Push the version change to `main` and check the **Verify release** workflow. A successful verification job alone does not confirm publication: the publish job and its registry smoke check must also pass. GitHub release completion is reported by the separate release job. Retry a transient failure by rerunning the same workflow; do not reuse a published version for different package contents.
 
 The npm trusted publisher is configured for GitHub repository `hyeonse-swing/flow-qa`, workflow `ci.yml`, with direct publishing allowed. See [npm's trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/) for account setup.
 
+## 0.1.3
+
+- `doctor` reports whether each configured planner or agent key environment variable is present, missing, or not configured. English and Korean diagnostics show no credential values and make no model requests. The command remains informational.
+- CLI target and model configuration updates write a private temporary file, synchronize it, and replace the configuration only after the new JSON is complete. Existing initialization and exclusive case-file creation behavior are preserved. This protects against partially written configuration during process interruption; it does not serialize concurrent CLI updates or guarantee rename durability after power loss.
+- CI runs the existing test, browser, UI, and package-install checks on Ubuntu and macOS before publishing. Successful npm publication and its consumer smoke check now also create the corresponding GitHub release.
+
+- Package: [`@ihyeon/flow-qa@0.1.3`](https://www.npmjs.com/package/@ihyeon/flow-qa/v/0.1.3)
+- Release: [GitHub 0.1.3](https://github.com/hyeonse-swing/flow-qa/releases/tag/v0.1.3)
+- Verification: [GitHub Actions](https://github.com/hyeonse-swing/flow-qa/actions/workflows/ci.yml)
+
 ## 0.1.2
 
 Adds version-gated npm publishing from GitHub Actions and npm links in both README languages. Runtime behavior is unchanged from 0.1.1.

package/docs/ui.md

@@ -1,13 +1,13 @@
 # Flow QA local UI
 
-Use the target app's URL and a user flow to review cases, run them, and inspect results. The local example is a to-do app; the UI does not bundle an organization's product list, internal URLs, accounts, model catalog, work cases, or run history.
+Describe a user flow, review cases, and configure a target when ready to run. Web targets use a URL; native targets use an iOS/Android app ID and an explicit device. Mobile targets require version `0.2.0` or later. The local example is a to-do web app; the UI does not bundle an organization's product list, internal URLs, accounts, model catalog, work cases, or run history.
 
 ## Start
 
-Node.js 24 or later is required. Install Flow QA and start the local demo:
+Node.js 24.8 or later is required. Install Flow QA and start the web demo:
 
 ```sh
-npm install -g @ihyeon/flow-qa@0.1.2
+npm install -g @ihyeon/flow-qa@0.2.0
 flow-qa browser install
 flow-qa ui --demo
 ```
@@ -28,17 +28,17 @@ The UI starts in **English**, regardless of browser language. Switch to **한국
 
 ## Workflow
 
-1. **Connections:** Register a target name and URL. Planner and browser agent models have separate settings.
-2. **Scenario:** Describe the initial state, actions, screen elements, and expected results. If a planner is ready, ask it to create cases. Without a model, download the planning prompt and paste a JSON response from an AI you already use.
+1. **Scenario:** Choose Web or Mobile and describe the initial state, actions, screen elements, and expected results. No target is required yet. If a planner is ready, ask it to create cases. Without a model, download the planning prompt and paste a JSON response from an AI you already use.
+2. **Connections:** When ready, register a target name and web URL, or choose iOS/Android and enter an installed app's bundle/package ID and device. Planner and execution agent models have separate settings. Saving settings does not start an app or model request.
 3. **Review and save cases:** Expand each case to read preconditions, actions, expected results, and unresolved questions. Editing the JSON keeps the linked flow; if that source flow changes, design the cases again. Planning and running are separate actions. Editing inputs or connection settings alone does not call a model.
-4. **Run QA:** Review the saved case file, select a target, and check the review confirmation before running. If the file changes after review, reload and review it again. Fixed steps need no agent model. `act` and `assertAgent` require a compatible agent; missing models and unresolved questions are reported as blocked cases.
+4. **Run QA:** Review the saved case file, select a matching web/mobile target, and check the review confirmation before running. If the file or target settings change after review, reload and review them again. Fixed steps need no agent model. `act` and `assertAgent` require a compatible agent; missing models and unresolved questions are reported as blocked cases.
 5. **Case library and Run history:** Save cases as new files and load them again. Open run details to see each case, attempt, and evidence; download the Markdown or JSON report.
 
 The top bar shows planning, running, and stopping states, plus a cancel button. A late planning response cannot change the draft after cancellation. The UI does not estimate progress inside an individual browser action. If the server disconnects, reconnect; runs started in another tab also appear. Refreshing settings rereads targets and models, so save edits first.
 
 For each attempt, the report can open or download an approved screenshot or text evidence item. It serves only evidence linked to the report and marked as redacted or not needing redaction. It does not serve arbitrary files, raw run logs, HTML, or SVG. Markdown and JSON downloads summarize results but do not include evidence files. Keep the original run directory structure if you need relative evidence links in an offline Markdown report.
 
-**Connections** shows whether Chromium is installed. A model key marked ready means only that the named environment variable exists; it does not prove authentication or model compatibility. Case review shows runnable and pre-blocked counts. Login and target reachability are established only by an actual run.
+**Connections** shows whether Chromium is installed for web targets. Mobile execution requires a prepared device and installed app; Chromium readiness does not determine mobile readiness. See [mobile setup](mobile.md). A model key marked ready means only that the named environment variable exists; it does not prove authentication or model compatibility. Case review shows runnable and pre-blocked counts. Login and target reachability are established only by an actual run.
 
 To enter fresh JSON after changing a scenario, open the JSON editor in case review and choose **New JSON draft**. Existing saved files remain; validate and save the new JSON before reviewing it for a run.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ihyeon/flow-qa",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "MIT",
   "author": "Hyeonse Im",
   "repository": {
@@ -38,7 +38,7 @@
   "description": "Turn user flows into repeatable tests and evidence-backed QA reports.",
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": ">=24.8.0"
   },
   "bin": {
     "flow-qa": "./dist/bin/flow-qa.mjs"
@@ -61,8 +61,10 @@
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "3.0.53",
+    "@e2e-dev/mobile": "0.11.0",
     "@e2e-dev/web": "0.11.1",
     "@hyeonse/design-system": "https://codeload.github.com/hyeonse-swing/hyeonse-design-system/tar.gz/38978c6a86f422fc0e63e919f600bc2dd3451e5c",
+    "agent-device": "0.21.22",
     "ai": "7.0.107",
     "e2e": "0.16.0",
     "playwright": "1.63.0",