doc.go 8.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218
  1. // Package convey contains all of the public-facing entry points to this project.
  2. // This means that it should never be required of the user to import any other
  3. // packages from this project as they serve internal purposes.
  4. package convey
  5. import "github.com/smartystreets/goconvey/convey/reporting"
  6. ////////////////////////////////// suite //////////////////////////////////
  7. // C is the Convey context which you can optionally obtain in your action
  8. // by calling Convey like:
  9. //
  10. // Convey(..., func(c C) {
  11. // ...
  12. // })
  13. //
  14. // See the documentation on Convey for more details.
  15. //
  16. // All methods in this context behave identically to the global functions of the
  17. // same name in this package.
  18. type C interface {
  19. Convey(items ...interface{})
  20. SkipConvey(items ...interface{})
  21. FocusConvey(items ...interface{})
  22. So(actual interface{}, assert assertion, expected ...interface{})
  23. SkipSo(stuff ...interface{})
  24. Reset(action func())
  25. Println(items ...interface{}) (int, error)
  26. Print(items ...interface{}) (int, error)
  27. Printf(format string, items ...interface{}) (int, error)
  28. }
  29. // Convey is the method intended for use when declaring the scopes of
  30. // a specification. Each scope has a description and a func() which may contain
  31. // other calls to Convey(), Reset() or Should-style assertions. Convey calls can
  32. // be nested as far as you see fit.
  33. //
  34. // IMPORTANT NOTE: The top-level Convey() within a Test method
  35. // must conform to the following signature:
  36. //
  37. // Convey(description string, t *testing.T, action func())
  38. //
  39. // All other calls should look like this (no need to pass in *testing.T):
  40. //
  41. // Convey(description string, action func())
  42. //
  43. // Don't worry, goconvey will panic if you get it wrong so you can fix it.
  44. //
  45. // Additionally, you may explicitly obtain access to the Convey context by doing:
  46. //
  47. // Convey(description string, action func(c C))
  48. //
  49. // You may need to do this if you want to pass the context through to a
  50. // goroutine, or to close over the context in a handler to a library which
  51. // calls your handler in a goroutine (httptest comes to mind).
  52. //
  53. // All Convey()-blocks also accept an optional parameter of FailureMode which sets
  54. // how goconvey should treat failures for So()-assertions in the block and
  55. // nested blocks. See the constants in this file for the available options.
  56. //
  57. // By default it will inherit from its parent block and the top-level blocks
  58. // default to the FailureHalts setting.
  59. //
  60. // This parameter is inserted before the block itself:
  61. //
  62. // Convey(description string, t *testing.T, mode FailureMode, action func())
  63. // Convey(description string, mode FailureMode, action func())
  64. //
  65. // See the examples package for, well, examples.
  66. func Convey(items ...interface{}) {
  67. if ctx := getCurrentContext(); ctx == nil {
  68. rootConvey(items...)
  69. } else {
  70. ctx.Convey(items...)
  71. }
  72. }
  73. // SkipConvey is analagous to Convey except that the scope is not executed
  74. // (which means that child scopes defined within this scope are not run either).
  75. // The reporter will be notified that this step was skipped.
  76. func SkipConvey(items ...interface{}) {
  77. Convey(append(items, skipConvey)...)
  78. }
  79. // FocusConvey is has the inverse effect of SkipConvey. If the top-level
  80. // Convey is changed to `FocusConvey`, only nested scopes that are defined
  81. // with FocusConvey will be run. The rest will be ignored completely. This
  82. // is handy when debugging a large suite that runs a misbehaving function
  83. // repeatedly as you can disable all but one of that function
  84. // without swaths of `SkipConvey` calls, just a targeted chain of calls
  85. // to FocusConvey.
  86. func FocusConvey(items ...interface{}) {
  87. Convey(append(items, focusConvey)...)
  88. }
  89. // Reset registers a cleanup function to be run after each Convey()
  90. // in the same scope. See the examples package for a simple use case.
  91. func Reset(action func()) {
  92. mustGetCurrentContext().Reset(action)
  93. }
  94. /////////////////////////////////// Assertions ///////////////////////////////////
  95. // assertion is an alias for a function with a signature that the convey.So()
  96. // method can handle. Any future or custom assertions should conform to this
  97. // method signature. The return value should be an empty string if the assertion
  98. // passes and a well-formed failure message if not.
  99. type assertion func(actual interface{}, expected ...interface{}) string
  100. const assertionSuccess = ""
  101. // So is the means by which assertions are made against the system under test.
  102. // The majority of exported names in the assertions package begin with the word
  103. // 'Should' and describe how the first argument (actual) should compare with any
  104. // of the final (expected) arguments. How many final arguments are accepted
  105. // depends on the particular assertion that is passed in as the assert argument.
  106. // See the examples package for use cases and the assertions package for
  107. // documentation on specific assertion methods. A failing assertion will
  108. // cause t.Fail() to be invoked--you should never call this method (or other
  109. // failure-inducing methods) in your test code. Leave that to GoConvey.
  110. func So(actual interface{}, assert assertion, expected ...interface{}) {
  111. mustGetCurrentContext().So(actual, assert, expected...)
  112. }
  113. // SkipSo is analagous to So except that the assertion that would have been passed
  114. // to So is not executed and the reporter is notified that the assertion was skipped.
  115. func SkipSo(stuff ...interface{}) {
  116. mustGetCurrentContext().SkipSo()
  117. }
  118. // FailureMode is a type which determines how the So() blocks should fail
  119. // if their assertion fails. See constants further down for acceptable values
  120. type FailureMode string
  121. const (
  122. // FailureContinues is a failure mode which prevents failing
  123. // So()-assertions from halting Convey-block execution, instead
  124. // allowing the test to continue past failing So()-assertions.
  125. FailureContinues FailureMode = "continue"
  126. // FailureHalts is the default setting for a top-level Convey()-block
  127. // and will cause all failing So()-assertions to halt further execution
  128. // in that test-arm and continue on to the next arm.
  129. FailureHalts FailureMode = "halt"
  130. // FailureInherits is the default setting for failure-mode, it will
  131. // default to the failure-mode of the parent block. You should never
  132. // need to specify this mode in your tests..
  133. FailureInherits FailureMode = "inherits"
  134. )
  135. func (f FailureMode) combine(other FailureMode) FailureMode {
  136. if other == FailureInherits {
  137. return f
  138. }
  139. return other
  140. }
  141. var defaultFailureMode FailureMode = FailureHalts
  142. // SetDefaultFailureMode allows you to specify the default failure mode
  143. // for all Convey blocks. It is meant to be used in an init function to
  144. // allow the default mode to be changdd across all tests for an entire packgae
  145. // but it can be used anywhere.
  146. func SetDefaultFailureMode(mode FailureMode) {
  147. if mode == FailureContinues || mode == FailureHalts {
  148. defaultFailureMode = mode
  149. } else {
  150. panic("You may only use the constants named 'FailureContinues' and 'FailureHalts' as default failure modes.")
  151. }
  152. }
  153. //////////////////////////////////// Print functions ////////////////////////////////////
  154. // Print is analogous to fmt.Print (and it even calls fmt.Print). It ensures that
  155. // output is aligned with the corresponding scopes in the web UI.
  156. func Print(items ...interface{}) (written int, err error) {
  157. return mustGetCurrentContext().Print(items...)
  158. }
  159. // Print is analogous to fmt.Println (and it even calls fmt.Println). It ensures that
  160. // output is aligned with the corresponding scopes in the web UI.
  161. func Println(items ...interface{}) (written int, err error) {
  162. return mustGetCurrentContext().Println(items...)
  163. }
  164. // Print is analogous to fmt.Printf (and it even calls fmt.Printf). It ensures that
  165. // output is aligned with the corresponding scopes in the web UI.
  166. func Printf(format string, items ...interface{}) (written int, err error) {
  167. return mustGetCurrentContext().Printf(format, items...)
  168. }
  169. ///////////////////////////////////////////////////////////////////////////////
  170. // SuppressConsoleStatistics prevents automatic printing of console statistics.
  171. // Calling PrintConsoleStatistics explicitly will force printing of statistics.
  172. func SuppressConsoleStatistics() {
  173. reporting.SuppressConsoleStatistics()
  174. }
  175. // ConsoleStatistics may be called at any time to print assertion statistics.
  176. // Generally, the best place to do this would be in a TestMain function,
  177. // after all tests have been run. Something like this:
  178. //
  179. // func TestMain(m *testing.M) {
  180. // convey.SuppressConsoleStatistics()
  181. // result := m.Run()
  182. // convey.PrintConsoleStatistics()
  183. // os.Exit(result)
  184. // }
  185. //
  186. func PrintConsoleStatistics() {
  187. reporting.PrintConsoleStatistics()
  188. }