A project is the container for tests that share an application, an environment and a set of defaults. It is the least glamorous object in Studio and the one that causes the most trouble when it is drawn badly, because almost everything else inherits from it.
This article covers what a project actually governs, how to decide where the boundaries go, and the two mistakes that are expensive to undo.
What a project governs
| The tests inside it | Tests belong to exactly one project. An orchestration draws its tests from a single project, so the boundary you choose decides what can be run together as one job. |
| The default settings | Execution behavior, timing model, self-healing, browser behavior and timeouts are set here and inherited by every test. A test can override them, but it has to say so deliberately. |
| Execution presets | Named bundles of settings and variables live at project level. This is how the same tests get pointed at a different environment without editing them. |
| Reporting | Reports breaks pass rate down by project. So a project boundary is also a reporting boundary — if you want a number for a team or an application, it needs to be its own project. |
Where to draw the boundary
The useful question is not "how should we organize this?" but "what should share a default?" Tests that want the same timing model, the same environment and the same answer to "who reads a red result" belong together.
In practice that usually means one project per application per environment — or one per application, with environments handled by execution presets. Both work. What does not work is a boundary drawn around something that does not share defaults.
If these tests were red together, would the same person care, and take the same first action? If yes, one project. If no, two.
Two mistakes that are expensive to undo
| One project for everything | Every test inherits one timing model and one set of defaults, so the slowest environment sets the pace for all of them. Reports gives you a single pass rate that no team recognizes as theirs. This is the common one, because it is the path of least resistance in week one. |
| A project per feature | The opposite failure. Orchestrations cannot span projects, so a critical journey that crosses two features can no longer be run as one job. Feature is a tag, not a project. |
Use tags for everything else
Almost every distinction people reach for a project to express — feature, team, speed, risk tier — is better expressed as a tag. Tags drive filtering, orchestration membership and reporting, and a test can carry several. A project cannot.
A consistent tag scheme agreed early (smoke, checkout,
slow) is what lets you assemble a suite by meaning rather than by
hand-picking tests. Tags are set in General → Test details —
see Settings: Where Everything Lives and What to Change First.
Settings: change the project, not the test
Project settings are defaults; test settings are exceptions. Most test-level settings carry an Override project default toggle, and the practical rule is to leave it off unless the test is genuinely different.
A setting tuned on forty individual tests is invisible and impossible to reason about. A project default with three deliberate exceptions is something a colleague can read. Settings: Where Everything Lives and What to Change First maps every section, and Self-Healing and Timing: Controlling How Studio Recovers covers the two that matter most.
Environments, without duplicating tests
The instinct is to copy a project per environment. Use execution presets instead: a named bundle of settings and variables, selected at run time, so one set of tests runs against staging or production without being edited or duplicated.
Duplicated projects drift. Within a month the staging copy has three fixes the production copy does not, and nobody knows which is authoritative. See Test Data: Execution Presets, Variables and Secrets.
When several teams share Studio
Project boundaries are the first convention to agree, before test naming or tier tags, because everything else inherits from them and they are the hardest to change later. Agree five things up front: project boundaries, test naming, tier tags, the promotion rule and who reads red. Scaling From One Team to Many covers each in turn, and How It All Ties Together: Studio Across an Enterprise shows how the objects relate across an organization.
Where to go next
- Settings: Where Everything Lives and What to Change First — what each project setting does.
- Test Data: Execution Presets, Variables and Secrets — environments without duplicated projects.
- Orchestrations: Running a Suite as One Job — what the project boundary lets you run together.
- Reports: Pass Rates, Trends and What They Actually Tell You — the per-project numbers your boundary decides.