From 24b43643ed6e18334e63e8d32826aabc98a0d472 Mon Sep 17 00:00:00 2001
From: Eamonn Mansour <47121388+eamansour@users.noreply.github.com>
Date: Tue, 12 May 2026 11:39:56 +0100
Subject: [PATCH 1/2] docs: Move gherkin-related docs into their own topic

Signed-off-by: Eamonn Mansour <47121388+eamansour@users.noreply.github.com>
---
 .secrets.baseline                             |  10 +
 .../runs-submit-local.md                      |  32 --
 .../setting-up-galasa-project.md              |   2 +-
 .../using-gherkin/gherkin-step-definitions.md | 299 ++++++++++++++++++
 .../using-gherkin/gherkin-syntax-reference.md | 253 +++++++++++++++
 docs/content/docs/using-gherkin/index.md      |  21 ++
 .../using-gherkin/running-gherkin-tests.md    | 133 ++++++++
 .../using-gherkin/writing-gherkin-tests.md    | 188 +++++++++++
 docs/mkdocs.yml                               |   6 +
 9 files changed, 911 insertions(+), 33 deletions(-)
 create mode 100644 docs/content/docs/using-gherkin/gherkin-step-definitions.md
 create mode 100644 docs/content/docs/using-gherkin/gherkin-syntax-reference.md
 create mode 100644 docs/content/docs/using-gherkin/index.md
 create mode 100644 docs/content/docs/using-gherkin/running-gherkin-tests.md
 create mode 100644 docs/content/docs/using-gherkin/writing-gherkin-tests.md

diff --git a/.secrets.baseline b/.secrets.baseline
index 13f5ecd2e..5a8a9f770 100644
--- a/.secrets.baseline
+++ b/.secrets.baseline
@@ -390,6 +390,16 @@
         "verified_result": null
       }
     ],
