Shared Steps Best Practices

2 min read

Shared steps are most useful when they reduce repeated work without making test cases harder to understand. Treat them as shared testing assets that need clear names, careful updates, and regular review.

Use Shared Steps for Stable Reusable Flows

Good shared step candidates include:

Login flows
Common navigation flows
Setup or cleanup steps
Repeated validation patterns
Standard checks used across many test cases

Avoid shared steps for one-off logic, rapidly changing flows, or steps that are tightly tied to a single test case.

Choose the Right Scope

Use workspace shared steps for flows that should be available across projects. Use project shared steps for flows that belong to one project.

When a flow is useful in only one project, keep it local. When multiple projects need the same flow, consider moving it to the workspace level.

Keep Shared Steps Small

A shared step should represent a focused reusable action or short flow.

Better:

User logs in with valid credentials
User adds item to cart
User confirms order

Too broad:

User completes full checkout flow

Smaller shared steps are easier to reuse, review, and safely update.

Name and Describe Clearly

Use names that describe the user action or test activity. Add descriptions that explain when the shared step should be used and what assumptions it makes.

Clear names and descriptions help teams choose the right shared step from the picker.

Use Parameters for Flexible Values

Parameters work well inside shared steps when a repeated value may change, such as a URL, test account, or environment name.

For example, a shared step can say:

Open $application_login_url.

This keeps the shared step reusable while allowing the value to be managed from the Parameters page.

Review Usage Before Editing

Editing a shared step can affect every test case that uses it. Before changing a shared step:

Review linked test cases.
Check whether the change is safe for all usages.
Create a new shared step if the new behavior is not compatible with old usage.

Workspace shared steps deserve extra care because they can be used across projects.

Prefer Convert Over Removal When Unsure

When deleting a used shared step, Convert to regular step keeps the step content inside linked test cases and removes the shared link.

Use Remove from usages only when the step should disappear from linked test cases.

Review Shared Steps Regularly

Over time, shared step libraries can become noisy. Periodically review:

Unused shared steps
Similar or duplicate shared steps
Outdated descriptions
Overly broad shared steps

Small cleanup habits keep the picker useful and reduce mistakes.