For the complete documentation index, see llms.txt. This page is also available as Markdown.

Write Test Cases using Gherkin

Gherkin is a human-readable language used to define how your application should behave.

It allows you to write automated tests as structured scenarios that are easy to read, write, and maintain.

Basic Structure

Every test is written as a Scenario:

Scenario: Navigate to TestFirst website
  Given browser "Chrome"
  When I visit "https://www.testfirst.com/"
  And I click "START NOW"
  Then "Pricing Plans" page is displayed
  And "Flexible pricing for any team" is displayed

Gherkin Keywords

Keyword
Purpose

Scenario

Defines the test case

Given

Sets the starting condition

When

Describes actions

Then

Defines expected results

And

Adds additional steps


How Gherkin Works

Each scenario represents a complete test:

  • Given Precondition (e.g., browser, environment)

  • When Actions performed

  • Then → Expected outcome

You can use And to extend any part of the scenario.

Auto-Complete Support

The editor provides intelligent suggestions while typing:

  • Suggests valid Gherkin steps

  • Adapts based on your test context

  • Helps reduce syntax errors

Use:

to trigger suggestions manually.


Selecting Elements in Tests

When interacting with UI elements, TestFirst supports 3 selector types.

1. AI Selectors

2. Quick Selectors

3. Custom Selectors

AI Selectors

Describe elements in natural language:

  • No need for technical selectors

  • Works well with dynamic UIs

  • Adapts to layout changes

You can also add context:

Tips for Better AI Selectors

  • Be specific about element type

    • 'Username' input field

    • 'Submit' button

  • Use relationships when needed

    • 'Amount' input field near to 'Bonus'

  • Add context when elements repeat

    • 'Bonus' item in dropdown near to 'Allowance'


Quick Selectors

Use ! for simple matching:

  • Fast and simple

  • Works best when elements are unique

  • Does not use cloud credits


Custom Selectors

Use selectors stored in the Data Repository:

  • Fully controlled (XPath / CSS)

  • Reusable across tests

  • Best for complex or unstable elements

Using Variables

Variables allow you to reuse data across tests.

  • Stored in the Data Repository

  • Useful for credentials, URLs, and test data

Additional Notes

  • The editor supports a wide range of Gherkin steps

  • Auto-complete reflects the latest supported syntax

  • Actual editor behaviour should be treated as the source of truth


Special Cases

  • Escape double quotes using \":

  • Use variables inside selectors:

Best Practices

  • Use clear and descriptive scenario names

  • Keep steps simple and readable

  • Prefer AI Selectors for speed and flexibility

  • Use variables instead of hardcoding values

  • Split large flows into smaller scenarios

Last updated