Feature Request: Support for 'Or' Step Following a 'Then' Step in Gherkin for Alternative Outcome Assertion

[abhinandraj07]

💡 Feature Idea: Support for Or Step Following a Then Step in Gherkin

Problem Statement

In real-world systems, a single action may lead to one of several valid outcomes. Currently, Gherkin syntax does not support expressing alternative expected outcomes within a single scenario. This forces test authors to duplicate scenarios with identical Given and When steps, which:

• Reduces readability and maintainability.
• Bloats the test suite with redundant logic.
• Makes reporting less intuitive for stakeholders.

Proposed Solution

Introduce support for an Or step that can follow a Then step to express alternative expected outcomes.

Example Syntax

Scenario: Payment confirmation message validation

  Given the user has completed a purchase
  When the user pays using a supported payment gateway
  Then the user should see "Payment successful"
  Or the user should see "Transaction completed"
  Or the user should see "Your payment has been processed"

The Or step is valid only after a Then step
It represents an alternative expected outcome

Execution Logic

Step Evaluation

Group the initial Then step and subsequent Or steps as a logical block.
Evaluate steps in order:

• If any step passes, the scenario is marked as Passed.
• If a step is not matched, it is marked as Unmet.
• If a step is skipped due to a previous match, it is marked as Bypassed.
• If none of the steps match, the scenario is marked as Failed.

Short-Circuit Behavior

• Once a step in the Then/Or block passes, remaining Or steps are Bypassed.
• If the first Then step passes, all Or steps are Bypassed.
• If a later Or step passes, earlier unmatched steps are marked as Unmet, and remaining steps are Bypassed.

Reporting Terminology

  ✅ Passed | The step matched and executed successfully.
  ⚠️ Unmet | The step did not match, but the scenario continued due to Or logic.
  ⏭ Bypassed | The step was skipped because a previous Or step passed.

Example Report

Case 1: First step passes

  ✅ Then the user should see "Payment successful" (Passed)
  ⏭ Or the user should see "Transaction completed" (Bypassed)
  ⏭ Or the user should see "Your payment has been processed" (Bypassed)

  ✅Scenario PASSED: One of the valid outcome matched

Case 2: Second step passes

  ⚠️ Then the user should see "Payment successful" (Unmet)
  ✅ Or the user should see "Transaction completed" (Passed)
  ⏭ Or the user should see "Your payment has been processed" (Bypassed)

  ✅Scenario PASSED: One of the valid outcome matched

Case 3: No step matches

  ⚠️ Then the user should see "Payment successful" (Unmet)
  ⚠️ Or the user should see "Transaction completed" (Unmet)
  ⚠️ Or the user should see "Your payment has been processed" (Unmet)

  ❌ Scenario FAILED: No valid outcome matched

Benefits

• Reduces duplication of scenarios.
• Improves readability and maintainability.
• Aligns better with real-world systems that have multiple valid outcomes.
• Enhances reporting clarity with intuitive status labels.

Backward Compatibility

• The feature is opt-in and only affects scenarios using the Or step after a Then.
• Existing scenarios and tooling remain unaffected.

🤝 Contribution

Happy to collaborate on prototyping or implementations.

Open to feedback and suggestions from the community!

[luke-hill]

The problem here is the procedurality (?), of the gherkin. What you are saying here is you want to do something conditional.

If it's a conditional setup, then you should absorb this into your setup. One "ruby" example is for instance #find_or_create i.e. I want a user/profile/entity. I don't care if I make one or one exists.

If it's conditional execution, i.e. actions. Then you should alter your behaviour accordingly. And should probably test these different permutations. A scenario outline is likely your best call here

Given some setup
When I <action>
Then I see a toast notification

Examples:
| action        |
| send an email |
| send an invite |
| request a password reset |

If it's conditional assertions, then you should absorb that into your library. RSpec (Ruby), has a nice syntax for this.

expect(page.text).to include('hello').or include('goodbye')

Hope this gives some insight.

