Shared steps

A shared step is a titled, ordered set of steps — action, data, expected result, and images, or keyword, text, and argument in a Gherkin set — that test cases use instead of copying the same steps. Log in, set up a cart, clean up test data: write it once, insert it into every case that needs it, and edit it in one place. Every case that uses it shows the change the next time it is opened; runs that already started keep the steps they had.

Question	Answer
Where do shared steps live?	In a project (usable by that project’s cases) or organization-wide (usable by every project).
Who creates project shared steps?	Members and above, on every plan.
Who creates organization-wide ones?	Owners and admins, on the Pro and Enterprise plans (and during a trial).
What does a run show?	The shared step’s steps as ordinary numbered steps.
What happens when I delete one?	You choose: keep its steps in every case as ordinary steps, or remove them.
Which cases can use one?	Only cases of the same step format, Classic or Gherkin. The format is fixed at creation.

Opening the library

Open a project, then click Shared steps in the project sidebar, right after Repository. The library lists every shared step the project can use: its own and the organization-wide ones.

Each entry in the list shows the shared step’s title and ID, how many steps it holds, how many test cases use it (Not used when none does), when it last changed, and an icon for its scope: project or organization-wide.

Click a shared step to open it. On a wide screen it opens next to the list, so you can move from one to the next without leaving the library; the up and down arrow keys do the same. On a smaller screen it opens as its own page.

Use the search box to filter by title. The folder menu above it narrows the list: All shared steps, This project, Organization, or any folder inside them. The list keeps your folder and search while you open shared steps.

Each shared step also has a readable ID, SS-1, SS-2, … — one sequence for the whole organization — shown in its page’s address. An ID is never reused: after SS-7 is deleted, the next shared step is SS-8, and making a project shared step organization-wide keeps its ID.

Creating a shared step

Click New next to the library’s title.
Enter a Title (up to 255 characters), for example Log in as an administrator.
If you are an owner or admin on a plan with organization-wide shared steps, choose where it is Available in: This project or Organization. Everyone else creates project shared steps.
Optionally pick a Folder of that scope, then click Create shared step.

The dialog also asks for the Step format, Classic or Gherkin. It cannot change once the shared step exists, and only cases of that format can use the set.

Open the new shared step and add its steps on the Steps tab with Edit steps: each step has the fields of its format, exactly like a test case step (an action with optional data and expected result, or a keyword with text and an optional argument), and can carry images. A shared step holds up to 500 steps. A shared step cannot contain another shared step.

Organizing with folders

Folders keep related shared steps together, and they nest. The project and the organization each have their own folder tree: a folder only holds shared steps and subfolders of its own scope.

Open the folder menu to manage folders: + next to This project or Organization creates a folder, and a folder’s ⋯ menu holds New shared step (created in that folder), New subfolder, Rename and Delete. Two folders side by side cannot share a name.
Shared steps that are in no folder are listed under Shared steps without folder, the first entry of their section. The entry only appears while the section has some, and its ⋯ menu creates a new shared step outside any folder.
Delete removes only the folder: its shared steps and subfolders move up to the folder that contained it, and nothing else is deleted. If a subfolder would land next to a folder with the same name, the delete is refused — rename one of them first.
To rename a shared step or move it to another folder, open the ⋯ menu at the top of its page and choose Edit shared step.

Using a shared step in a test case

In the case editor — the full editor page, or the Steps section of the case panel after Edit — click Insert shared step:

The list of shared steps shows beside the preview. Type in the search to narrow it by title, and narrow it to This project or Organization and one of its folders. Organization-wide shared steps carry the building icon; hover it to read the scope.
Pick a shared step from the list, with the mouse or with the arrow keys and Enter from the search: the preview beside it shows its steps.
Under Insert at, keep At the end, choose At the beginning, or the step it should follow, then click Insert.
Save the case.

The shared step’s steps then appear among the case’s own steps, numbered like them: a shared step with 3 steps inserted after step 01 takes steps 02, 03 and 04, and the next step of the case is 05. They are read-only in the case — in the editor their text sits in greyed-out boxes you cannot type in. Only the case editor marks them: each one shows a Shared step label on the right, and hovering the label shows the shared step’s title. The case view and runs show them as ordinary numbered steps. In the editor, open the ⋯ menu on a shared step’s row, where ordinary steps have their image and delete buttons: it offers Open shared step, Convert to regular and Remove. A case can mix ordinary steps and shared steps, use several shared steps, and use the same one more than once. A case still holds at most 500 rows, and a shared step counts as one row toward that limit however many steps it holds.

A case can use a shared step of its own project or an organization-wide one — never another project’s. The picker lists only the shared steps of the case’s format, and the API refuses a shared step of the other format with 422. On a plan without organization-wide shared steps the picker still lists them, but they cannot be inserted; See plans shows the plans that include them.

Three actions change how a case uses shared steps. Convert to regular and Remove are in the ⋯ menu of each step of a shared step:

