Parameter Best Practices

2 min read

Parameters are most valuable when teams treat them as shared test assets. A small amount of discipline around naming, scope, and cleanup keeps test content readable and easy to maintain.

Choose the Right Scope

Use workspace parameters for values that should be available across projects, such as shared environment names, organization-wide URLs, or common test data.

Use project parameters for values that belong to one project, such as feature-specific accounts, local URLs, or temporary project data.

When a value is useful in only one project, keep it local. When several projects need the same value, move it to the workspace level.

Use Clear Names

Parameter names should explain what the value means.

Good examples:

application_login_url
checkout_test_user
default_timeout_seconds
customer_admin_email

Avoid vague names such as url, value1, or test_param. Vague names make parameter pickers harder to use and increase the chance of choosing the wrong value.

Add Helpful Descriptions

Descriptions help teammates understand why a parameter exists and when to use it.

A useful description can mention:

The workflow or area that uses the value
The environment the value belongs to
Any limits or naming rules
Whether the parameter replaces an older value

Keep Values Easy to Review

Regular parameters are visible in the Parameters table and parameter pickers. Do not use regular parameters for sensitive secrets.

Use values that are safe for team members with parameter access to view. If a value should not be broadly visible, handle it outside regular parameters.

Update Widely Used Parameters Carefully

Changing a parameter value affects the places where it is used. Before updating a widely used parameter:

Review the usage list.
Check whether the value is shared across projects.
Communicate the change if other teams may be affected.
Consider creating a new parameter first when the change is risky.

Prefer Replacement Over Removal

When deleting a used parameter, replacement is usually safer than removal.

Replace with another parameter when consolidating or renaming.
Replace with value when the content should keep the current text.
Remove from usages only when the reference should disappear completely.

Learn more in Delete Parameters.

Review Unused Parameters

Unused parameters can make pickers noisy. Periodically review parameters with No usages, then delete or repurpose values that are no longer needed.

For active parameters, keep descriptions current so future users understand why the value exists.

Keep Parameterized Content Readable

Use parameters where they make content easier to maintain, not harder to read.

Good:

Open $application_login_url and sign in with $checkout_test_user.

Avoid:

Open $url and use $user.

The best parameterized steps are still understandable to a person reviewing the test.