Implement BDD-style bifurcated evaluation of nested test branches (#14)

- Add bdd package to support proper BDD-style bifurcated evaluation of test branches
- Update readme to include description, rationale and usage for the `bdd` package
- Add code snippets and link in README
- Update release notes for v1.1.0

Author: maargenton

README.md

@@ -1,7 +1,7 @@
 # go-testpredicate
 
-Test assertions library using predicate-like syntax, producing extensive
-diagnostics output
+Test assertions library using a test predicate style syntax, and producing
+extensive diagnostics output
 
 [![Latest](
   https://img.shields.io/github/v/tag/maargenton/go-testpredicate?color=blue&label=latest&logo=go&logoColor=white&sort=semver)](
@@ -19,9 +19,10 @@ diagnostics output
 
 ---------------------------
 
-Package `go-testpredicate` is a test assertions library exposing a
-predicate-like syntax that works with Go testing support to provide extensive
-diagnostics output and reduces the need to use a debugger on every failing test.
+Package `go-testpredicate` is a test assertions library exposing a test
+predicate style syntax for use with the built-in Go `testing` package, producing
+extensive diagnostics output and reducing the need to use a debugger on every
+failing test.
 
 The library contains an extensive collection of built-in predicates covering:
 
@@ -33,29 +34,40 @@ The library contains an extensive collection of built-in predicates covering:
 - set conditions on unordered collections
 - panic conditions on code fragment execution
 
+It also includes a BDD-style bifurcated evaluation context, where each test
+section is potentially evaluated multiple times in order to evaluate each branch
+independently.
+
 
 ## Installation
 
-    go get github.com/maargenton/go-testpredicate
+```
+go get github.com/maargenton/go-testpredicate
+```
+
+Optionally, you can add predefined code snippets for your text editor or IDE to
+assist in writing  your test code. Snippets for VSCode are available
+[here](docs/snippets.md)
 
 ## Usage
 
 ```go
-package examples_test
+package example_test
 
 import (
     "testing"
 
+    "github.com/maargenton/go-testpredicate/pkg/bdd"
     "github.com/maargenton/go-testpredicate/pkg/require"
     "github.com/maargenton/go-testpredicate/pkg/verify"
 )
 
 func TestExample(t *testing.T) {
-    t.Run("Given ", func(t *testing.T) {
+    bdd.Given(t, "something", func(t *bdd.T) {
         require.That(t, 123).ToString().Length().Eq(3)
 
-        t.Run("when ", func(t *testing.T) {
-            t.Run("then ", func(t *testing.T) {
+        t.When("doing something", func(t *bdd.T) {
+            t.Then("something happens ", func(t *bdd.T) {
                 verify.That(t, "123").Eq(123)
                 verify.That(t, 123).ToString().Length().Eq(4)
             })
@@ -67,14 +79,14 @@ func TestExample(t *testing.T) {
 Output:
 ```
 --- FAIL: TestExample (0.00s)
-    --- FAIL: TestFoo/Given_ (0.00s)
-        --- FAIL: TestFoo/Given_/when_ (0.00s)
-            --- FAIL: TestFoo/Given_/when_/then_ (0.00s)
-                usage_test.go:16:
+    --- FAIL: TestExample/Given_something (0.00s)
+        --- FAIL: TestExample/Given_something/when_doing_something (0.00s)
+            --- FAIL: TestExample/Given_something/when_doing_something/then_something_happens_ (0.00s)
+                example_test.go:17:
                     expected: value == 123
                     error:    values of type 'string' and 'int' are never equal
                     value:    "123"
-                usage_test.go:17:
+                example_test.go:18:
                     expected: length(value.String()) == 4
                     value:    123
                     string:   "123"
@@ -206,3 +218,121 @@ func TestStringAPI(t *testing.T) {
     verify.That(t, "aBc").ToUpper().Eq("ABC")
 }
 ```
+
+## BDD-style bifurcated tests
+
+### Rationale
+
+First of all, the Go `testing` package is great and the fact that it is
+standard, built in and integrated with the Go tooling infrastructure is awesome.
+This is why the `go-testpredicate` packages strives to enhance it instead of
+replacing it, unlike many other testing packages.
+
+If you look at other unit-testing packages, in other languages, you will find
+either traditional xUnit style packages relying on classes to define test suites
+and fixtures and test cases, or more recent testing packages (like
+[Catch-2](https://github.com/catchorg/Catch2) for C++) that provide, through
+other means, ways to define setup and test cases than run independently. The
+common pattern is that setup code, that may be shared by multiple test cases, is
+usually re-evaluated for every test case so that, despite their potentially
+mutating interactions with the setup, test cases don't affect each other.
+
+Some great articles and blog posts have explained how the leverage nested
+`t.Run()` calls to structure tests in way that is closer to BDD-style given /
+when / then paradigm. Unfortunately, when using thees approaches, and especially
+with shared setup sections, the test cases are no longer independent, as all
+branches are run sequentially, going up and down each branch and into the next
+branch, without resetting the setup.
+
+The `bdd` package in `go-testpredicate` provides a way to write tests with a
+BDD-style structure, using the built-in `testing.T`, but evaluating the test
+cases in a bifurcated fashion, repeating the evaluation of each entire branch
+for every leaf test case, so that test cases are independent from each other
+again.
+
+### Usage overview
+
+`bdd.Wrap()` or `bdd.Given()` are the root level function that setup and iterate
+through the bifurcated test evaluation context. They define blocks that receive
+a `bdd.T` instead of `testing.T`, but `bdd.T` is fully compatible with
+`testing.T` and can be used with any third party library that expect either the
+`testing.TB` interface or a subset of it (including out own `verify.That()` /
+`require.That()`).
+
+Nested and sibling bifurcated branches are defined with `t.Run()` (on `bdd.T`)
+or `t.When()` / `t.Then()` for BDD style.
+
+> **IMPORTANT:** In a bifurcated evaluation context, as defined by `bdd.T`, test
+> scenarios are run repeatedly in order to evaluate each branch (from root to
+> leaf) independently of each other. When a particular branch is being
+> evaluated, all the other forks and sub-branches are skipped; the other
+> branches are run in separated independent iterations of the scenario.
+
+### Usage, traditional style
+
+```go
+package example_test
+
+import (
+    "testing"
+    "github.com/maargenton/go-testpredicate/pkg/bdd"
+)
+
+func TesTraditional(t *testing.T) {
+
+    // Global immutable setup code can go here
+
+    bdd.Wrap(t, "Given something", func(t *bdd.T) {
+
+        // Local mutable setup code goes here
+
+        t.Run("something happens", func(t *bdd.T) {
+
+            // When this code runs, the code in following `t.Run()` blocks
+            // will be skipped.
+        })
+        t.Run("something else happens", func(t *bdd.T) {
+
+            // When this code runs, all code in preceding `t.Run()` blocks
+            // has been skipped and did not affect the local setup.
+        })
+    })
+}
+```
+
+### Usage, BDD style
+
+```go
+package bdd_test
+
+import (
+    "testing"
+    "github.com/maargenton/go-testpredicate/pkg/bdd"
+)
+
+func TestBDDStyle(t *testing.T) {
+
+    // Global immutable setup code can go here
+
+    bdd.Given(t, "something", func(t *bdd.T) {
+
+        // Local mutable setup code goes here
+
+        t.When("doing something", func(t *bdd.T) {
+
+            // or here
+
+            t.Then("something happens", func(t *bdd.T) {
+
+                // When this code runs, the code in the following `t.Then()`
+                // blocks will be skipped.
+            })
+            t.Then("something else happens", func(t *bdd.T) {
+
+                // When this code runs, all code in preceding `t.Then()`
+                // blocks has been skipped and did not affect the local setup.
+            })
+        })
+    })
+}
+```

RELEASES.md

@@ -1,3 +1,11 @@
+# v1.1.0
+
+## Major Changes
+
+- Add `bdd` sub-package to support BDD-style bifurcated execution of nested test
+  sections.
+
+
 # v1.0.0
 
 ## Major Changes

docs/snippets.md

@@ -0,0 +1,70 @@
+## VS Code snippets
+
+In VSCode, open the command palette (⌘⇧P / ^⇧P) and select '_Preferences:
+Configure User Snippets_', then '_go.json_' and add any or all of the following
+snippets:
+- `tfbdd`: inserts the definition of a test function with BDD-style given /when
+  / then blocks, using the bifurcated execution context define in the `bdd`
+  sub-package.
+- `tftcs`: inserts the definition of a test function with data-driven test cases
+  and BDD-style given /when / then blocks, using the bifurcated execution
+  context define in the `bdd` sub-package.
+- `require.That` or `reth`: inserts a placeholder for require.That() statement.
+- `verify.That` or `veth`: inserts a placeholder for verify.That() statement.
+
+```json
+"test function bdd": {
+    "prefix": "tfbdd",
+    "body": [
+        "func Test$1(t *testing.T) {",
+        "\tbdd.Given(t, \"${2:something}\", func(t *bdd.T) {",
+        "\t\tt.When(\"${3:doing something}\", func(t *bdd.T) {",
+        "\t\t\tt.Then(\"${4:something happens}\", func(t *bdd.T) {",
+        "\t\t\t\trequire.That(t, ${5:\"123\"}).Eq(${6:123})",
+        "\t\t\t\t$0",
+        "\t\t\t})",
+        "\t\t})",
+        "\t})",
+        "}",
+    ],
+    "description": "Test function with BDD-style given/when/then and require.That"
+},
+"test function bdd with test cases": {
+    "prefix": "tftcs",
+    "body": [
+        "func Test$1(t *testing.T) {",
+        "\tvar tcs = []struct {",
+        "\t\tname string",
+        "\t}{",
+        "\t\t{\"${2:test case}\"},",
+        "\t}",
+        "\t",
+        "\tfor _, tc := range tcs {",
+        "\t\tbdd.Given(t, tc.name, func(t *bdd.T) {",
+        "\t\t\tt.When(\"${3:doing something}\", func(t *bdd.T) {",
+        "\t\t\t\tt.Then(\"${4:something happens}\", func(t *bdd.T) {",
+        "\t\t\t\t\trequire.That(t, ${5:\"123\"}).Eq(${6:123})",
+        "\t\t\t\t\t$0",
+        "\t\t\t\t})",
+        "\t\t\t})",
+        "\t\t})",
+        "\t}",
+        "}",
+    ],
+    "description": "Test function with BDD-style given/when/then, test cases and require.That"
+},
+"verify": {
+    "prefix": "verify.That",
+    "body": [
+        "verify.That(t, ${0:\"\"}).Eq(\"\")",
+    ],
+    "description": "verifty.That()"
+},
+"require": {
+    "prefix": "require.That",
+    "body": [
+        "require.That(t, ${0:\"\"}).Eq(\"\")",
+    ],
+    "description": "verifty.That()"
+},
+```

pkg/bdd/bdd.go

@@ -0,0 +1,75 @@
+// Package bdd defines a BDD-style bifurcated evaluation context, compatible
+// with the build-in testing package.
+package bdd
+
+import (
+	"fmt"
+	"testing"
+)
+
+// T is a testing context, similar to testing.T, passed to the testing functions
+// in the BDD style bifurcated test evaluation. It forwards most of the
+// testing.T API by encapsulating the current test context as a `TB` interface;
+// only `Parallel()` is dropped as non-relevant.
+//
+// The `Run()` function has a similar interface as testing.T, but passing a
+// bdd.T object for the nested testing context, and evaluating all branches in a
+// BDD style bifurcated fashion, where each branch is fully and independently
+// re-evaluated for every leaf.
+//
+// Additional functions `When()` and `Then()` are syntactic sugar on top the
+// `Run()` function. `bdd.Given()` is the root function that initializes the
+// bifurcated evaluation context and runs all the branches.
+type T struct {
+	TB
+	t       *testing.T
+	tracker *tracker
+}
+
+// Run defines a new fork in the current bifurcated evaluation context.
+func (b *T) Run(name string, f func(b *T)) bool {
+	success := true
+	if b.tracker.Active() {
+		success = success && b.t.Run(name, func(t *testing.T) {
+			f(&T{t, t, b.tracker.SubTracker()})
+		})
+	}
+	return success
+}
+
+// When adds syntactic sugar on top of `bdd.T.Run()` and prefixes the name
+// of the section with 'when ...'.
+func (b *T) When(name string, f func(b *T)) bool {
+	name = fmt.Sprintf("when %v", name)
+	return b.Run(name, f)
+}
+
+// Then adds syntactic sugar on top of `bdd.T.Run()` and prefixes the name
+// of the section with 'then ...'.
+func (b *T) Then(name string, f func(b *T)) bool {
+	name = fmt.Sprintf("then %v", name)
+	return b.Run(name, f)
+}
+
+// Wrap is the root function that wraps the top level testing.T context and
+// starts a bifurcated bdd.T evaluation context.
+func Wrap(t *testing.T, name string, f func(b *T)) bool {
+	tracker := &tracker{}
+	success := true
+	for tracker.Next() {
+		if tracker.Active() {
+			s := t.Run(name, func(t *testing.T) {
+				f(&T{t, t, tracker.SubTracker()})
+			})
+			success = success && s
+		}
+	}
+	return success
+}
+
+// Given adds syntactic sugar on top of `bdd.Wrap()` and prefixes the name
+// of the section with 'Given ...'.
+func Given(t *testing.T, name string, f func(b *T)) bool {
+	name = fmt.Sprintf("Given %v", name)
+	return Wrap(t, name, f)
+}