> For the complete documentation index, see [llms.txt](https://docs.testfirst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.testfirst.com/testfirst-editor/writing-test-cases/write-test-cases-using-gherkin.md).

# Write Test Cases using Gherkin

{% hint style="info" %}
 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.
{% endhint %}

### 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** <i class="fa-arrow-right">:arrow-right:</i> Precondition (e.g., browser, environment)
* **When** <i class="fa-arrow-right">:arrow-right:</i> 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:

```
CTRL + SPACE
```

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&#x20;

Describe elements in natural language:

```
When I click "'Login' button"
```

* No need for technical selectors
* Works well with dynamic UIs
* Adapts to layout changes

You can also add context:

```
When I click "'Sign up' button near to Login"
```

#### 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:

```
When I click "!Login"
```

* Fast and simple
* Works best when elements are unique
* Does not use cloud credits

***

### Custom Selectors

Use selectors stored in the Data Repository:

```
When I click "{Login Button}"
```

* Fully controlled (XPath / CSS)
* Reusable across tests
* Best for complex or unstable elements

#### Using Variables

Variables allow you to reuse data across tests.

```
When I type "{{username}}" in "Username"
```

* 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 `\"`:

```
When I click "Text with \"quotes\""
```

* Use variables inside selectors:

```
When I click "Button with {{label}}"
```

### 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