Add support for Scenario Outline and Examples

README.md

@@ -69,6 +69,7 @@ Implemented pieces include:
 - `Background`, `Scenario`, `Given` / `When` / `Then`, `And` / `But`, and `*`
 - doc strings via Gherkin-style `"""` blocks exposed as `DOC_STRING`
 - data tables exposed as `TABLE_HEADER` and `TABLE_ROWS` arrays
+- `Scenario Outline` expansion from one `Examples` table
 - colored terminal output and scenario summary
 
 ### Gherkin Feature Support
@@ -88,9 +89,9 @@ Implemented pieces include:
 | `Before`, `After` hooks       | Supported   |
 | `BeforeAll`, `AfterAll` hooks | Supported   |
 | Data tables                   | Supported   |
+| `Scenario Outline`            | Supported   |
+| `Examples`                    | Supported   |
 | `Rule`                        | Unsupported |
-| `Scenario Outline`            | Unsupported |
-| `Examples`                    | Unsupported |
 
 Tags can be selected with `--tag` / `-t` and skipped with `--exclude-tag` / `-x`.
 `@Before` and `@After` hooks are declared in step definition files and may be

doc/shellkin-feature.5

@@ -18,6 +18,8 @@ Shellkin currently supports these Gherkin keywords:
 .IP \(bu 2
 \f[B]Scenario\f[R]
 .IP \(bu 2
+\f[B]Scenario Outline\f[R], \f[B]Examples\f[R]
+.IP \(bu 2
 \f[B]Given\f[R], \f[B]When\f[R], \f[B]Then\f[R]
 .IP \(bu 2
 \f[B]And\f[R], \f[B]But\f[R], \f[B]*\f[R]
@@ -53,6 +55,30 @@ in the feature.
 Background:
   Given I am in a temp directory
 .EE
+.SS Scenario Outline
+Use \f[B]Scenario Outline:\f[R] with one \f[B]Examples:\f[R] table to
+run the same scenario with several values.
+Each Examples row is a separate scenario.
+.IP
+.EX
+Scenario Outline: Creating <name> as <role>
+  When I register user \(aq<name>\(aq with role \(aq<role>\(aq
+  Then user \(aq<name>\(aq should have role \(aq<role>\(aq
+
+Examples:
+  | name  | role   |
+  | Alice | admin  |
+  | Bob   | member |
+.EE
+.PP
+Placeholders may appear in the scenario name, steps, doc strings, and
+data table cells.
+Every placeholder must have a matching Examples column.
+Examples headings must be unique, and all rows must have the same number
+of cells.
+.PP
+Shellkin currently supports one Examples block per Scenario Outline.
+Tags on Examples blocks are not supported.
 .SS Steps
 Supported step keywords are \f[B]Given\f[R], \f[B]When\f[R],
 \f[B]Then\f[R], \f[B]And\f[R], \f[B]But\f[R], and \f[B]*\f[R].
@@ -147,10 +173,6 @@ Escaped pipe characters in cells are not currently supported.
 The following common Gherkin constructs are not currently supported:
 .IP \(bu 2
 \f[B]Rule\f[R]
-.IP \(bu 2
-\f[B]Scenario Outline\f[R]
-.IP \(bu 2
-\f[B]Examples\f[R]
 .SH EXAMPLE
 .IP
 .EX

doc/shellkin-feature.md

@@ -24,6 +24,7 @@ Shellkin currently supports these Gherkin keywords:
 - **Feature**
 - **Background**
 - **Scenario**
+- **Scenario Outline**, **Examples**
 - **Given**, **When**, **Then**
 - **And**, **But**, **\***
 - data tables
@@ -72,6 +73,30 @@ Background:
   Given I am in a temp directory
 ```
 
+Scenario Outline
+--------------------------------------------------
+
+Use **Scenario Outline:** with one **Examples:** table to run the same scenario
+with several values. Each Examples row is a separate scenario.
+
+```gherkin
+Scenario Outline: Creating <name> as <role>
+  When I register user '<name>' with role '<role>'
+  Then user '<name>' should have role '<role>'
+
+Examples:
+  | name  | role   |
+  | Alice | admin  |
+  | Bob   | member |
+```
+
+Placeholders may appear in the scenario name, steps, doc strings, and data
+table cells. Every placeholder must have a matching Examples column. Examples
+headings must be unique, and all rows must have the same number of cells.
+
+Shellkin currently supports one Examples block per Scenario Outline. Tags on
+Examples blocks are not supported.
+
 Steps
 --------------------------------------------------
 
@@ -177,8 +202,6 @@ UNSUPPORTED CONSTRUCTS
 The following common Gherkin constructs are not currently supported:
 
 - **Rule**
-- **Scenario Outline**
-- **Examples**
 
 EXAMPLE
 ==================================================

features/fixtures/scenario_outlines/scenario_outlines.feature

@@ -0,0 +1,14 @@
+Feature: scenario outlines
+  Run the same scenario with several examples
+
+Background:
+  Given the user registry is empty
+
+Scenario Outline: Creating <name> as <role>
+  When I register user '<name>' with role '<role>'
+  Then user '<name>' should have role '<role>'
+
+Examples:
+  | name  | role   |
+  | Alice | admin  |
+  | Bob   | member |

features/fixtures/scenario_outlines/step_definitions/core.sh

@@ -0,0 +1,17 @@
+@Given the user registry is empty
+  USER_NAMES=()
+  USER_ROLES=()
+
+@When I register user '{name}' with role '{role}'
+  USER_NAMES+=("$name")
+  USER_ROLES+=("$role")
+
+@Then user '{name}' should have role '{role}'
+  for index in "${!USER_NAMES[@]}"; do
+    if [[ ${USER_NAMES[$index]} == "$name" ]]; then
+      [[ ${USER_ROLES[$index]} == "$role" ]]
+      return
+    fi
+  done
+
+  fail "user not found: $name"

features/test.feature

@@ -28,6 +28,21 @@ Scenario: Running a feature that uses a data table
   And the output should include '1 scenario, 0 failing'
   And the exit code should mean success
 
+Scenario: Running a scenario outline
+  When I run 'shellkin features/fixtures/scenario_outlines'
+  Then the output should include 'Feature: scenario outlines'
+  And the output should include 'Scenario 1: Creating Alice as admin'
+  And the output should include 'Scenario 2: Creating Bob as member'
+  And the output should include '2 scenarios, 0 failing'
+  And the exit code should mean success
+
+Scenario: Selecting one expanded scenario outline row
+  When I run 'shellkin features/fixtures/scenario_outlines:2'
+  Then the output should include 'Scenario 2: Creating Bob as member'
+  And the output should not include 'Creating Alice as admin'
+  And the output should include '1 scenario, 0 failing'
+  And the exit code should mean success
+
 Scenario: Running a failing test
   When I run 'shellkin features/fixtures/selective/failing.feature'
   Then the output should include 'Feature: two'