Skip to main content
A suite is a YAML manifest that groups individual test files into a logical collection you can run together. Rather than running tests one at a time, you define a suite for each feature and run every scenario in it with a single command. Suite manifests live under .finalrun/suites/.

​
Suite fields

​
string
required
A stable identifier for the suite. Use snake_case. This name is what you pass to finalrun suite when you want to run it.
​
string
A short, human-readable summary of what the suite covers. One or two sentences is enough.
​
list of strings
required
An ordered list of test file paths. Each path is relative to .finalrun/tests/. The agent runs the tests in the order listed.

​
Example suite

​
Organizing suites by feature

The recommended convention is one suite per feature folder, mirroring the structure of .finalrun/tests/<feature>/. A suite named auth_smoke covering tests in .finalrun/tests/auth/ is a clear, predictable mapping that makes it easy to find which suite runs a given test.
Name your suite files after their feature folder. If your tests live in .finalrun/tests/checkout/, name the suite file .finalrun/suites/checkout.yaml and give it the name: checkout identifier. This one-to-one convention keeps suites discoverable as the test library grows.

​
Running a suite

Pass the suite manifest path to finalrun suite. Specify a platform and AI model:
You can also target iOS:

​
Validating a suite before running

Run finalrun check with the --suite flag to validate the suite manifest and all referenced test files — confirming that paths resolve, placeholders are declared, and the workspace is configured correctly — before spending time on a full test run:
Fix any errors reported by finalrun check before proceeding. The command output is the source of truth for binding correctness and path resolution.