Start

Explore: a first suite in one command

TestedOK walks your app, maps its screens, and drafts v1 flows for you to edit.

You do not have to write the first flows yourself. Point TestedOK at an installed app and it walks the app, maps what it finds, and writes a draft suite: real flow files, in your tests/ folder, for you to read and edit.

testedok explore com.example.rote
Exploring com.example.rote on iPhone 17 Pro…
  s1 Rote
  s2 Today  ← Today
  s3 New list  ← Add
  s4 Settings  ← You
  s5 Appearance  ← You › Appearance
  …
9 screens, 23 taps, 41s. Drafting flows…
 
Wrote 6 draft flows:
  tests/open-today.json
  tests/create-a-list.json
  tests/change-appearance.json
  …
 
Read them, edit what is off, delete what you do not want, then: testedok run tests

What it does

  1. Walks the app. From the first screen it taps what looks safe: tabs first, then rows and buttons. It never taps anything that deletes, pays, sends or signs out, and it never types. To get back it uses a Back or Cancel when there is one, and otherwise relaunches the app and retraces its steps. It stops after 20 screens, 80 taps, or the --budget in seconds (--max-screens changes the first).
  2. Maps what it saw. Each screen's visible text, its controls with their labels, its text fields, and the tap that led there. The map is saved as tests/.explore-map.json if you want to look.
  3. Drafts flows. The map goes to the TestedOK API, where a model proposes four to eight flows that cover different screens, following the same advice as goals that pass: controls named exactly as labelled, one thing per flow, values in data, an expectation taken from the destination screen's own text. Each file carries a note saying it is a draft.
tests/create-a-list.json
{
  "name": "Rote: create a list",
  "app": { "bundleId": "com.example.rote" },
  "goal": "On the Lists tab, tap \"Add\", type the value of list_name into \"List name\", and tap \"Save\".",
  "expectText": ["Test list {{run}}"],
  "data": { "list_name": "Test list {{run}}" },
  "maxSteps": 8,
  "note": "Drafted by testedok explore from screen s3. Edit the goal and expectText to taste; delete what you do not want."
}

Verify the drafts

testedok explore com.example.rote --verify

With --verify, each draft that can run is run once, right after it is written. Drafts that pass stay as they are; a draft that does not gets the reason appended to its note ("First run did not pass: …"), so the folder opens with known-good flows and the rest say what to look at. The summary tells you how many pass as written.

Drafts that need a fixture

Some flows cannot run without something first: a signed-in test account, a password, an emailed code, a system permission, or items that must already exist in the app. The model marks such a draft with needs and writes its goal with the placeholders TestedOK provides ({{ account.user }}, {{ secrets.password }}, {{ inbox.code }}) rather than made-up values; its note says what to set up, in the words of Test accounts, Secrets and Inboxes. --verify skips them.

What changed since last time

Running explore again on the same folder compares the new map with the previous one and prints what appeared, what was not reached, and which screens gained or lost controls:

Since the last explore:
  + Stats  ← You › Stats
  - Onboarding (not reached this time)
  ~ Today: new: "Filter"; gone: "Sort"

The project's app map learns the screens too, and the CLI says how many were new to it.

Budget and destructive controls

--budget 120 stops the walk after two minutes with what it has; --max-screens caps screens. --allow-destructive also taps controls that delete, send or sign out — for a throwaway build or account, never a real one. Nothing that pays, buys or subscribes is ever tapped.

YAML flows

--format yaml writes the drafts as .yaml files. Flows can be JSON or YAML anywhere: testedok run finds both, and requires resolves either.

tests/create-a-list.yaml
name: "Rote: create a list"
app:
  bundleId: com.example.rote
goal: On the Lists tab, tap "Add", type the value of list_name into "List name", and tap "Save".
expectText:
  - Test list {{run}}
data:
  list_name: Test list {{run}}
maxSteps: 8

Then edit

The drafts are a starting point, not a verdict. The model saw a map, not your intentions: it may pick a screen you do not care about, expect a label that changes, or miss that a button sits below the fold. Open each file, fix the wording against the real screen, delete the ones you do not want, and run the folder. A flow that passes saves its route and is cheap from then on.

Running explore again writes new files beside the old (-2, -3); it never overwrites one you edited.

Where it stops

  • Screens behind sign-in are reached only if the app is already signed in on the device. Sign in once (or use a build with a test session), then explore.
  • Modal sheets and alerts count as screens; a sheet with only "Cancel" is recorded and left.
  • Apps that ask for a permission on the first screen get the system dialog as their first screen. Grant it in setup or by hand, then explore again.

From a coding agent

explore_app over MCP does the same and returns the files it wrote, so an agent can explore a fresh build, read the drafts, tighten them, and run them without you.