> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testdriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gherkin

> Convert Gherkin scenarios to TestDriver prompts

This guide explains how to convert **Gherkin scenarios** into **TestDriver prompts** for use in your testing workflows. By following this process, you can easily adapt existing Gherkin test cases into a format compatible with TestDriver.

***

## What's Gherkin?

Gherkin is a plain-text language used to describe test scenarios in a human-readable format. It uses keywords like `Given`, `When`, `Then`, and `And` to define steps in a test.

### Example Gherkin scenario:

```gherkin theme={null}
Scenario: Successful login
  Given the user is on the login page
  When the user enters valid credentials
  And clicks the "Log In" button
  Then the user should see the dashboard
```

***

## What are TestDriver prompts?

TestDriver prompts are high-level instructions that describe what the AI should do. They're written in plain text and focus on user actions or expected outcomes.

### Example prompts:

```yaml theme={null}
- prompt: the user is on the login page
- prompt: the user enters valid credentials
- prompt: clicks the "Log In" button
- prompt: the user should see the dashboard
```

***

## Steps to convert Gherkin to TestDriver prompts

### Step 1: Understand the mapping

| **Gherkin Keyword** | **TestDriver Prompt**                      |
| ------------------- | ------------------------------------------ |
| `Given`             | Describes the initial state or setup.      |
| `When`              | Describes the user action.                 |
| `Then`              | Describes the expected outcome or result.  |
| `And`               | Adds additional steps to the same context. |

***

### Step 2: Extract steps from Gherkin

Take each step from the Gherkin scenario and rewrite it as a plain-text prompt. Remove the `Given`, `When`, `Then`, and `And` keywords, and focus on the action or expectation.

#### Example:

| **Gherkin Step**                         | **TestDriver Prompt**               |
| ---------------------------------------- | ----------------------------------- |
| `Given the user is on the login page`    | `the user is on the login page`     |
| `When the user enters valid credentials` | `the user enters valid credentials` |
| `And clicks the "Log In" button`         | `clicks the "Log In" button`        |
| `Then the user should see the dashboard` | `the user should see the dashboard` |

***

### Step 3: Write the prompts in YAML format

Combine the extracted prompts into a YAML file. Each step should be written as a `prompt` entry.

#### Example YAML:

```yaml theme={null}
- prompt: the user is on the login page
- prompt: the user enters valid credentials
- prompt: clicks the "Log In" button
- prompt: the user should see the dashboard
```

***

### Step 4: Save the YAML file

1. Save the YAML content to a file (for example, `login_test.yaml`).
2. Ensure the file is stored in the appropriate directory for your TestDriver project (for example, `testdriver/`).

***

### Step 5: Run the test with TestDriver

Use the TestDriver CLI to execute the test.

#### Command:

```bash theme={null}
npx testdriverai@latest run login_test.yaml
```

***

## Example: Full conversion workflow

### Input Gherkin scenario:

```gherkin theme={null}
Scenario: Add a product to the cart
  Given the user is on the product page
  When the user clicks "Add to Cart"
  And confirms the action
  Then the product should appear in the cart
```

### Converted YAML:

```yaml theme={null}
- prompt: the user is on the product page
- prompt: the user clicks "Add to Cart"
- prompt: confirms the action
- prompt: the product should appear in the cart
```

### Run the test:

```bash theme={null}
npx testdriverai@latest run add_to_cart_test.yaml
```

***

## Best practices

1. **Keep Prompts Simple**: Focus on high-level actions or outcomes. Avoid including unnecessary details.
2. **Use Descriptive Prompts**: Ensure each prompt clearly describes the action or expectation.
3. **Test the YAML**: Run the converted YAML file to verify that it works as expected.
4. **Organize Files**: Store YAML files in a structured directory (for example, `testdriver/`) for easy management.

***

By following this guide, you can efficiently convert Gherkin scenarios into TestDriver prompts, enabling seamless integration of existing test cases into your TestDriver workflows.