+    "docs/content/docs/using-gherkin/gherkin-step-definitions.md": [
+      {
+        "hashed_secret": "c61db10457a740b07845146f2d1b391c133a6ebf",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 142,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
     "docs/content/docs/writing-own-tests/binding-tests.md": [
       {
         "hashed_secret": "877704f69026efee10f08e8f95568749f2682203",
diff --git a/docs/content/docs/cli-command-reference/runs-submit-local.md b/docs/content/docs/cli-command-reference/runs-submit-local.md
index 7aa3e57e1..76df04b2e 100644
--- a/docs/content/docs/cli-command-reference/runs-submit-local.md
+++ b/docs/content/docs/cli-command-reference/runs-submit-local.md
@@ -71,38 +71,6 @@ Use this command to run a Java test in a local JVM:
 
     Galasa uses OBRs to locate tests and all required Managers in the specified Maven repository.
 
-## Running a Gherkin test with the `runs submit local` command
-
-Use this command to run a Gherkin test in a local JVM. Note that the `--gherkin` flag is used instead of `--obr` or `--class` flags.
-
-=== "Linux or macOS"
-
-    ```shell
-    galasactl runs submit local --log - \
-    --gherkin file:///path/to/gherkin/file.feature
-    ```
-
-
-=== "Windows (Powershell)"
-
-    ```powershell
-    galasactl runs submit local --log - `   
-    --gherkin file:///path/to/gherkin/file.feature
-    ```
-
-**Parameters explained:**
-
-- `--log -`: Sends debugging information to the console (stderr).
-
-- `--gherkin`: Specifies the path to the Gherkin file containing your tests. The path must be in URL format and end with a `.feature` extension. 
-  
-    Examples:
-
-    - Linux/macOS: `file:///Users/myuserid/gherkin/MyGherkinFile.feature`
-    - Windows: `file:///C:/Users/myuserid/gherkin/MyGherkinFile.feature`
-
-For more information about Gherkin support, see the [Galasa CLI Gherkin documentation](https://github.com/galasa-dev/galasa/blob/main/modules/cli/gherkin-docs.md){target="_blank"}.
-
 
 ## Stopping a running test
 
diff --git a/docs/content/docs/cli-command-reference/setting-up-galasa-project.md b/docs/content/docs/cli-command-reference/setting-up-galasa-project.md
index 0ce5c9070..2155e5c31 100644
--- a/docs/content/docs/cli-command-reference/setting-up-galasa-project.md
+++ b/docs/content/docs/cli-command-reference/setting-up-galasa-project.md
@@ -12,7 +12,7 @@ This guide explains:
 - How to create and build an example project
 - The purpose of the generated files
 
-Once you have created and built your project, you can run tests locally. Both Java and Gherkin tests are supported. Learn more in [Running a test locally](./runs-submit-local.md).
+Once you have created and built your project, you can run tests locally. Learn more in [Running a test locally](./runs-submit-local.md).
 
 
 ## Getting started
diff --git a/docs/content/docs/using-gherkin/gherkin-step-definitions.md b/docs/content/docs/using-gherkin/gherkin-step-definitions.md
new file mode 100644
index 000000000..ceaaa9870
--- /dev/null
+++ b/docs/content/docs/using-gherkin/gherkin-step-definitions.md
@@ -0,0 +1,299 @@
+---
+title: "Available step definitions"
+---
+
+This reference lists all pre-implemented step definitions available in Galasa for writing Gherkin tests.
+
+## General steps
+
+### Writing to the test log
+
+Write messages to the test log for debugging or documentation purposes:
+
+```gherkin
+THEN Write to log "Your message here"
+```
+
+**Example:**
+```gherkin
+THEN Write to log "Starting test execution"
+```
+
+## 3270 Terminal steps
+
+These steps allow you to interact with 3270 terminal applications.
+
+### Allocating terminals
+
+Allocate a terminal for your scenario to use:
+
+```gherkin
+GIVEN a terminal
+GIVEN a terminal with id of xxx
+GIVEN a terminal tagged yyy
+GIVEN a terminal with id of xxx tagged yyy
+```
+
+**Parameters:**
+
+- **id**: A name to identify the terminal when using multiple terminals in one scenario. Default is `A`.
+- **tag**: Specifies which system to connect to. Default is `PRIMARY`.
+
+**Examples:**
+```gherkin
+GIVEN a terminal
+GIVEN a terminal with id of B
+GIVEN a terminal tagged SECONDARY
+GIVEN a terminal with id of C tagged BACKUP
+```
+
+### Specifying terminal size
+
+You can specify the terminal dimensions in your scenario:
+
+```gherkin
+GIVEN a terminal with 48 rows and 160 columns
+GIVEN a terminal B with 24 rows and 160 columns
+GIVEN a terminal C tagged ABCD with 24 rows and 80 columns
+```
+
+**Default size:** 24 rows × 80 columns
+
+**Configuration:** You can also set terminal size using CPS properties:
+
+- `zos3270.gherkin.terminal.rows` (default: 24)
+- `zos3270.gherkin.terminal.columns` (default: 80)
+
+Priority order: Scenario specification > Override properties > CPS properties > Default values
+
+### Pressing special keys
+
+Send Program Function (PF) keys to the terminal:
+
+```gherkin
+AND press terminal key PF1
+AND press terminal key PF2
+...
+AND press terminal key PF24
+```
+
+**For named terminals:**
+```gherkin
+AND press terminal A key PF1
+```
+
+### Pressing special character keys
+
+Send special character keys to the terminal:
+
+```gherkin
+AND press terminal key TAB
+AND press terminal key BACKTAB
+AND press terminal key ENTER
+AND press terminal key CLEAR
+```
+
+**For named terminals:**
+```gherkin
+AND press terminal A key ENTER
+```
+
+### Typing text
+
+Send text to the terminal:
+
+```gherkin
+AND type "xxx" on terminal
+AND type "xxx" on terminal in field labelled "yyy"
+AND type "xxx" on terminal A in field labelled "yyy"
+```
+
+**Parameters:**
+
+- **xxx**: The text to type
+- **yyy**: The label of the field to type into
+- **A**: The terminal ID (if using multiple terminals)
+
+**Examples:**
+```gherkin
+AND type "LOGON" on terminal
+AND type "myusername" on terminal in field labelled "User ID"
+AND type "CICS" on terminal B in field labelled "Application"
+```
+
+### Using credentials
+
+Type credentials from the credentials store:
+
+```gherkin
+AND type credentials MYCREDS1 username on terminal
+AND type credentials MYCREDS1 password on terminal
+AND type credentials MYCREDS1 username on terminal A
+AND type credentials MYCREDS1 password on terminal A
+```
+
+**Parameters:**
+
+- **MYCREDS1**: The credential name from your credentials store
+
+**Credentials configuration example** (`credentials.properties`):
+```properties
+secure.credentials.MYCREDS1.username=myuserid
+secure.credentials.MYCREDS1.password=mypassw0rd
+```
+
+**Example scenario:**
+```gherkin
+Scenario: Login with stored credentials
+  GIVEN a terminal
+  THEN wait for "Login" in any terminal field
+  AND type credentials MAINFRAME username on terminal
+  AND press terminal key TAB
+  AND type credentials MAINFRAME password on terminal
+  AND press terminal key ENTER
+```
+
+### Positioning the cursor
+
+Move the terminal cursor to a specific field:
+
+```gherkin
+AND move terminal cursor to field "xxx"
+```
+
+**Example:**
+```gherkin
+AND move terminal cursor to field "Command"
+```
+
+### Waiting for responses
+
+Wait for the terminal to be ready or for specific text to appear:
+
+```gherkin
+AND wait for terminal keyboard
+AND wait for terminal A keyboard
+THEN wait for "xxx" in any terminal field
+THEN wait for "xxx" in any terminal A field
+```
+
+**Examples:**
+```gherkin
+AND wait for terminal keyboard
+THEN wait for "Ready" in any terminal field
+THEN wait for "CICS" in any terminal B field
+```
+
+### Checking terminal output
+
+Verify that specific text appears on the terminal:
+
+```gherkin
+THEN check "xxx" appears only once on terminal
+THEN check "xxx" appears only once on terminal A
+```
+
+**Examples:**
+```gherkin
+THEN check "Transaction complete" appears only once on terminal
+THEN check "Error" appears only once on terminal B
+```
+
+## Configuration property steps
+
+### Retrieving test properties
+
+Get values from the Configuration Property Store (CPS):
+
+```gherkin
+GIVEN <VariableName> is test property namespace.property.name
+```
+
+**Note:** The `test` namespace prefix is automatically added, so you only specify the property name.
+
+**Examples:**
+```gherkin
+GIVEN <FruitName> is test property fruit.name
+GIVEN <ServerPort> is test property server.port
+GIVEN <Timeout> is test property connection.timeout
+```
+
+**Using the variable:**
+```gherkin
+Feature: Configuration Test
+  Scenario: Use configured fruit name
+    GIVEN <FruitName> is test property fruit.name
+    THEN Write to log "Testing with <FruitName>"
+```
+
+## Complete terminal interaction example
+
+Here is a complete example showing multiple step definitions working together:
+
+```gherkin
+Feature: CICS Transaction Test
+  
+  Scenario: Execute CICS transaction
+    # Allocate and configure terminal
+    GIVEN a terminal with 24 rows and 80 columns
+    
+    # Login to system
+    THEN wait for "VTAM" in any terminal field
+    AND type "LOGON APPLID(CICSRGN1)" on terminal
+    AND press terminal key ENTER
+    AND wait for terminal keyboard
+    
+    # Enter credentials
+    THEN wait for "User ID" in any terminal field
+    AND type credentials CICS username on terminal
+    AND press terminal key TAB
+    AND type credentials CICS password on terminal
+    AND press terminal key ENTER
+    
+    # Wait for CICS ready
+    THEN wait for "CICS" in any terminal field
+    AND press terminal key CLEAR
+    AND wait for terminal keyboard
+    
+    # Execute transaction
+    AND type "MYTR" on terminal
+    AND press terminal key ENTER
+    
+    # Verify result
+    THEN wait for "Transaction completed" in any terminal field
+    THEN check "Success" appears only once on terminal
+```
+
+## Step definition syntax patterns
+
+When writing steps, follow these patterns:
+
+**Terminal allocation:**
+
+- `GIVEN a terminal [with id of <id>] [tagged <tag>] [with <rows> rows and <columns> columns]`
+
+**Typing:**
+
+- `AND type "<text>" on terminal [<id>] [in field labelled "<label>"]`
+- `AND type credentials <credname> <username|password> on terminal [<id>]`
+
+**Key presses:**
+
+- `AND press terminal [<id>] key <keyname>`
+
+**Waiting:**
+
+- `AND wait for terminal [<id>] keyboard`
+- `THEN wait for "<text>" in any terminal [<id>] field`
+
+**Checking:**
+
+- `THEN check "<text>" appears only once on terminal [<id>]`
+
+**Configuration:**
+
+- `GIVEN <<variable>> is test property <property.name>`
+
+**Logging:**
+
+- `THEN Write to log "<message>"`
diff --git a/docs/content/docs/using-gherkin/gherkin-syntax-reference.md b/docs/content/docs/using-gherkin/gherkin-syntax-reference.md
new file mode 100644
index 000000000..93ec0be6f
--- /dev/null
+++ b/docs/content/docs/using-gherkin/gherkin-syntax-reference.md
@@ -0,0 +1,253 @@
+---
+title: "Gherkin syntax reference"
+---
+
+This page provides the formal grammar specification for Gherkin syntax supported by Galasa.
+
+## Formal grammar
+
+The following [Backus-Naur Form (BNF)](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form) defines the grammar supported by the Galasa Gherkin parser:
+
+```bnf
+<feature> ::= 'Feature:' <scenarioPartList> END_OF_FILE
+
+<scenarioPartList> ::= null
+                    | <scenarioPart> <scenarioPartList>
+
+<scenarioPart> ::= <scenarioOutline>
+                | <scenario>
+
+<scenario> ::= 'Scenario:' <stepList>
+
+<scenarioOutline> ::= 'Scenario Outline:' <stepList> 'Examples:' <dataTable>
+
+<stepList> ::= null
+            | <step> <stepList>
+
+<dataTable> ::= <dataHeaderLine> <dataValuesLineList>
+
+<dataTableHeader> ::= <dataLine>
+
+<dataTableValuesLineList> ::= null
+                            | <dataLine> <dataTableValuesLineList>
+
+<step> ::= <stepKeyword> <text>
+
+<stepKeyword> ::= "GIVEN" | "THEN" | "WHEN" | "AND"
+```
+
+## Grammar explanation
+
+### Feature
+
+A feature file must start with the `Feature:` keyword followed by one or more scenarios or scenario outlines.
+
+**Syntax:**
+```
+Feature: <feature name>
+  <scenarios>
+```
+
+### Scenario
+
+A scenario represents a single test case and contains a list of steps.
+
+**Syntax:**
+```
+Scenario: <scenario name>
+  <steps>
+```
+
+### Scenario Outline
+
+A scenario outline is a template for scenarios that can be executed multiple times with different data from an examples table.
+
+**Syntax:**
+```
+Scenario Outline: <scenario name>
+  <steps with variables>
+  Examples:
+    | <column headers> |
+    | <data row 1>     |
+    | <data row 2>     |
+```
+
+### Steps
+
+Steps are individual actions or assertions within a scenario. Each step starts with a keyword.
+
+**Syntax:**
+```
+<keyword> <step text>
+```
+
+**Keywords:**
+
+- `GIVEN` - Preconditions or setup
+- `WHEN` - Actions or events
+- `THEN` - Expected outcomes or assertions
+- `AND` - Continuation of the previous step type
+
+### Data Tables
+
+Data tables in scenario outlines provide test data for parameterized scenarios.
+
+**Syntax:**
+```
+Examples:
+  | column1 | column2 | column3 |
+  | value1  | value2  | value3  |
+  | value4  | value5  | value6  |
+```
+
+**Rules:**
+
+- First row contains column headers (variable names)
+- Subsequent rows contain data values
+- Columns are separated by `|` characters
+- Variable names in steps are surrounded by `<` and `>`
+
+## Syntax rules
+
+### Case sensitivity
+
+- Keywords (`Feature:`, `Scenario:`, `Scenario Outline:`, `Examples:`, `GIVEN`, `WHEN`, `THEN`, `AND`) are case-sensitive
+- Step text is case-sensitive
+- Variable names in scenario outlines are case-sensitive
+
+### Whitespace and indentation
+
+- Indentation is optional and ignored by the parser
+- Use indentation for readability
+- Leading and trailing whitespace in step text is trimmed
+
+### Comments
+
+- Comments start with `#`
+- Comments can appear on their own line or at the end of a line
+- Comments are ignored by the parser
+
+**Example:**
+```gherkin
+# This is a comment
+Feature: Example  # This is also a comment
+  Scenario: Test
+    GIVEN a terminal  # Comment after a step
+```
+
+### Line endings
+
+- Both Unix (`\n`) and Windows (`\r\n`) line endings are supported
+- Line endings are normalized during parsing
+
+## Limitations
+
+Galasa's Gherkin implementation has the following limitations compared to full Cucumber:
+
+1. **No Background sections:** Background steps that run before each scenario are not supported
+
+2. **No Tags:** Scenario and feature tags (like `@smoke`, `@regression`) are not supported
+
+3. **No Doc Strings:** Multi-line string arguments (using `"""`) are not supported
+
+4. **No Data Tables in steps:** Data tables as step arguments are not supported
+
+5. **Limited step definitions:** Only pre-implemented step definitions from Galasa Managers are available. Custom step definition implementation is not supported
+
+6. **No Hooks:** Before and After hooks are not supported
+
+7. **No Step Arguments:** Steps cannot have additional arguments beyond the step text
+
+## Valid examples
+
+### Minimal feature
+
+```gherkin
+Feature: Minimal
+  Scenario: Simple
+    THEN Write to log "Hello"
+```
+
+### Feature with multiple scenarios
+
+```gherkin
+Feature: Multiple Scenarios
+  Scenario: First
+    THEN Write to log "First"
+  
+  Scenario: Second
+    THEN Write to log "Second"
+```
+
+### Feature with scenario outline
+
+```gherkin
+Feature: Data Driven
+  Scenario Outline: Test with data
+    THEN Write to log "<message>"
+  
+  Examples:
+    | message |
+    | First   |
+    | Second  |
+```
+
+### Feature with comments
+
+```gherkin
+# This feature tests logging
+Feature: Logging Test
+  # This scenario logs a message
+  Scenario: Log message
+    # Write to the log
+    THEN Write to log "Test"
+```
+
+### Complex feature
+
+```gherkin
+Feature: Terminal Test
+  # Test basic terminal operations
+  Scenario: Allocate and use terminal
+    GIVEN a terminal
+    AND wait for terminal keyboard
+    THEN Write to log "Terminal ready"
+  
+  # Test with different terminal sizes
+  Scenario Outline: Terminal with size
+    GIVEN a terminal with <rows> rows and <columns> columns
+    THEN Write to log "Terminal size: <rows>x<columns>"
+  
+  Examples:
+    | rows | columns |
+    | 24   | 80      |
+    | 48   | 160     |
+```
+
+## Invalid examples
+
+### Missing Feature keyword
+
+```gherkin
+# INVALID: No Feature keyword
+Scenario: Test
+  THEN Write to log "Test"
+```
+
+### Scenario Outline without Examples
+
+```gherkin
+# INVALID: Scenario Outline requires Examples
+Feature: Invalid
+  Scenario Outline: Test
+    THEN Write to log "<message>"
+```
+
+### Invalid step keyword
+
+```gherkin
+# INVALID: 'BUT' is not a supported keyword
+Feature: Invalid
+  Scenario: Test
+    BUT Write to log "Test"
+```
diff --git a/docs/content/docs/using-gherkin/index.md b/docs/content/docs/using-gherkin/index.md
new file mode 100644
index 000000000..23c1a2c7a
--- /dev/null
+++ b/docs/content/docs/using-gherkin/index.md
@@ -0,0 +1,21 @@
+---
+title: "Using Gherkin with Galasa"
+---
+
+Galasa provides support for writing tests using Gherkin syntax, allowing you to express test scenarios in a human-readable format that supports Behavior-Driven Development (BDD) practices.
+
+## What is Gherkin?
+
+[Gherkin](https://cucumber.io/docs/gherkin/reference/) is a language popularized by [Cucumber](https://cucumber.io/) that provides a high-level syntax for expressing test steps and assertions. It allows you to write tests in a way that is understandable by both technical and non-technical stakeholders.
+
+## Galasa Gherkin support
+
+Galasa offers limited support for Gherkin syntax with pre-implemented step definitions available in standard Galasa Managers.
+
+## Getting started
+
+To start using Gherkin with Galasa:
+
+1. **Learn the basics**: Read [Writing Gherkin tests](./writing-gherkin-tests.md) to understand Gherkin syntax and structure
+2. **Explore step definitions**: Review [Available step definitions](./gherkin-step-definitions.md) to see what operations are supported
+3. **Run your tests**: Follow the guide on [Running Gherkin tests](./running-gherkin-tests.md) to execute your tests locally
diff --git a/docs/content/docs/using-gherkin/running-gherkin-tests.md b/docs/content/docs/using-gherkin/running-gherkin-tests.md
new file mode 100644
index 000000000..22258f22b
--- /dev/null
+++ b/docs/content/docs/using-gherkin/running-gherkin-tests.md
@@ -0,0 +1,133 @@
+---
+title: "Running Gherkin tests"
+---
+
+This guide explains how to run Gherkin tests locally and remotely using the Galasa CLI.
+
+## Prerequisites
+
+Before running Gherkin tests, ensure you have:
+
+1. **Initialized your Galasa environment:**
+   ```shell
+   galasactl local init
+   ```
+
+2. **Set up Java:** Ensure `JAVA_HOME` is set and points to a Java 17 JDK installation
+
+3. **Created a feature file:** Write your test in a `.feature` file
+
+## Running tests locally
+
+Use the `galasactl runs submit local` command with the `--gherkin` flag to run Gherkin tests on your local machine.
+
+```shell
+galasactl runs submit local --gherkin file:///path/to/test.feature --log -
+```
+
+**Path format:** The path must be in URL format:
+
+- Linux/macOS: `file:///Users/username/tests/test.feature`
+- Windows: `file:///C:/Users/username/tests/test.feature`
+
+The `--log -` flag sends logging output to the console (stderr).
+
+## Configuring your environment
+
+### Setting up CPS properties
+
+For tests that interact with z/OS systems, configure your `.galasa/cps.properties` file:
+
+```properties
+# Gherkin uses the 'PRIMARY' tag by default
+# The imageid property indicates which zos.image will be used
+zos.dse.tag.PRIMARY.imageid=MYHOST
+
+# The cluster name for your z/OS system
+zos.dse.tag.PRIMARY.clusterid=PLEXNAME
+
+# Images in the cluster (change MYHOSTIMAGE to your system name, e.g., MV2XX)
+zos.cluster.PLEXNAME.images=MYHOSTIMAGE
+
+# Hostname configuration (change MYHOST to match zos.dse.tag.PRIMARY.imageid)
+# Change machine.hostname to your actual hostname or IP address
+zos.image.MYHOST.default.hostname=machine.hostname
+zos.image.MYHOST.ipv4.hostname=machine.hostname
+
+# Sysplex configuration (change PLEXNAME to match zos.dse.tag.PRIMARY.clusterid)
+zos.image.MYHOST.sysplex=PLEXNAME
+
+# Telnet configuration
+zos.image.MYHOST.telnet.port=23
+zos.image.MYHOST.telnet.tls=false
+```
+
+**Configuration steps:**
+
+1. Replace `MYHOST` with your chosen image identifier
+2. Replace `PLEXNAME` with your z/OS cluster name
+3. Replace `MYHOSTIMAGE` with your actual system name
+4. Replace `machine.hostname` with your system's hostname or IP address
+
+### Terminal size configuration
+
+You can set default terminal dimensions using CPS properties:
+
+```properties
+# Default terminal size for Gherkin tests
+zos3270.gherkin.terminal.rows=24
+zos3270.gherkin.terminal.columns=80
+```
+
+These values can be overridden in your feature file or using override properties.
+
+## Example: Running a simple test
+
+### Create a feature file
+
+Create a file named `test1.feature`:
+
+```gherkin
+Feature: GherkinLog
+  Scenario: Log Example Statement
+    THEN Write to log "Hello World"
+```
+
+### Run the test
+
+```shell
+galasactl runs submit local --gherkin file:///test1.feature --log -
+```
+
+## Troubleshooting
+
+### Common issues
+
+**Issue:** `JAVA_HOME not set`
+
+- **Solution:** Set the `JAVA_HOME` environment variable to your Java 17 JDK installation
+
+**Issue:** `Feature file not found`
+
+- **Solution:** Ensure the path is in URL format and the file exists at that location
+
+**Issue:** `Connection timeout to z/OS system`
+
+- **Solution:** Verify your CPS properties are correct and the system is accessible
+
+**Issue:** `Step definition not found`
+
+- **Solution:** Check that you are using a supported step definition from the [Available step definitions](./gherkin-step-definitions.md) list
+
+### Getting help
+
+If you encounter issues:
+
+1. Check the [CLI prerequisites](../cli-command-reference/cli-prereqs.md)
+2. Verify your [local environment initialization](../cli-command-reference/initialising-home-folder.md)
+3. Review the [Available step definitions](./gherkin-step-definitions.md)
+4. Check the Galasa logs for detailed error messages
+
+## Command reference
+
+For complete command syntax and all available options, see [galasactl runs submit local](../reference/cli-syntax/galasactl_runs_submit_local.md)
diff --git a/docs/content/docs/using-gherkin/writing-gherkin-tests.md b/docs/content/docs/using-gherkin/writing-gherkin-tests.md
new file mode 100644
index 000000000..d12e3e343
--- /dev/null
+++ b/docs/content/docs/using-gherkin/writing-gherkin-tests.md
@@ -0,0 +1,188 @@
+---
+title: "Writing Gherkin tests"
+---
+
+This guide explains how to write Gherkin tests for Galasa, covering the syntax, structure, and best practices.
+
+## Feature files
+
+A feature file describes the feature you are testing. Feature files use the `.feature` extension and contain one or more test scenarios.
+
+**Basic structure:**
+```gherkin
+Feature: Feature name
+  Scenario: Scenario name
+    GIVEN some precondition
+    WHEN some action occurs
+    THEN some expected result
+```
+
+## A simple example
+
+Here is a minimal Gherkin test:
+
+```gherkin
+Feature: FruitLogger
+  Scenario: Log the cost of fruit
+    THEN Write to log "An apple costs 1"
+```
+
+**Key elements:**
+
+- **Feature**: Names the feature being tested. This name appears in test reports, so make it meaningful. Each file can only have one feature.
+
+- **Scenario**: Names a specific test case, similar to a test method in Java. A feature can contain multiple scenarios.
+
+- **Step**: An individual action or assertion. Steps start with keywords: `GIVEN`, `WHEN`, `THEN`, or `AND`.
+
+## Comments and formatting
+
+You can add comments and format your feature files for readability:
+
+```gherkin
+Feature: FruitLogger
+  # This is a simple feature which logs text to the test log.
+  Scenario: Log the cost of fruit
+    # We can log our favourite fruit.
+    THEN Write to log "An apple costs 1"
+```
+
+**Formatting rules:**
+
+- Comments start with `#` and are ignored by the test runner
+- Indentation is flexible and ignored during processing
+- Use indentation to improve readability
+
+## Multiple scenarios
+
+You can include multiple scenarios in a single feature file:
+
+```gherkin
+Feature: FruitLogger
+  Scenario: Log the cost of fruit-0
+    THEN Write to log "An apple costs 1"
+  
+  Scenario: Log the cost of fruit-1
+    THEN Write to log "A melon costs 2"
+```
+
+When executed, this creates one test (`FruitLogger`) with two test methods (`Log the cost of fruit-0` and `Log the cost of fruit-1`).
+
+## Scenario outlines
+
+Scenario outlines provide a template for scenarios that can be run multiple times with different data. This keeps your feature files concise and supports data-driven testing.
+
+**Example:**
+
+```gherkin
+Feature: FruitLogger
+  Scenario Outline: Log the cost of fruit
+    THEN Write to log "A <fruit> costs <cost>"
+  
+  Examples:
+    | fruit  | cost |
+    | apple  | 1    |
+    | melon  | 2    |
+```
+
+**How it works:**
+
+1. The `Examples:` section defines a data table with column headers (variable names) and data rows
+2. Variables in steps are surrounded by `<` and `>` brackets (for example, `<fruit>`)
+3. At runtime, the scenario outline expands into multiple scenarios, one for each data row
+4. Each generated scenario gets a suffix (`-0`, `-1`, `-2`) indicating which data row was used
+
+This example produces the same result as the multiple scenarios example above, but is more maintainable when you have many data variations.
+
+## Step keywords
+
+Gherkin uses four step keywords:
+
+- **GIVEN**: Sets up preconditions or initial state
+- **WHEN**: Describes an action or event
+- **THEN**: Specifies expected outcomes or assertions
+- **AND**: Continues the previous step type for readability
+
+**Example showing all keywords:**
+
+```gherkin
+Feature: Terminal Login
+  Scenario: Successful login
+    GIVEN a terminal
+    AND the terminal is connected
+    WHEN I type my username
+    AND I type my password
+    THEN I should see the main menu
+    AND the session should be active
+```
+
+While Galasa processes all keywords the same way, using them appropriately makes your tests more readable and follows BDD conventions.
+
+## Variables from configuration
+
+You can retrieve values from the Configuration Property Store (CPS) and use them in your tests:
+
+```gherkin
+Feature: Application Test
+  Scenario: Use configured values
+    GIVEN <FruitName> is test property fruit.name
+    THEN Write to log "Testing with <FruitName>"
+```
+
+**Syntax:** `GIVEN <VariableName> is test property namespace.property.name`
+
+The `test` namespace prefix is automatically added, so you only need to specify the property name after `test.`.
+
+## Complete example
+
+Here is a more complete example showing multiple features working together:
+
+```gherkin
+Feature: Test 3270 interactions
+  
+  Scenario Outline: Run a named transaction and check the result
+    GIVEN a terminal
+    
+    # Login to zOS
+    THEN wait for "MYCLUSTER1 VAMP" in any terminal field
+    AND type "LOGON APPLID(MYAPPLID1)" on terminal
+    AND wait for terminal keyboard
+    AND press terminal key ENTER
+    THEN wait for "*****" in any terminal field
+    AND press terminal key CLEAR
+    AND wait for terminal keyboard
+
+    # Run a transaction
+    AND type "<transaction>" on terminal
+    AND press terminal key ENTER
+    THEN wait for "<expectedMessage>" in any terminal field    
+
+    Examples:
+      | transaction | expectedMessage  |
+      | GRK1        | TEST MESSAGE     |
+      | GRK2        | SECOND TEST      |  
+      | GRK3        | THRICE THIS      |
+```
+
+This example demonstrates:
+
+- Terminal allocation
+- Waiting for specific text
+- Typing commands
+- Pressing special keys
+- Using scenario outlines with data tables
+- Comments for clarity
+
+## Best practices
+
+1. **Use meaningful names**: Feature and scenario names should clearly describe what is being tested
+
+2. **Keep scenarios focused**: Each scenario should test one specific behavior
+
+3. **Use scenario outlines for data variations**: When testing the same behavior with different data, use scenario outlines instead of duplicating scenarios
+
+4. **Add comments for clarity**: Use comments to explain complex steps or business logic
+
+5. **Organize logically**: Group related scenarios in the same feature file
+
+6. **Follow BDD conventions**: Use `GIVEN` for setup, `WHEN` for actions, and `THEN` for assertions
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 8a3969909..af0fde9ff 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -200,6 +200,12 @@ nav:
       - docs/writing-own-tests/key-principles.md
       - docs/writing-own-tests/test-result-provider.md
       - docs/writing-own-tests/running-resource-cleanup-locally.md
+    - Behavior-Driven Development with Galasa:
+      - docs/using-gherkin/index.md
+      - docs/using-gherkin/writing-gherkin-tests.md
+      - docs/using-gherkin/running-gherkin-tests.md
+      - docs/using-gherkin/gherkin-step-definitions.md
+      - docs/using-gherkin/gherkin-syntax-reference.md
     - Configuring Credentials:
       - docs/configuring-local-credentials/index.md
       - docs/configuring-local-credentials/macos-keychain-store.md

From ed51f9a5809084b04e7a6a8c81e6ad97c48614a5 Mon Sep 17 00:00:00 2001
From: Eamonn Mansour <47121388+eamansour@users.noreply.github.com>
Date: Tue, 12 May 2026 11:45:02 +0100
Subject: [PATCH 2/2] docs: Remove wikipedia link

Signed-off-by: Eamonn Mansour <47121388+eamansour@users.noreply.github.com>
---
 docs/content/docs/using-gherkin/gherkin-syntax-reference.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/content/docs/using-gherkin/gherkin-syntax-reference.md b/docs/content/docs/using-gherkin/gherkin-syntax-reference.md
index 93ec0be6f..6a5fc2a44 100644
--- a/docs/content/docs/using-gherkin/gherkin-syntax-reference.md
+++ b/docs/content/docs/using-gherkin/gherkin-syntax-reference.md
@@ -6,7 +6,7 @@ This page provides the formal grammar specification for Gherkin syntax supported
 
 ## Formal grammar
 
-The following [Backus-Naur Form (BNF)](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form) defines the grammar supported by the Galasa Gherkin parser:
+The following Backus-Naur Form (BNF) defines the grammar supported by the Galasa Gherkin parser:
 
 ```bnf
 <feature> ::= 'Feature:' <scenarioPartList> END_OF_FILE