Skip to main content

Gherkin Best Practices for WepNG

To ensure our "Living Documentation" remains readable and maintainable, we follow these guidelines.

1. Declarative vs Imperative​

Goal: Describe Business Behavior, not UI mechanics.

  • ❌ Bad (Imperative - UI Focused):

    Given I am on the Fee Create Page
    When I type "FEE_2024" in the "Code" textbox
    And I click the "Save" button
    Then I should see a red error box saying "Duplicate"

    Why bad? If we rename the button or change the UI layout, the test breaks, even if the logic is correct.

  • ✅ Good (Declarative - Logic Focused):

    Given a Fee exists with Code "FEE_2024"
    When I attempt to create a new Fee with Code "FEE_2024"
    Then the creation should be rejected due to "Duplicate Code"

    Why good? It describes the rule. The automation layer handles how (API call, Controller action, or UI interaction).

2. Use Background for Context​

Don't repeat setup steps that are common to all scenarios in a feature.

Background:
  Given the System has Master Cultures initialized  # Common prerequisite
  And the User is an Administrator                  # Common authorization

3. Data Tables for Complex Objects​

Avoid "And I set X... And I set Y... And I set Z...". Use tables.

  • ✅ Good: 
    When I create a Fee with:
      | Property | Value    |
      | Code     | FEE_A    |
      | Title    | Fee A    |
      | Amount   | 100.00   |

4. Scenario Titles​

Scenario titles should be readable summaries of the rule being tested.

  • ❌ Bad: Scenario 1
  • ❌ Bad: Test Valid Fee
  • ✅ Good: Prevent creation of Fee with duplicate Code
  • ✅ Good: Allow update of Title without changing Code

5. The "Mapping" Companion​

Since we prioritize Documentation, every .feature file MUST have a companion .mapping.md file.

  • Template: Use the Gherkin Mapping Template.
  • Purpose: Explains to developers how to automate this feature.
  • Content: "Mock DbContext", "Call FeeController.Edit", etc.