[abhinandraj07]

Thanks for the thoughtful feedback — I really appreciate the perspective!

Just to clarify: this proposal is not about conditional execution or setup logic, and it’s not driven by variations in the When step.

It’s focused strictly on the Then step, where a single action may lead to multiple valid outcomes, and we want to express those outcomes declaratively in the feature file.

The key distinction here is that only one of the outcomes is expected to happen at runtime, not all. So using a Scenario Outline with an Examples table doesn’t fit well — because that implies testing all permutations, which isn’t the case here.

For example:

Scenario: User receives confirmation after payment
     Given the user has completed a purchase
     When the user pays using a supported payment gateway
     Then the user should see "Payment successful"
     Or the user should see "Transaction completed"
     Or the user should see "Your payment has been processed"

All Given and When steps are identical — only the Then varies.
At runtime, only one of these messages will appear, and any of them is considered a valid success.
If we try to handle this entirely in the step implementation (e.g., using a regex or compound matcher), it becomes:

• Opaque to stakeholders reading the feature file
• Hard to maintain, especially when the list of valid outcomes grows
• Difficult to report clearly, since the feature file doesn’t reflect all acceptable results

Also, combining all possible outcomes into a single step would make the step definition too long and unreadable, and it would hide the business logic from the feature file — which defeats the purpose of BDD.
The Or step allows us to:

• Keep the scenario clean and readable
• Avoid duplicating logic across multiple scenarios
• Make reporting intuitive, by showing which outcome matched and which were bypassed

I do understand that this feature can be misused if not applied thoughtfully — for example, by overusing Or steps to avoid proper scenario design. But if handled responsibly and with clear guidelines, it can be a powerful tool to improve readability, reduce duplication, and enhance reporting clarity.

I’m happy to refine the idea further based on community feedback — thanks again for engaging in the discussion!

[luke-hill]

As I mentioned, I covered all three use cases.

If it's conditional assertions, then you should absorb that into your library. RSpec (Ruby), has a nice syntax for this.

So you would write something like this

     Then the user should see "Payment successful"
     Or the user should see "Transaction completed"
     Or the user should see "Your payment has been processed"

Becomes

    Then the user is informed that their payment was completed

And your assertion library needs to lean on this in their conditionals.

[abhinandraj07]

You're absolutely right that abstracting assertions into the step implementation can work well, and it's a common practice in many frameworks. But the core motivation behind this proposal is to make alternative valid outcomes visible and explicit in the feature file itself — not just in the code.

Yes, we could write:

Then the user is informed that their payment was completed

and handle all message variations inside the step definition. Or even use a data table to add more context.. But that approach:

• Hides the business logic from stakeholders (even with a data table, it's somewhat ambiguous)
• Makes reporting less transparent
• Requires digging into implementation to understand what’s actually being validated

With Or steps, we keep expectations declarative, readable, and reportable — similar to how And expresses multiple required outcomes. Or would simply express multiple acceptable ones, directly in the scenario.

[vitalets]

@abhinandraj07 Maybe a single step with data table can suite for this case?

  Scenario: User receives confirmation after payment
    Given the user has completed a purchase
    When the user pays using a supported payment gateway
    Then the user should see one of the success messages:
      | Payment successful              |
      | Transaction completed           |
      | Your payment has been processed |

[abhinandraj07]

Thanks for the suggestion — a data table is a clean alternative, but it doesn't fully solve the problem.

The key issue is: only one of the outcomes is expected at runtime, not all. A data table hides this logic inside the step definition, making it less transparent to stakeholders and harder to report clearly.

With Or steps:

• Each outcome is visible in the feature file.
• Reporting can show which outcome matched, which were skipped.
• It avoids duplicating scenarios and keeps logic declarative.

We already have And steps to express multiple related actions or assertions, so introducing Or wouldn't break the model.
The goal isn't to add conditional logic, but to allow a clean way to express alternative valid outcomes in the Then step — just like And expresses multiple required outcomes.