Remove — removes that single step: once you save, the case no longer has it, and the shared step’s other steps stay shared and keep updating. The shared step itself is untouched.
Convert to regular — converts the whole shared step, from any of its steps: after you confirm, all its steps become regular, editable copies of their current text and images, in place, in this case only. Later edits to the shared step no longer reach this case.
Create shared step from selection — tick the boxes of ordinary steps that follow one another, click Create shared step from selection, and give the new project shared step a Title and, optionally, a Folder. The steps become the new shared step’s steps in the same place, with their text and the images in that text. Steps with a gap between them cannot be converted. The new set takes the case’s step format.

Convert to regular and Create shared step from selection change the saved case right away, so they work only on a case that already exists and has no unsaved changes: save or discard your edits first. A case being created offers neither.

A placeholder inside a shared step, such as ${name}, is read from the case that uses the step. One shared step can therefore serve every combination of a parameterized case. See Parameterized test cases.

Editing a shared step, and what runs see

Editing a shared step changes it everywhere it is used. There is no per-case copy to update: every case reads the shared step’s current steps. Each edit, including removing an image, saves a new version of every case whose steps it changes, and anyone editing one of those cases at that moment is asked to reload before saving. The title, steps, and images of a shared step used by more than 5,000 cases cannot be changed; convert it to regular steps or remove it in some of them first.

Runs are different. When a case is added to a run, its steps are snapshotted, and a shared step is snapshotted as its steps at that moment. In the execution panel they appear as ordinary steps, each with its own number and no label; you mark each one like any other step. Editing or deleting the shared step later never changes a run that already holds it.

Organization-wide shared steps

An organization-wide shared step can be used by cases of every project. Because one edit reaches all of them, only owners and admins can create, edit, move, or delete them, and their folders. Members can still insert them into cases.

Organization-wide shared steps are part of the Pro and Enterprise plans, and of the trial. On the Free plan the Organization section shows the upgrade option instead of its create actions.

To share a project shared step with the whole organization, an owner or admin opens it and chooses Make organization-wide from the ⋯ menu at the top of its page. It moves to the organization’s root folder and keeps its ID, steps, and every case that uses it. This cannot be undone.

If your organization moves to Free

Nothing is deleted, and nothing stops working for the cases that already use them:

Cases keep showing their organization-wide shared steps, and new runs keep snapshotting them.
Saving a case that already uses one keeps it, and Convert to regular still works.
Owners and admins can still delete organization-wide shared steps and their folders, so you can clean up.

What stops until you are back on a paid plan: creating, editing, or making shared steps organization-wide, creating, renaming, or moving organization folders, and adding an organization-wide shared step to a case that does not use it yet.

Deleting a shared step

Open the shared step, then open the ⋯ menu at the top of its page and choose Delete. The dialog says how many cases use it and asks what should happen to them:

Keep the steps in the cases (the default) — each case gets its own ordinary copy of the steps, in the same place, with the images in their text. Later edits no longer reach them.
Remove the steps from the cases — the steps disappear from every case that uses it, and the remaining steps close the gap.

All the cases change together, or none do. The delete is refused, and nothing changes, when:

keeping the steps would take a case past 500 steps — the dialog lists those cases;
the shared step is used by more than 5,000 cases (either choice) — convert it to regular steps or remove it in some of them first;

Deleting never changes a run.

Usage and history

A shared step’s page has three tabs:

Steps — its steps, editable by whoever may edit it.
Used in — every test case that uses it, with its project and suite. You only see cases of projects you can open.
History — who created, edited, moved, deleted, or made it organization-wide, and the step-by-step changes of every edit. Each case changed by deleting a shared step, converting one to regular steps, or creating one from a selection also records the change in its own activity.

Duplicating, exporting and importing

Duplicating a case or a suite keeps its shared steps when the copy lands where they can be used: in the same project, or anywhere for organization-wide ones. A project shared step duplicated into another project becomes ordinary steps, with its images — see Duplicating cases and suites.
Exporting writes shared steps out as ordinary steps, in every format.
Importing never creates shared steps. A shared step that the source file carries with its content arrives as ordinary steps in place; one that the file only references by ID is skipped and reported as a warning on that case — see Import test cases.

Shared parameters are a separate library with their own scope. Organization-wide shared parameters need the same permission and the same plan entitlement as organization-wide shared steps. See Parameterized test cases.

Permissions

Action	Who
See shared steps	Anyone who can open the project
Create, edit, move, delete project shared steps and folders	Members and above
Insert, remove, convert to regular, create from selection in a case	Members and above
Create, edit, move organization-wide shared steps and folders	Owners and admins, on a paid plan
Make a shared step organization-wide	Owners and admins, on a paid plan
Delete organization-wide shared steps and folders	Owners and admins, on any plan

API and MCP

Everything on this page is available to integrations. The API reference documents the Shared steps operations, and AI agents use the shared steps tools listed in the MCP tool reference.