.BugRadar/, and every recognized key in flow files, suite manifests, and hook scripts.
Repository layout
Everything BugRadar manages lives under a single.BugRadar/ folder — at your repository root by default, or under a subdirectory you point BugRadar at (see Monorepos). Flows are *.flow.yaml files, a suite is a directory containing a _suite.yaml manifest, and hooks are script files under a hooks/ directory.
The sync reads
BugRadar.md at the root of .BugRadar/, files that end in .flow.yaml, are named exactly _suite.yaml, or scripts directly inside a hooks/ folder with a supported extension. Every other file under .BugRadar/ is ignored, including config.yaml, which only the CLI reads.Flow files
A flow file ends in.flow.yaml. The only required keys are name and instructions, where instructions is either a single multiline prompt or a YAML list of steps.
As a multiline prompt:
Exporting caching settings
CLI 0.9.15 and later preserve each caching mode when exporting flows. Older CLI versions export an explicit Standard limit as caching Off, because their boolean format cannot preserve that limit. Upgrade the CLI before exporting to retain the exact setting.Referencing variables
Define flow overrides in*.flow.yaml and suite defaults in _suite.yaml with variables:
CODE: "00123", ENABLED: "false").
Names use letters, digits, and underscores, and cannot start with a digit.
A supplied map replaces that flow’s or suite’s overrides on sync. Omit variables to keep existing values, or use variables: {} to clear them.
Keep secrets in Environments, since YAML values are committed to your repository.
Referencing hooks
Attach hooks to a flow withsetup_hooks and teardown_hooks, each an ordered list of hook slugs:
lease-email-address and Lease phone number as lease-phone-number, and the sync adds the hook to your organization if it isn’t there yet. If one of your own hooks already uses that slug, your hook is used instead.
Duplicate slugs within one list are rejected. The same slug may appear in both setup_hooks and teardown_hooks — that’s legal. To reference a hook by name inside your instructions at run time, use ${hooks:Hook Name} (by display name); see Hooks. On a run pinned to a commit (an API run with ref, BugRadar run --ref, BugRadar’s pull-request test runs, or a CI run with a branch build’s app_build_id), the branch’s hook file of that name runs, including one the branch adds. Working-copy runs (--local or --cloud) use your local file.
When the list mixes scripts with a launch-args (.json) hook, the app starts where that hook sits — see when launch configuration runs.
Labels
Attach labels to a flow or suite withlabels, a list of label names:
labels leaves the flow/suite’s existing labels untouched — an explicit labels: [] clears them. Labeled flows and suites dispatch via run-by-label as usual.
The built-in snoozed label is the exception. List it to snooze a flow:
- Remove
snoozedfrom the file to unsnooze the flow on the next sync. Omittinglabels, orlabels: [], also removes it. - A snooze added in the dashboard stays even when the file leaves
snoozedout, includinglabels: []. Only the dashboard removes it. - When both the file and the dashboard snoozed a flow, it stays snoozed until both remove it. Unsnooze in the dashboard removes only the dashboard’s snooze. When only the file snoozes a flow, Unsnooze is unavailable, and the API refuses with
409. - A branch or commit run reads
snoozedfrom the file at that commit. A flow snoozed in the dashboard is also skipped there.
Suites
A suite is a directory containing a_suite.yaml manifest. The suite’s key is its directory path (a smoke/ directory gives the suite key smoke). The only required key is name:
The Lease email address and Lease phone number built-in hooks may be listed in a suite’s
setup_hooks. Unlike ordinary suite setup scripts, a lease hook is inherited by every member flow and creates a separate inbox or number for each flow run. The suite’s setup_flow, when configured, receives its own lease too. This also applies when parallelize_flows: true. These built-ins are setup-only and are rejected in teardown_hooks. Reference them as lease-email-address and lease-phone-number; you don’t need to add them from the Hook Library first.
References in flows and setup_flow resolve sibling-first: a flow directly in the suite’s own directory wins, otherwise the reference is matched against every flow in the repo. A suite directory cannot hold directories of tests; the sync fails and names the directory to move out. Flow keys and suite keys must each be unique across the whole repo. An unknown reference, or the same flow listed twice, is a validation error.
The
_suite.yaml file must live inside a directory — it cannot sit at the .BugRadar/ root, because a suite is a directory. Membership is defined by the suite (its flows list or its directory), never declared inside the flow files themselves.Folders
Each directory under.BugRadar/ that holds tests, at any depth, shows as a folder on the Flows page. The top folder from a repo shows the repo’s name, linked to that directory in your repo. Directories can nest as deep as you like.
- A suite directory (one with
_suite.yaml) is a suite, not a folder. It cannot hold directories of tests. - A flow file the suite lists shows under the suite only. A flow file the suite leaves out shows in the folder that holds the suite.
hooks/directories, and everything below them, are not folders.- Spaces at the start or end of a directory name are dropped from the folder name.
- Folders from a pull request appear when it merges to your default branch.
Moving files
Moving a flow file to another directory keeps its run history when the file name stays the same. If several moved files share a name, a file keeps its history only when exactly one new file matches it on the folder around it as well as the name, and that new file matches no other old file as closely. For example, renamingCheckout/ to Payments/ keeps the history of both Checkout/web/happy-path.flow.yaml and Checkout/ios/happy-path.flow.yaml. If that’s not clear-cut, those files start as new tests. Moving a suite directory works the same way, matched on the directory name.
Otherwise the old test is archived and a new one starts. That includes moving and renaming a file in one commit, or moving it across two commits.
What a move does not carry over:
- Results of runs on a branch, which are saved by key, stay under the old key.
- A branch cut before the move still has the old path. Its runs create a separate test under the old key.
flows or setup_flow entry that names an old key then stops the whole sync. When only one flow could be the moved one, the error names its new key. CI scripts that name keys need updating too. To keep keys fixed when you move files, set key: in each file.
Hooks as files
Hooks live as script files inside ahooks/ folder — either .BugRadar/hooks/ or <suite>/hooks/. The file extension determines the hook type, and the filename becomes the hook’s slug.
The slug is derived from the filename with its final extension removed: lowercased, with runs of non-alphanumeric characters collapsed to
-. So Seed DB.sh becomes slug seed-db, and reset.env.json becomes reset-env. This slug is what you reference in setup_hooks / teardown_hooks. The display name is the humanized filename (reset-test-env.sh shows as “Reset Test Env”).
The file content is the hook script, stored verbatim. Empty or whitespace-only files are rejected. A
.json launch-args hook must parse as valid JSON, and a filename with no letters or digits (so it produces an empty slug) is rejected..py, .js, .ts, .sh) read environment variables natively — os.environ.get(...) in Python, process.env in JavaScript/TypeScript, $VAR in Bash. Launch-args (.json) hooks — and dashboard-authored cURL hooks — use the ${env:KEY} token instead, since they aren’t executed scripts. cURL hooks have no file form; reference an existing dashboard cURL hook by slug, or use a .sh hook that runs curl. See Hooks for the full hook model.
Config file
config.yaml at the root of .BugRadar/ sets defaults for BugRadar run. It is not a test: the sync never reads it and the CLI never uploads it. How the defaults apply is on Running from the CLI.
Any other key, an unknown platform, or a mobile entry without
bundle_id (or a web entry without app_id) is an error. BugRadar flows validate reports it, and BugRadar run refuses to start until it is fixed.
Monorepos
By default BugRadar looks for.BugRadar/ at your repository root. If your definitions live in a subdirectory — common in a monorepo — point BugRadar at that folder with the repo’s Root directory setting.
- Go to Settings > Integrations > GitHub
- On the connected repo, set Root directory to the folder that contains
.BugRadar/(for example,services/mobileforservices/mobile/.BugRadar/) - Leave it blank to use the repository root
.BugRadar/, so moving your definitions into a subdirectory doesn’t change any keys — a flow at services/mobile/.BugRadar/login.flow.yaml still has the key login. The GitHub links on each row point at the full path in your repo.
Saving a new Root directory doesn’t re-sync on its own. Click Resync on the repository card, or push to the default branch to sync from the new location. Once
.BugRadar/ has been detected, the nightly resync also checks it for drift.