Add support for @Before and @After hooks

README.md

@@ -84,14 +84,16 @@ Implemented pieces include:
 | Doc strings (`"""`)           | Supported   |
 | Comments (`#`)                | Supported   |
 | Tags (`@tag`)                 | Supported   |
+| `Before`, `After` hooks       | Supported   |
 | `Rule`                        | Unsupported |
 | `Scenario Outline`            | Unsupported |
 | `Examples`                    | Unsupported |
 | Data tables                   | Unsupported |
-| `Before`, `After` hooks       | Unsupported |
 | `BeforeAll`, `AfterAll` hooks | 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
+limited to a tag.
 
 ## Usage
 
@@ -209,10 +211,6 @@ shellkin --init
 Step definitions are shell snippets declared in files under
 `step_definitions/`.
 
-To share helper functions across step definition files, place them in
-`support.sh` under the features directory. For additional support scripts, use
-`--load` or configure them in `.shellkin`.
-
 ```bash
 @When I run '{command}'
   run "$command"
@@ -261,7 +259,54 @@ Then the text should include 'Jim "Jimbo" Jackson'
 The opening and closing quote in the feature step must match. Quoted token
 patterns do not match unquoted values.
 
-Each definition continues until the next step header or the end of the file.
+Each definition continues until the next step or hook header or the end of the
+file.
+
+## Step Definition Hooks
+
+Step definition files can also declare scenario hooks with `@Before` and
+`@After`.
+
+```bash
+@Before
+  mkdir -p tmp
+
+@After
+  rm -rf tmp
+
+@Before @needs-server
+  ./server start
+
+@After @needs-server
+  ./server stop
+```
+
+Hooks without a tag run for every scenario. Tagged hooks run only for scenarios
+with that tag, including tags inherited from the feature. `@Before` hooks run
+before background and scenario steps. `@After` hooks run after the scenario
+steps, even when a step or `@Before` hook fails.
+
+Hooks can call helper functions from `support.sh`:
+
+```bash
+# features/support.sh
+start_server() {
+  ./server start
+}
+
+stop_server() {
+  ./server stop
+}
+```
+
+```bash
+# features/step_definitions/hooks.sh
+@Before @needs-server
+  start_server
+
+@After @needs-server
+  stop_server
+```
 
 ## Step Helpers
 

doc/shellkin-feature.5

@@ -135,7 +135,7 @@ The following common Gherkin constructs are not currently supported:
 .IP \(bu 2
 data tables
 .IP \(bu 2
-hooks
+\f[B]BeforeAll\f[R] and \f[B]AfterAll\f[R] hooks
 .SH EXAMPLE
 .IP
 .EX

doc/shellkin-feature.md

@@ -162,7 +162,7 @@ The following common Gherkin constructs are not currently supported:
 - **Scenario Outline**
 - **Examples**
 - data tables
-- hooks
+- **BeforeAll** and **AfterAll** hooks
 
 EXAMPLE
 ==================================================

doc/shellkin-stepdefs.5

@@ -41,8 +41,8 @@ The step body is plain shell code.
 .PP
 Indenting the body is recommended for readability, but optional.
 .PP
-Each definition continues until the next valid step header or the end of
-the file.
+Each definition continues until the next valid step or hook header or
+the end of the file.
 .SS Tokens
 Patterns may contain named tokens in braces.
 .IP
@@ -74,6 +74,60 @@ Then the text should include \(aqJim \(dqJimbo\(dq Jackson\(aq
 .PP
 The opening and closing quote in the feature step must match.
 Quoted token patterns do not match unquoted values.
+.SH HOOKS
+Step definition files can also declare scenario hooks with
+\f[B]\(atBefore\f[R] and \f[B]\(atAfter\f[R].
+.IP
+.EX
+\(atBefore
+  mkdir \-p tmp
+
+\(atAfter
+  rm \-rf tmp
+
+\(atBefore \(atneeds\-server
+  ./server start
+
+\(atAfter \(atneeds\-server
+  ./server stop
+.EE
+.PP
+Hooks without a tag run for every scenario.
+Tagged hooks run only for scenarios with that tag, including tags
+inherited from the feature.
+.PP
+\f[B]\(atBefore\f[R] hooks run before background and scenario steps.
+If a \f[B]\(atBefore\f[R] hook fails, the scenario fails and the
+remaining steps are skipped.
+.PP
+\f[B]\(atAfter\f[R] hooks run after scenario steps, even when a step or
+\f[B]\(atBefore\f[R] hook fails.
+If an \f[B]\(atAfter\f[R] hook fails, the scenario fails.
+.PP
+Passing hooks are quiet.
+Failing hooks are shown in the error report.
+.PP
+Hooks can call helper functions from \f[B]support.sh\f[R]:
+.IP
+.EX
+\f[I]# features/support.sh\f[R]
+start_server() \f[B]{\f[R]
+  ./server start
+\f[B]}\f[R]
+
+stop_server() \f[B]{\f[R]
+  ./server stop
+\f[B]}\f[R]
+.EE
+.IP
+.EX
+\f[I]# features/step_definitions/hooks.sh\f[R]
+\(atBefore \(atneeds\-server
+  start_server
+
+\(atAfter \(atneeds\-server
+  stop_server
+.EE
 .SH HELPERS
 .SS run
 Run a shell command and capture its result for later assertions.

doc/shellkin-stepdefs.md

@@ -52,8 +52,8 @@ The step body is plain shell code.
 
 Indenting the body is recommended for readability, but optional.
 
-Each definition continues until the next valid step header or the end of the
-file.
+Each definition continues until the next valid step or hook header or the end
+of the file.
 
 Tokens
 --------------------------------------------------
@@ -88,6 +88,59 @@ Then the text should include 'Jim "Jimbo" Jackson'
 The opening and closing quote in the feature step must match. Quoted token
 patterns do not match unquoted values.
 
+HOOKS
+==================================================
+
+Step definition files can also declare scenario hooks with **@Before** and
+**@After**.
+
+```bash
+@Before
+  mkdir -p tmp
+
+@After
+  rm -rf tmp
+
+@Before @needs-server
+  ./server start
+
+@After @needs-server
+  ./server stop
+```
+
+Hooks without a tag run for every scenario. Tagged hooks run only for scenarios
+with that tag, including tags inherited from the feature.
+
+**@Before** hooks run before background and scenario steps. If a **@Before**
+hook fails, the scenario fails and the remaining steps are skipped.
+
+**@After** hooks run after scenario steps, even when a step or **@Before** hook
+fails. If an **@After** hook fails, the scenario fails.
+
+Passing hooks are quiet. Failing hooks are shown in the error report.
+
+Hooks can call helper functions from **support.sh**:
+
+```bash
+# features/support.sh
+start_server() {
+  ./server start
+}
+
+stop_server() {
+  ./server stop
+}
+```
+
+```bash
+# features/step_definitions/hooks.sh
+@Before @needs-server
+  start_server
+
+@After @needs-server
+  stop_server
+```
+
 HELPERS
 ==================================================
 

features/fixtures/hooks/hooks.feature

@@ -0,0 +1,11 @@
+Feature: hooks
+  Before and After hooks
+
+@needs-server
+Scenario: tagged hooks run before matching scenarios
+  Then the hook log should include 'before'
+  And the hook log should include 'server-start'
+
+Scenario: after hooks run after scenarios
+  Then the hook log should include 'after'
+  And the hook log should include 'server-stop'

features/fixtures/hooks/step_definitions/core.sh

@@ -0,0 +1,14 @@
+@Before
+  printf 'before\n' >>"$HOOK_LOG"
+
+@After
+  printf 'after\n' >>"$HOOK_LOG"
+
+@Before @needs-server
+  printf 'server-start\n' >>"$HOOK_LOG"
+
+@After @needs-server
+  printf 'server-stop\n' >>"$HOOK_LOG"
+
+@Then the hook log should include '{text}'
+  [[ "$(cat "$HOOK_LOG")" == *"$text"* ]]

features/fixtures/hooks/support.sh

@@ -0,0 +1,3 @@
+HOOK_LOG="${TMPDIR:-/tmp}/shellkin-hooks-$$.log"
+export HOOK_LOG
+: >"$HOOK_LOG"

features/test.feature

@@ -14,6 +14,12 @@ Scenario: Filtering scenarios by tag
   And the output should include '1 scenario, 0 failing'
   And the exit code should mean success
 
+Scenario: Running hooks from step definition files
+  When I run 'shellkin features/fixtures/hooks'
+  Then the output should include 'Feature: hooks'
+  And the output should include '2 scenarios, 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'