Skip to main content
Free plan, no cardStart free
Suites, runs and planning 9 min read Updated

Test Folders: suites that run as one job

A test folder holds the test files that run together as one job. Each file is a list of steps you edit in a table: start it from a recording (a copy, the recording itself is never changed) or from nothing, add variables, choose the browsers, split the run across runners, and run it as a bot identity when the application needs a signed-in account. The result page shows every step, what was expected and what was found, and a diagnosis that names the biggest problem first.

About this guide

Written for
QA leads and test managers · SDETs and automation engineers

Where it fits

Test Folders is the suite layer over the recorder. A recording is one flow; a folder is the set of flows you want to run and read as one result. It sits on the dashboard of every signed-in account and uses the projects entitlement: Solo Pro and above include it, and on the Free plan it comes with the Projects & traceability tool on the pricing page. The folder-run allowance for the month is shown at the top of the page with the date it resets.

Until the first run has completed, the page shows a three-step card: create a folder, add a test file, run it and read the result. A "Try a sample folder" link creates a ready-to-run check of a public page's title, so you can see a green result in under a minute before touching your own application.

Your first green run

  1. Choose Create Test Folder and give it a name (a description is optional).
  2. Open the folder and choose New Test File. Start from a recording, which copies its steps into the file, or start with a blank file and add steps yourself.
  3. Press Run. The result opens with a row per step; a failed step shows what was expected and what the page gave.

Editing steps

A file is a table. Each row has the action, a Selector / Target, a Value / Input and, for assertions, an Expected value, which may be a `{{keyword}}` or a `${var}` resolved at run time. A row can be enabled or disabled, duplicated, inserted after, and pinned to the main window or to a popup window when the recording opened one. The keyword reference beside the editor is searchable (assert, click, wait) and marks the keywords that need an Expected value. Function keywords are masked in the preview and resolved when the run happens.

Save with Ctrl+S or the Save button; leaving with unsaved changes asks first. When a teammate saved the same file while you were editing, the save stops with three choices: go back to your edits, load the newer version, or keep your edits and overwrite. Two more actions keep a file in step with its recording: Re-import compares the file with the recording and lets you apply some or all of the differences, and Repair steps backfills a missing selector or value from the recording.

Variables and data-driven runs

The variables editor adds named values a step refers to as `{{name}}`; they are resolved at run time, so one file serves several environments. A variable with several values is a matrix: the run expands into one run per combination, up to the limit of runs per file. An upload step takes a file from Test Files, the library every plan has, so a fixture lives in one place and is never pasted into a step.

Running: browsers, sharding and bot identities

  • Select the browsers the run uses; each file runs once per selected browser.
  • Parallel sharding splits the files round-robin across runners: set the shard total and which shard this runner is.
  • Run as a bot identity when the application needs a signed-in account: one authorised identity is allocated per selected browser, its stored session is reused, and the run stays on a single tab. When no identity is free the run is refused rather than run signed out, or it waits up to 1, 5 or 15 minutes for one to free up. The network path is this server (a fixed egress address) or a VPN lane into your own network.
  • A bot identity is registered without a password: the secret stays in the credentials vault and the identity carries a reference to it. Sign in once yourself, export the browser state, and import it into the identity; or attach a client certificate (.pfx or .p12) when the account signs in with one. Two failed sign-ins lock the identity so the platform never locks the account itself. Your identities are private to you unless you share one with the workspace.

Reading a result

Test Results lists each file with its steps: the selector and value used, a screenshot, and for a check the expected text, the text found and the comparison mode; a calculation step shows the parsed values, the difference, the tolerance and the formula; an extraction step shows what it extracted. Runtime variables are listed with the run, and a paused run can be resumed from the step it stopped at.

The run diagnosis groups the failures: the root problems first, biggest first, each with the next action to take and the failures it knocked on; a problem that keeps failing across recent runs is marked as such. Heal candidates the run refused are listed for the review queue, which an administrator works. Flake detection labels each file Flaky, Broken or Healthy from its history and recommends quarantine when the failure rate passes 20%. The visual report shows new baselines, the regression rate, the largest difference and the checks awaiting approval.

Two planning tools sit beside the results. Test impact analysis takes the output of `git diff --name-only main` and ranks the files to run first. Scenario allocation reads your requirement analyses and recording scenarios and proposes smoke, critical-path, regression and extended folders; a dry run shows the allocation, a commit creates the folders, and a folder created this way is marked unverified until someone runs it.

Assessment QA: synthetic learners

For a quiz or assessment application, a file can carry assessment steps (grade against a key, the timer, autosave, network loss and resume, the back button, accessibility) and the folder plans how many learners run it at once: real-browser scouts measure what a learner sees while a protocol swarm gives the server the concurrency, within a requests-per-second cap you set. Every target host must be authorised first; a preview shows the plan without starting anything.

Questions people ask about this

Does editing a test file change the recording?
No. A file started from a recording is a copy. The recording stays as captured, which is why Re-import and Repair can read it back later.
What happens when no bot identity is free?
The run is refused, or waits for the time you chose, and says so. It never runs signed out and never falls back to a shared browser without telling you.
Two of us edited the same file. Who wins?
Nobody silently. The second save stops and offers three choices: back to your edits, load the newer version, or keep your edits and overwrite.

Source: /documentation/test-folders, updated 2026-11-16. Answers are checked against the shipped product on that date.

Found something out of date? The people who build the module answer the contact form on the home page, and corrections to this guide are dated above. Tell us.

This guide is about regression testing, the job that suites, runs and planning serve. Twenty tools, including ours, are compared by job.

Try it against your own app.

Record one flow and get four kinds of evidence back. Judge the results yourself.

  • Free plan, no card
  • 14-day Solo Pro trial
  • Demo replies within one business day
  • Data hosted in India