Record a Scenario locally

Act out a journey in a private Chrome window on your computer. The Composal CLI captures your browser actions and writes a Scenario YAML draft that you can review, run locally, or upload to a Project.

Your app responds directly to local clicks and typing. You can record against localhost or an app reachable from your computer. Recording does not need a Composal login or a model provider.

Before you start

• Install the Composal CLI and Google Chrome or Chromium.
• Start your app, or have its URL ready. Use a URL without credentials, query parameters, or a fragment. Use a test account and test data: actions you perform while recording happen in the app.
• Decide what the journey should prove. You will provide the expected result with --outcome.
• Choose a Persona name for the YAML draft. To upload later, this must match a Persona in your Project.

The local recorder requires Composal CLI 1.17.103 or later. The initial standalone release is available for Linux x64. macOS and npm builds of this command are pending.

On Linux x64, update an existing standalone installation and check that the command is available:

com update
com verify scenarios record --help

If you use npm or macOS, check com verify scenarios record --help before following this guide. Until a supported build is available, use the hosted Record a Scenario feature in your Project.

Use the guided workflow

Check com verify scenarios record --help for --guided. If your installed build does not list it, update the CLI or use the explicit flags below.

com verify scenarios record --guided

The terminal asks for the app URL, Scenario name, existing Project Persona, expected result, and a new draft file. Act out the flow in private Chrome, then return to the terminal and type save. Chrome closes, and the terminal shows the full saved draft for review.

Edit that file in your editor while the review prompt remains open. Choose:

• show to display the current file.
• check to validate its structure offline.
• upload to sign in if needed, choose the Project, and submit this file after a final destination confirmation.
• keep to finish with the draft saved locally.

The guided uploader submits only the reviewed file, even if other Scenarios are beside it. It keeps the creation key, saved Scenario ID, and version in your file so retries do not create duplicate Scenarios. Sign in with com login before uploading; use --org to select the organization when needed.

Reopen an existing draft without recording again:

com verify scenarios record --guided --review scenarios/update-delivery-address.yaml

If upload fails, the draft stays on disk. Fix the reported issue and reopen it with --review. A saved version that has changed in Composal must be reconciled with the latest definition before uploading again.

Start recording

Run this in an interactive terminal, replacing the URL, Persona, and expected result with your own:

com verify scenarios record \
  --url http://localhost:3000 \
  --name "Customer updates their delivery address" \
  --persona "Customer" \
  --outcome "The updated delivery address appears in the customer's profile." \
  --output scenarios/update-delivery-address.yaml

A separate Chrome window opens with a temporary profile. Sign in to your test account if needed, then carry out the journey. Follow links, fill fields, choose options, and submit forms as a tester would. Leave the terminal running.

The recorder keeps committed field values and meaningful clicks and key presses. Focusing a field and typing several characters become a field entry rather than one step per character. Page transitions caused by an action support that action.

Repeat --outcome when the Scenario needs to prove more than one result:

com verify scenarios record \
  --url https://staging.example.com \
  --name "Customer places an order" \
  --persona "Customer" \
  --outcome "An order confirmation number is visible." \
  --outcome "The order appears in order history." \
  --output scenarios/place-order.yaml

Mark an important element

Use a required check when a particular field, button, message, or other page element must be part of the test.

1. In the local recording page, choose Mark important element or press Ctrl+Shift+M.
2. Move over the element you want to mark. An outline identifies the current target.
3. Click the element to select it. This selection does not activate its normal app action.
4. Write what the test must do or verify, then choose Add required check.

For a field inside an embedded frame, focus that frame and press Ctrl+Shift+M to start selection there.

For example, select the Quantity field and write:

Enter 0 and verify that "Quantity must be positive" appears before continuing.

The draft keeps this instruction as a Required check at that point in the journey. Use Escape or Cancel to leave selection without adding a check. If Chrome handles the shortcut itself, use the on-page Mark important element button.

