|
| 1 | +// Copyright (c) 2021, Maxime Soulé |
| 2 | +// All rights reserved. |
| 3 | +// |
| 4 | +// This source code is licensed under the BSD-style license found in the |
| 5 | +// LICENSE file in the root directory of this source tree. |
| 6 | + |
| 7 | +// Package tdsuite adds tests suite feature to go-testdeep in a |
| 8 | +// non-intrusive way, but easily and powerfully. |
| 9 | +// |
| 10 | +// A tests suite is a set of tests run sequentially that share some data. |
| 11 | +// |
| 12 | +// Some hooks can be set to be automatically called before the suite |
| 13 | +// is run, before, after and/or between each test, and at the end of |
| 14 | +// the suite. |
| 15 | +// |
| 16 | +// In addition, a test can discontinue the suite. |
| 17 | +// |
| 18 | +// Giving a suite using a MySuite type, the test methods have the form: |
| 19 | +// |
| 20 | +// func (s *MySuite) TestXxx(t *td.T) |
| 21 | +// func (s *MySuite) TestXxx(assert, require *td.T) |
| 22 | +// |
| 23 | +// where Xxx does not start with a lowercase letter. Each test method |
| 24 | +// is run in a subtest, the method name serves to identify the |
| 25 | +// subtest. |
| 26 | +// |
| 27 | +// A test method can return a bool, as in: |
| 28 | +// |
| 29 | +// func (s *MySuite) TestXxx(t *td.T) bool |
| 30 | +// func (s *MySuite) TestXxx(assert, require *td.T) bool |
| 31 | +// |
| 32 | +// in this case, returning false means discontinuing the suite without |
| 33 | +// any error. Consider it as a skip feature. |
| 34 | +// |
| 35 | +// A test method can instead return an error, as in: |
| 36 | +// |
| 37 | +// func (s *MySuite) TestXxx(t *td.T) error |
| 38 | +// func (s *MySuite) TestXxx(assert, require *td.T) error |
| 39 | +// |
| 40 | +// in this case, returning a non-nil error marks the test as having |
| 41 | +// failed, logs the error and discontinues the suite. |
| 42 | +// |
| 43 | +// A test method can also return a tuple (bool, error), as in: |
| 44 | +// |
| 45 | +// func (s *MySuite) TestXxx(t *td.T) (bool, error) |
| 46 | +// func (s *MySuite) TestXxx(assert, require *td.T) (bool, error) |
| 47 | +// |
| 48 | +// in this case, both returned values are independent. Returning a |
| 49 | +// false boolean means discontinuing the suite while returning a |
| 50 | +// non-nil error marks the test as having failed and logs the |
| 51 | +// error. So: |
| 52 | +// |
| 53 | +// Returning do... |
| 54 | +// (false, nil) continue the suite, do not log anything |
| 55 | +// (false, ERROR) continue the suite, marks the test as failed & log ERROR |
| 56 | +// (true, nil) discontinue the suite & log the discontinuation |
| 57 | +// (true, ERROR) discontinue the suite & log the discontinuation, marks the |
| 58 | +// test as failed & log ERROR |
| 59 | +// |
| 60 | +// Test methods are run in lexicographic order. |
| 61 | +// |
| 62 | +// Very simple tests suite |
| 63 | +// |
| 64 | +// Used typically to group tests and benefit from already instanciated |
| 65 | +// *td.T instances. |
| 66 | +// |
| 67 | +// import ( |
| 68 | +// "testing" |
| 69 | +// |
| 70 | +// "github.com/maxatome/go-testdeep/td" |
| 71 | +// "github.com/maxatome/go-testdeep/helpers/tdsuite" |
| 72 | +// ) |
| 73 | +// |
| 74 | +// type MySuite struct{} |
| 75 | +// |
| 76 | +// func (s MySuite) TestDB(assert, require *td.T) { |
| 77 | +// db, err := initDB() |
| 78 | +// require.CmpNoError(err) |
| 79 | +// assert.CmpNoError(db.Ping()) |
| 80 | +// } |
| 81 | +// |
| 82 | +// func (s MySuite) TestPerson(assert *td.T) { |
| 83 | +// person := Getperson("Bob") |
| 84 | +// assert.Cmp(person, Person{Name: "Bob", Age: 44}) |
| 85 | +// } |
| 86 | +// |
| 87 | +// // TestMySuite is the go test entry point. |
| 88 | +// func TestMySuite(t *testing.T) { |
| 89 | +// tdsuite.Run(t, MySuite{}) |
| 90 | +// } |
| 91 | +// |
| 92 | +// Suite setup and other hooks |
| 93 | +// |
| 94 | +// In most cases, a suite is used for sharing information between |
| 95 | +// tests. The type of the suite can implement several methods that are |
| 96 | +// called before, after and/or between tests. |
| 97 | +// |
| 98 | +// type SuiteDB struct{ |
| 99 | +// DB *sql.DB |
| 100 | +// } |
| 101 | +// |
| 102 | +// // Setup is called once before any test runs. |
| 103 | +// func (s *SuiteDB) Setup(t *td.T) error { |
| 104 | +// db, err := sql.Open(driver, dataSourceName) |
| 105 | +// s.DB = db |
| 106 | +// return err // automatically logged + failure if non-nil |
| 107 | +// } |
| 108 | +// |
| 109 | +// // Destroy is called after all tests are run. |
| 110 | +// // Destroy is not called if Setup returned an error. |
| 111 | +// func (s *SuiteDB) Destroy(t *td.T) error { |
| 112 | +// return s.DB.Close() // automatically logged + failure if non-nil |
| 113 | +// } |
| 114 | +// |
| 115 | +// func (s *SuiteDB) TestPerson(assert, require *td.T) { |
| 116 | +// person, err := GetPerson(s.DB, "Bob") |
| 117 | +// require.CmpNoError(err) |
| 118 | +// assert.Cmp(person, Person{Name: "Bob", Age: 44}) |
| 119 | +// } |
| 120 | +// |
| 121 | +// // TestMySuite is the go test entry point. |
| 122 | +// func TestSuiteDB(t *testing.T) { |
| 123 | +// tdsuite.Run(t, &SuiteDB{}) |
| 124 | +// } |
| 125 | +// |
| 126 | +// See documentation below for other possible hooks: PreTest, PostTest |
| 127 | +// and BetweenTests. |
| 128 | +package tdsuite |
0 commit comments