03.02.02 — Step Instructions: How to Write Them Once, Not Rewrite Them

Lesson goal

This lesson explains how to write durable step instructions that remain valid despite UI, layout, and configuration changes in Salesforce.

After this lesson, you should be able to:

• avoid UI-coupled instructions that quickly become obsolete,
• write functional, behavior-focused steps,
• separate execution mechanics from verification logic.

Why step instructions break so often in Salesforce

Salesforce environments evolve continuously:

• page layouts change,
• Lightning components move,
• flows replace validation rules,
• navigation paths are restructured.

Step instructions that describe how to click rather than what to do become outdated quickly.

This leads to:

• frequent rewrites,
• execution confusion,
• testers deviating from documentation.

Durable instructions focus on intent and outcome, not UI paths.

Functional instructions vs navigation instructions

A functional instruction describes the action from the system’s perspective.

A navigation instruction describes how to reach a UI element.

Example

Navigation-based (fragile):

Click the “New Opportunity” button on the Opportunities related list

Functional (durable):

Create a new Opportunity for an existing Account

The second instruction remains valid even if:

• the button moves,
• the UI changes,
• the action is triggered from a different screen.

Avoiding UI-specific labels and names

UI labels are configuration artifacts.

They:

• vary by language,
• change between orgs,
• are frequently renamed during implementation.

Step instructions should avoid:

• exact button names,
• menu paths,
• tab labels,
• Lightning component names.

When a UI reference is unavoidable:

• describe it functionally,
• avoid quoting exact labels,
• use it as a hint, not a requirement.

One action per step

Each step instruction should describe one action.

Combining multiple actions into a single step:

• hides execution complexity,
• complicates expected results,
• makes defect diagnosis harder.

Example

Poor:

Create an Opportunity and set Stage to Closed Won

Better:

1. Create a new Opportunity for the Account
2. Change Opportunity Stage to Closed Won

This separation clarifies:

• execution flow,
• expected behavior,
• failure points.

Separating instruction from verification

A step instruction should never include verification logic.

Instruction:

What the tester does

Expected Result:

What the system should do

Mixing the two:

• obscures intent,
• creates ambiguous outcomes,
• complicates execution.

This separation is especially important in Salesforce, where:

• automation may trigger side effects,
• errors may appear asynchronously,
• multiple outcomes are possible.

Writing instructions that survive automation changes

Automation is a major source of instruction instability.

Flows, validation rules, and triggers may:

• block actions,
• alter data,
• redirect execution paths.

Durable instructions:

• describe the intended action,
• do not assume automation outcomes,
• leave verification to Expected Results.

Example:

• Instruction: Save the i
• Verification: System prevents save and displays validation message

This keeps responsibilities clear.

Handling conditional behavior

Some actions behave differently depending on context:

• user permissions,
• record state,
• related data.

Step instructions should:

• describe the intended action,
• rely on Preconditions to control context,
• avoid conditional wording inside the step.

Avoid:

If validation appears, then…

Conditions belong in analysis and Preconditions, not in step instructions.

Common instruction anti-patterns

Frequent mistakes include:

• embedding assumptions about data state,
• referencing specific UI paths,
• using vague language (“try to”, “check if possible”),
• combining multiple actions and checks.

Each of these reduces clarity and increases maintenance cost.

Practical guideline

Good step instructions:

• are short,
• are functional,
• describe one action,
• avoid UI-specific language,
• rely on Preconditions for context.

If a step needs explanation to be executed, it is not written clearly enough.

Key takeaway

• Step instructions define what the tester does.
• Expected Results define what the system does.
• Durable instructions focus on behavior, not UI mechanics.

Writing steps this way allows Salesforce test cases to remain valid as the system evolves.