├── .gitignore ├── LICENSE ├── README.md ├── go.mod ├── go.sum ├── lib.go ├── lib_test.go └── v2 ├── lib.go └── lib_test.go /.gitignore: -------------------------------------------------------------------------------- 1 | .idea/ 2 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 Antony Koch 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Ensure 2 | A scenario-based test runner for Go 3 | 4 | ## Installation 5 | ```bash 6 | go get github.com/iamkoch/ensure 7 | ``` 8 | 9 | ## Basic scenario 10 | 11 | ```go 12 | package myapp 13 | 14 | import ( 15 | "testing" 16 | "github.com/iamkoch/ensure" 17 | ) 18 | 19 | func TestExample(t *testing.T) { 20 | var aThing bool 21 | 22 | ensure.That("Testing a thing", func(s *ensure.Scenario) { 23 | s.Given("a thing is false", func() { 24 | aThing = false 25 | }) 26 | 27 | s.When("I set a thing to true", func() { 28 | aThing = true 29 | }) 30 | 31 | s.Then("the thing should be true", func() { 32 | if !aThing { 33 | t.Error("aThing should be true") 34 | } 35 | }) 36 | }, t) 37 | } 38 | 39 | ``` 40 | 41 | ## Background, And, Teardown 42 | This library also supports Background, And, and Teardown steps: 43 | 44 | ```go 45 | package myapp 46 | 47 | import ( 48 | "testing" 49 | "context" 50 | "github.com/iamkoch/ensure" 51 | ) 52 | 53 | func TestExample(t *testing.T) { 54 | var aThing bool 55 | 56 | ensure.That("Testing a thing", func(s *ensure.Scenario) { 57 | s.Background("Prepare the scenario", func() { 58 | // Do something here 59 | }) 60 | 61 | s.Given("a thing is false", func() { 62 | aThing = false 63 | }) 64 | 65 | s.And("another thing happens", func() { 66 | // Do another thing here 67 | }) 68 | 69 | s.When("I set a thing to true", func() { 70 | aThing = true 71 | }) 72 | 73 | s.Then("the thing should be true", func() { 74 | if !aThing { 75 | t.Error("aThing should be true") 76 | } 77 | }).Teardown("revert a thing", context.Background(), func(ctx context.Context) { 78 | aThing = false 79 | }) 80 | }, t) 81 | } 82 | 83 | ``` 84 | 85 | ## Printing 86 | Scenario text is, by default, printed to stdout using `fmt.Println`. This can be overridden by setting the `Printer` variable to a custom implementation of the `Printer` interface. 87 | 88 | This can be overridden by setting the `Printer` variable to a custom implementation of the `Printer` interface. 89 | 90 | ```go 91 | package myapp 92 | 93 | type testPrinter struct { 94 | entries []string 95 | } 96 | 97 | func (t *testPrinter) Write(s string) { 98 | t.entries = append(t.entries, s) 99 | } 100 | 101 | func (t *testPrinter) Output() string { 102 | var output string 103 | for _, entry := range t.entries { 104 | output += entry + "\n" 105 | } 106 | return output 107 | } 108 | 109 | func init() { 110 | ensure.Printer = &testPrinter{} 111 | } 112 | 113 | func TestMyThing(t *testing.T) { 114 | ... 115 | } 116 | ``` 117 | 118 | 119 | 120 | ## Full Example 121 | This is taken from our own test in `lib_test.go`: 122 | 123 | ```go 124 | func TestFullScenario(t *testing.T) { 125 | var ( 126 | testCtx = context.Background() 127 | aThing bool 128 | anotherThing bool 129 | tornDown = false 130 | ) 131 | 132 | That("A full scenario runs as expected", func(s *Scenario) { 133 | s.Given("a thing is false", func() { 134 | aThing = false 135 | }) 136 | 137 | s.And("another thing is true", func() { 138 | anotherThing = true 139 | }).Teardown("revert anotherThing", testCtx, func(ctx context.Context) { 140 | anotherThing = false 141 | }) 142 | 143 | s.When("I do the old swaperoo", func() { 144 | aThing = true 145 | anotherThing = false 146 | }) 147 | 148 | s.Then("the a thing should be true", func() { 149 | require.Equal(t, true, aThing) 150 | }) 151 | 152 | s.And("anotherThing should be false", func() { 153 | require.Equal(t, false, anotherThing) 154 | }).Teardown("tearDown", testCtx, func(ctx context.Context) { 155 | tornDown = true 156 | }) 157 | }, t) 158 | 159 | require.True(t, tornDown) 160 | 161 | require.Equal(t, `Scenario: A full scenario runs as expected 162 | Given a thing is false 163 | And another thing is true 164 | When I do the old swaperoo 165 | Then the a thing should be true 166 | And anotherThing should be false 167 | Tearing down revert anotherThing 168 | Tearing down tearDown 169 | `, Printer.(*testPrinter).Output(), "output should be as expected") 170 | } 171 | 172 | ``` 173 | -------------------------------------------------------------------------------- /go.mod: -------------------------------------------------------------------------------- 1 | module github.com/iamkoch/ensure/v2 2 | 3 | go 1.19 4 | 5 | require github.com/stretchr/testify v1.10.0 6 | 7 | require ( 8 | github.com/davecgh/go-spew v1.1.1 // indirect 9 | github.com/pmezard/go-difflib v1.0.0 // indirect 10 | gopkg.in/yaml.v3 v3.0.1 // indirect 11 | ) 12 | -------------------------------------------------------------------------------- /go.sum: -------------------------------------------------------------------------------- 1 | github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= 2 | github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= 3 | github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= 4 | github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= 5 | github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk= 6 | github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo= 7 | github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= 8 | github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= 9 | gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= 10 | gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= 11 | gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= 12 | gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= 13 | -------------------------------------------------------------------------------- /lib.go: -------------------------------------------------------------------------------- 1 | package ensure 2 | 3 | import ( 4 | "context" 5 | "fmt" 6 | "testing" 7 | ) 8 | 9 | type ScenarioPrinter interface { 10 | Write(s string) 11 | } 12 | 13 | type fmtPrinter struct { 14 | } 15 | 16 | func (d fmtPrinter) Write(s string) { 17 | fmt.Println(s) 18 | } 19 | 20 | var ( 21 | Printer ScenarioPrinter = &fmtPrinter{} 22 | ) 23 | 24 | func That(s string, f func(s *Scenario), t *testing.T) { 25 | Printer.Write("Scenario: " + s) 26 | scn := &Scenario{ 27 | t: t, 28 | } 29 | f(scn) 30 | for _, f2 := range scn.teardownMethods { 31 | Printer.Write("Tearing down " + f2.name) 32 | f2.f() 33 | } 34 | } 35 | 36 | type Scenario struct { 37 | teardownMethods []tearDown 38 | t *testing.T 39 | } 40 | 41 | func (s2 *Scenario) Given(s string, f func()) *Scenario { 42 | Printer.Write(" Given " + s) 43 | f() 44 | return s2 45 | } 46 | 47 | func (s2 *Scenario) And(s string, f func()) *Scenario { 48 | Printer.Write(" And " + s) 49 | f() 50 | return s2 51 | } 52 | 53 | func (s2 *Scenario) When(s string, f func()) *Scenario { 54 | Printer.Write(" When " + s) 55 | f() 56 | return s2 57 | } 58 | 59 | func (s2 *Scenario) Background(s string, f func()) *Scenario { 60 | Printer.Write(" Background " + s) 61 | f() 62 | return s2 63 | } 64 | 65 | func (s2 *Scenario) Then(s string, f func()) *Scenario { 66 | Printer.Write(" Then " + s) 67 | f() 68 | return s2 69 | } 70 | 71 | // Teardown adds a function to be called when the scenario ends. 72 | // The function is passed a context that is cancelled when the scenario ends. 73 | func (s2 *Scenario) Teardown(s string, ctx context.Context, f func(ctx context.Context)) *Scenario { 74 | s2.addTearDown(s, func() { 75 | ctx.Done() 76 | f(ctx) 77 | }) 78 | return s2 79 | } 80 | 81 | func (s2 *Scenario) addTearDown(s string, f func()) { 82 | s2.teardownMethods = append(s2.teardownMethods, tearDown{ 83 | name: s, 84 | f: f, 85 | }) 86 | } 87 | 88 | func (s2 *Scenario) NotImplemented() { 89 | s2.t.Fatal("Not implemented") 90 | } 91 | 92 | type tearDown struct { 93 | name string 94 | f func() 95 | } 96 | -------------------------------------------------------------------------------- /lib_test.go: -------------------------------------------------------------------------------- 1 | package ensure 2 | 3 | import ( 4 | "context" 5 | "github.com/stretchr/testify/require" 6 | "testing" 7 | ) 8 | 9 | type testPrinter struct { 10 | entries []string 11 | } 12 | 13 | func (t *testPrinter) Write(s string) { 14 | t.entries = append(t.entries, s) 15 | } 16 | 17 | func (t *testPrinter) Output() string { 18 | var output string 19 | for _, entry := range t.entries { 20 | output += entry + "\n" 21 | } 22 | return output 23 | } 24 | 25 | func init() { 26 | Printer = &testPrinter{} 27 | } 28 | 29 | func TestFullScenario(t *testing.T) { 30 | var ( 31 | testCtx = context.Background() 32 | aThing bool 33 | anotherThing bool 34 | tornDown = false 35 | ) 36 | 37 | That("A full scenario runs as expected", func(s *Scenario) { 38 | s.Given("a thing is false", func() { 39 | aThing = false 40 | }) 41 | 42 | s.And("another thing is true", func() { 43 | anotherThing = true 44 | }).Teardown("revert anotherThing", testCtx, func(ctx context.Context) { 45 | anotherThing = false 46 | }) 47 | 48 | s.When("I do the old swaperoo", func() { 49 | aThing = true 50 | anotherThing = false 51 | }) 52 | 53 | s.Then("the a thing should be true", func() { 54 | require.Equal(t, true, aThing) 55 | }) 56 | 57 | s.And("anotherThing should be false", func() { 58 | require.Equal(t, false, anotherThing) 59 | }).Teardown("tearDown", testCtx, func(ctx context.Context) { 60 | tornDown = true 61 | }) 62 | }, t) 63 | 64 | require.True(t, tornDown) 65 | 66 | require.Equal(t, `Scenario: A full scenario runs as expected 67 | Given a thing is false 68 | And another thing is true 69 | When I do the old swaperoo 70 | Then the a thing should be true 71 | And anotherThing should be false 72 | Tearing down revert anotherThing 73 | Tearing down tearDown 74 | `, Printer.(*testPrinter).Output(), "output should be as expected") 75 | } 76 | -------------------------------------------------------------------------------- /v2/lib.go: -------------------------------------------------------------------------------- 1 | package ensure 2 | 3 | import ( 4 | "context" 5 | "testing" 6 | ) 7 | 8 | func That(scenarioName string, scenarioFunc func(s *Scenario), t *testing.T) { 9 | t.Run("Scenario__"+scenarioName, func(t *testing.T) { 10 | scenario := &Scenario{t: t} 11 | scenarioFunc(scenario) 12 | for _, teardown := range scenario.teardownMethods { 13 | t.Run("Teardown of "+teardown.name, func(t *testing.T) { 14 | teardown.f() 15 | }) 16 | } 17 | }) 18 | } 19 | 20 | type Scenario struct { 21 | teardownMethods []tearDown 22 | t *testing.T 23 | } 24 | 25 | func (s *Scenario) Given(stepName string, stepFunc func(t *testing.T)) *Scenario { 26 | s.t.Run("Given "+stepName, func(t *testing.T) { 27 | stepFunc(t) 28 | }) 29 | return s 30 | } 31 | 32 | func (s *Scenario) And(stepName string, stepFunc func(t *testing.T)) *Scenario { 33 | s.t.Run("And "+stepName, func(t *testing.T) { 34 | stepFunc(t) 35 | }) 36 | return s 37 | } 38 | 39 | func (s *Scenario) When(stepName string, stepFunc func(t *testing.T)) *Scenario { 40 | s.t.Run("When "+stepName, func(t *testing.T) { 41 | stepFunc(t) 42 | }) 43 | return s 44 | } 45 | 46 | func (s *Scenario) Background(stepName string, stepFunc func(t *testing.T)) *Scenario { 47 | s.t.Run("Background of "+stepName, func(t *testing.T) { 48 | stepFunc(t) 49 | }) 50 | return s 51 | } 52 | 53 | func (s *Scenario) Then(stepName string, stepFunc func(t *testing.T)) *Scenario { 54 | s.t.Run("Then "+stepName, func(t *testing.T) { 55 | stepFunc(t) 56 | }) 57 | return s 58 | } 59 | 60 | // Teardown adds a function to be called when the scenario ends. 61 | // The function is passed a context that is canceled when the scenario ends. 62 | func (s *Scenario) Teardown(stepName string, ctx context.Context, teardownFunc func(ctx context.Context)) *Scenario { 63 | s.addTearDown(stepName, func() { 64 | teardownFunc(ctx) 65 | }) 66 | return s 67 | } 68 | 69 | func (s *Scenario) addTearDown(name string, f func()) { 70 | s.teardownMethods = append(s.teardownMethods, tearDown{ 71 | name: name, 72 | f: f, 73 | }) 74 | } 75 | 76 | func (s *Scenario) NotImplemented() { 77 | s.t.Fatal("Not implemented") 78 | } 79 | 80 | type tearDown struct { 81 | name string 82 | f func() 83 | } 84 | -------------------------------------------------------------------------------- /v2/lib_test.go: -------------------------------------------------------------------------------- 1 | package ensure 2 | 3 | import ( 4 | "context" 5 | "github.com/stretchr/testify/assert" 6 | "github.com/stretchr/testify/require" 7 | "testing" 8 | ) 9 | 10 | func TestFullScenario(t *testing.T) { 11 | var ( 12 | testCtx = context.Background() 13 | aThing bool 14 | anotherThing bool 15 | tornDown = false 16 | ) 17 | 18 | That("A full scenario runs as expected", func(s *Scenario) { 19 | s.Given("a thing is false", func(t *testing.T) { 20 | aThing = false 21 | }) 22 | 23 | s.And("another thing is true", func(t *testing.T) { 24 | anotherThing = true 25 | }).Teardown("revert anotherThing", testCtx, func(ctx context.Context) { 26 | anotherThing = false 27 | }) 28 | 29 | s.When("I do the old swaperoo", func(t *testing.T) { 30 | aThing = true 31 | anotherThing = false 32 | }) 33 | 34 | s.Then("the a thing should be true", func(t *testing.T) { 35 | assert.Equal(t, true, aThing) 36 | }) 37 | 38 | s.And("anotherThing should be false", func(t *testing.T) { 39 | require.Equal(t, false, anotherThing) 40 | }).Teardown("tearDown", testCtx, func(ctx context.Context) { 41 | tornDown = true 42 | }) 43 | }, t) 44 | 45 | require.True(t, tornDown) 46 | 47 | } 48 | --------------------------------------------------------------------------------