For the hosted Record a Scenario browser, use the shortcut in the outer browser viewer while its remote screen has focus. There, Ctrl+Shift+M marks the currently focused element in the remote app and opens the required-check form. You can also choose Mark important element and select a target with the mouse. In the local recorder, the shortcut starts element selection directly in Chrome.

Save and review

Return to the terminal, type save, and press Enter:

save

The CLI saves the YAML draft and reports the number of steps and its file path. The private browser closes and its temporary profile is removed. Existing output files are never overwritten.

To discard the recording, type cancel or press Ctrl+C. Closing Chrome or reaching the time limit also ends recording without saving.

Open the YAML file and review it before running or uploading:

• Give ambiguous targets enough context to identify the right control.
• Check that each important action and required check is present and in order.
• Confirm that the outcomes describe the result the test should prove. Recording captures your actions; it does not establish that the Scenario passes.
• For an account Persona that Verify signs in automatically, remove initial sign-in setup from the authored journey. Configure its test credentials in the Project.
• Add starting conditions and cleanup when the journey needs existing data or creates records that should be removed.
• Review allowed_actions. Local drafts default to writes; change this to read_only only when the reviewed Scenario does not change app state.

Check the file's structure:

com verify scenarios lint scenarios/update-delivery-address.yaml

Lint checks the Scenario schema without signing in. Upload also checks Project Persona names and other Project references.

Run the Scenario

Run the reviewed draft against your local app:

com verify scenarios run scenarios/update-delivery-address.yaml \
  --local \
  --url http://localhost:3000

Local execution uses the CLI's browser agent and needs model access. Read the generated report and refine the draft until the intended actions and outcomes pass.

To run against a saved Project environment instead, use the Project's configuration and Scenario run commands.

Upload to your Project

If the folder does not already contain project.yaml, download your Project's Scenario configuration first. This creates the upload context alongside its saved Scenarios:

com login
com verify scenarios download --org acme --project storefront --dir scenarios

Replace acme and storefront with your organization and Project slugs. The draft's persona must name an existing Persona in that Project.

Preview the upload, then save the files to the Project:

com verify scenarios upload --dir scenarios --dry-run --json
com verify scenarios upload --dir scenarios --json

Upload checks all Scenario files in the folder and saves them together. Review the dry-run result before uploading a folder that contains other edits. Uploaded Scenarios appear in the Project and can run against its configured environments.

Privacy and limits

The recorder uses its own temporary Chrome profile. Your normal browser profile and saved sign-ins are not imported. The recording process does not upload actions, screenshots, cookies, or storage; it writes the draft locally. Uploading the YAML is a separate command.

Password fields and fields identified as credentials are represented without their values. Ordinary test data entered in other fields is written to the draft. Recorded navigation URLs omit query strings and fragments; add the intended search, filter, or hash-route navigation when your app uses them. Keep secrets out of Scenario names, expected outcomes, and required-check notes. Review the YAML before sharing or committing it.

A recording can contain up to 1,000 steps and 100 expected outcomes. It ends without saving if it exceeds the step limit. Break longer journeys into smaller Scenarios. Run time and browser interaction budgets still apply when executing them.

The default recording deadline is 30 minutes. Use --timeout-seconds to choose another deadline, up to two hours:

com verify scenarios record \
  --url http://localhost:3000 \
  --name "Customer updates their profile" \
  --persona "Customer" \
  --outcome "The updated profile is visible." \
  --output scenarios/update-profile.yaml \
  --timeout-seconds 3600

Browser dialogs, file uploads, canvas interactions, drag-and-drop, controls inside closed shadow roots, and controls without meaningful labels may need manual steps in the draft. Review journeys that use these controls before running them.

Troubleshooting

Use com verify scenarios record --help for the flags accepted by your installed CLI. Continue with Scenario authoring and execution after uploading your reviewed draft.

Prefer recording in your existing Chrome session? Use the Composal Recorder extension to review, submit, and follow runs from a side panel.