Testing framework for Go. Allows writing self-documenting tests/specifications, and executes them concurrently and safely isolated. [UNMAINTAINED]

GoSpec

GoSpec is a BDD-style testing framework for the Go programming language. It allows writing self-documenting tests/specs, and executes them in parallel and safely isolated.

NOTICE: GoSpec has not been developed for quite some time, but there is a new testing framework called GoConvey which was inspired by GoSpec and does the same things plus much more.

Source code is available at http://github.com/orfjackal/gospec

For discussion, use the golang-nuts mailing list, at least until GoSpec has so many users that it requires its own mailing list. You may also contact GoSpec's developer, Esko Luontola, by email.

Quick Start

First you must have Go installed on your machine, as instructed in Installing Go.

Install and Update

Download GoSpec using the go get tool:

go get "github.com/orfjackal/gospec/src/gospec"

See go help get for more instructions on using the tool.

See "Version History" for any additional upgrade notes.

Sample Project

Make a copy of the hello-world-template directory to get started. You can run its tests with the go test command. All test files must end with _test.go and all specs must be listed in all_specs_test.go.

Running Specs

You can use the go test command to run GoSpec's specs. The integration with gotest requires a couple of lines of boilerplate: you'll need to write a gotest test method, where you list all your specs and call GoSpec. See all_specs_test.go in the examples directory for an example. Also all your specs must be in files whose names end with _test.go.

See gotest's documentation for instructions on how to use gotest.

GoSpec adds one additional parameter to gotest. Use the -print-all parameter to print a list of all specs: go test -print-all Otherwise only the failing specs are printed. The list of all specs can be useful as documentation.

Writing Specs

The following imports are needed. The first imports the gospec.Context interface and the second is needed for using GoSpec's expectation matchers (Equals, IsTrue, IsNil, Not(), Contains etc.) without having to prefix them with the package name. (In a future GoSpec version the matchers will be moved to their own package.)

import "github.com/orfjackal/gospec/src/gospec"
import . "github.com/orfjackal/gospec/src/gospec"

The specs are written as functions which take gospec.Context as a parameter. You can call the methods of Context to declare expectations and nested specs.

For examples on how to write specs, see the files in the examples directory.

Version History

1.x.x (2012-xx-xx)

  • ...

1.3.9 (2012-03-28)

UPGRADE NOTES: Check your imports - when using the go tool they are different than when using the old hand-written Makefiles.

  • Build using the go tool instead of Makefiles
  • Upgraded to Go 1 (weekly.2012-02-07)

1.3.8 (2011-08-04)

  • Upgraded to Go release.r59 (weekly.2011-07-07)

1.3.7 (2011-07-02)

  • Upgraded to Go release.r58 (weekly.2011-06-23)

1.3.6 (2011-05-04)

  • Upgraded to Go release.r57.1 (weekly.2011-04-27)

1.3.5 (2011-01-21)

  • Upgraded to Go release.2011-01-20

1.3.4 (2010-10-15)

  • Upgraded to Go release.2010-10-13

1.3.3 (2010-10-11)

  • Fixed an occasional off-by-one in exception stack trace line numbers

1.3.2 (2010-10-01)

  • Upgraded to Go release.2010-09-29

1.3.1 (2010-09-11)

  • Issue 754 was fixed in Go release.2010-09-06, so line numbers in GoSpec's stack traces are now correct
  • Fixed an occasional off-by-one in exception stack trace line numbers
  • Upgraded to Go release.2010-09-06

1.3.0 (2010-09-06)

UPGRADE NOTES: If you have written custom matchers, their result parameters' types have changed. Also the error messages are expected to be in a slightly different format. See expectation_syntax_test.go or GoSpec's built-in matchers for examples.

  • New error message format
  • Workaround for a bug in gedit 2.28.0 which caused stack traces to be sometimes non-clickable
  • Improved the stack traces to hide GoSpec internals also for root specs
  • Upgraded to Go release.2010-08-25

1.2.0 (2010-04-29)

UPGRADE NOTES: In your spec suite, replace r.AddSpec("SomeSpec", SomeSpec) with r.AddSpec(SomeSpec).

  • Recover from panics in specs and report their stack traces
  • Retrieve the spec function names using reflection, to avoid some boilerplate in the spec suite
  • Changes to error messages: function names and full file paths are now shown in the stack traces
  • Improved documentation and provided a hello world project template
  • Removed the deprecated c.Then() syntax
  • Upgraded to Go release.2010-04-13

1.1.0 (2010-03-08)

UPGRADE NOTES: In all your specs, replace *gospec.Context with gospec.Context in the spec's parameters. Add import . "gospec" to the imports and change every assertion of the old c.Then(x).Should.Equal(y) syntax to use the new c.Expect(x, Equals, y) syntax.

  • New expectation syntax. The old c.Then() syntax is deprecated and will be removed later.
  • New matchers: IsSame, IsNil, IsTrue, IsFalse, ContainsAll, ContainsAny, ContainsExactly, ContainsInOrder, ContainsInPartialOrder
  • Added Fibonacci numbers example
  • Added instructions about the style of naming and organizing specs
  • Minor changes to the print format of error messages
  • Upgraded to Go release.2010-02-04

1.0.0 (2009-12-30)

  • Initial release

Project Goals

The following are a must, because they enable using specification-style the way I prefer:

  • Unlimited Nesting - The specs can be organized into a nested hierarchy. This makes it possible to apply One Assertion Per Test which isolates the reason for a failure, because the specs are very fine-grained. Many unit testing tools allow only 2 levels of nesting (e.g. JUnit) and a few only 1 level (e.g. gotest), but for specification-style at least 3 levels are needed (e.g. JDave), and once you have 3 levels you might as well implement unlimited levels with the same abstraction.

  • Isolated Execution - The specs must be isolated from the side-effects of their sibling specs. Each spec will see only the side-effects of its parent specs. In effect, the parent specs work similar to the "before" (and "after") test code in many test frameworks, and by default none of the specs can see its siblings (there will be a way to override the default). Without this isolation, it would be harder to write reliable side-effect free specs, which in turn would force the specs to be organized differently than what was desired.

  • No Forced Words - Getting the words right was the starting point for BDD, so it is absurd that almost all of the BDD frameworks force the programmer to use fixed words (describe, it, should, given, when, then etc.) which incline the programmer to write spec names as sentences which begin or end with those words. You should be able to choose yourself the best possible words that fit a situation. GoSpec uses the syntax c.Specify("name", ...) for all levels in the specs, which leads to the word Specify becoming background noise, so that you ignore it and it does not force you to start your sentences with any particular word (using a meaningless word such as "Spec" would also be a good choice, as long as it is easy to pronounce when communicating with others).

The following are nice-to-haves, which make it more pleasant to use the framework:

  • Plain Text Names - You can use any Unicode characters in the spec names, because they are declared as strings. Using only those characters that are allowed in method names would be too limiting and hard to read.

  • Fluent API - The syntax for writing specs should be easily readable. It should be obvious that what an assert does, and which is the expected and which the actual value. Also writing the specs should be easy, requiring as little syntax as possible, but readability has always higher priority than writability.

  • Parallel Execution - Running the specs quickly (i.e. less than 10-20 seconds) is a must for using TDD, so being able to take advantage of all processing power is important, and multiple CPU cores is the only way to go fast in the foreseen future. GoSpec executes the specs using as much parallelism as possible (one goroutine for each leaf spec), so that it would be possible to utilize all available CPU cores (just remember to set GOMAXPROCS).

License

Copyright © 2009-2012 Esko Luontola <http://www.orfjackal.net>
This software is released under the Apache License 2.0.
The license text is at http://www.apache.org/licenses/LICENSE-2.0

Owner
Esko Luontola
Esko Luontola
https://github.com/orfjackal/gospec
Comments
  • can not print when the case success

    can not print when the case success

    about "Use the -print-all parameter to print a list of all specs: go test -print-all Otherwise only the failing specs are printed"

    i find it does not work if i print "go test tester -print-all"

    my example like this: package hello

    import ( "gospec" "testing" "fmt" )

    func TestAllSpecs(t *testing.T) { fmt.Println("testing") r := gospec.NewRunner() r.AddSpec(HelloSpec) gospec.MainGoTest(r, t) }

    anything wrong?

  • Release

    Release

    Hey, I'm using gospec on a pet project of mine and added a few matchers as I went:

    (1) Is("arbitrary message") as a more explicit Satisfies (2) Support for catching panics conveniently, e.g.

     c.Expect(func() { panic(os.EINVAL) }, Panic(Equals), os.EINVAL)
 c.Expect(func() { ... }, RunsNormally)

    Greets,

    boggle

  • GoSpec not building as at 2011-03-14T10:48

    GoSpec not building as at 2011-03-14T10:48

    I am running Go tip (as at 2011-03-14T10:48 this is 7754:cb96564f5925 in my repository). I have a clone of GoSpec and using release (cd174f43fd4a893f3b3310601c7af0f9ad07b53d) I get a compilation error:

    |> make install  
cd gospec && make install  
make[1]: Entering directory `/home/Checkouts/Git/Git/GoSpec/src/gospec'  
6g -o _go_.6 context.go error.go funcname.go location.go main.go matchers.go printer.go print_format.go recover.go results.go runner.go specification.go  
matchers.go:308: multiple-value ch.Recv() in single-value context  
matchers.go:309: ch.Closed undefined (type *reflect.ChanValue has no field or method Closed)  
make[1]: *** [_go_.6] Error 1  
make[1]: Leaving directory `/home/Checkouts/Git/Git/GoSpec/src/gospec'  
make: *** [gospec.install] Error 2
  • Exposing the test context to each spec

    Exposing the test context to each spec

    This PR allows the exposure of the runner's test context to each spec, useful for using gospec in conjunction with gomock as per https://github.com/orfjackal/gospec/issues/4

  • Parallel/Serial Runner options

    Parallel/Serial Runner options

    This is the execution of the idea I expressed in #6.

    • TODO Specs - This is a quick hack, to get work done. Spec'ing this is on mine and rafrombrc's todo list.

    TL:DR;

    type Runner interface {
...
}  

type SerialRunner struct {
...
}  

type ParallelRunner struct {
...
}
  • Make *testing.T object available from inside spec functions

    Make *testing.T object available from inside spec functions

    I've hit a hiccup trying to use gomock w/ gospec b/c creating a gomock controller requires access to the testing object that go usually passes in to tests. Ideally there'd be a way to get access to the lower level testing object from within the spec functions, possibly as a method call on the context object.

Related tags
Testing Frameworks gospec
Immutable transaction isolated sql driver for golang

Single transaction based sql.Driver for GO Package txdb is a single transaction based database sql driver. When the connection is opened, it starts a

Jan 6, 2023
Ritchie CLI is an open-source tool that allows to create, store and share any kind of automation, executing them through command lines, to run operations or start workflows ⚙️ 🖥 💡
 Ritchie CLI is an open-source tool that allows to create, store and share any kind of automation, executing them through command lines, to run operations or start workflows ⚙️ 🖥 💡

Table of contents 1. About 2. Getting Started i. Installation ii. Initialize rit locally iii. Add your first formulas repository iv. Run the Hello Wor

Dec 29, 2022
Extremely flexible golang deep comparison, extends the go testing package and tests HTTP APIs
 Extremely flexible golang deep comparison, extends the go testing package and tests HTTP APIs

go-testdeep Extremely flexible golang deep comparison, extends the go testing package. Latest news Synopsis Description Installation Functions Availab

Dec 22, 2022
A next-generation testing tool. Orion provides a powerful DSL to write and automate your acceptance tests

Orion is born to change the way we implement our acceptance tests. It takes advantage of HCL from Hashicorp t o provide a simple DSL to write the acceptance tests.

Aug 31, 2022
Go testing in the browser. Integrates with `go test`. Write behavioral tests in Go.
 Go testing in the browser. Integrates with `go test`. Write behavioral tests in Go.

GoConvey is awesome Go testing Welcome to GoConvey, a yummy Go testing tool for gophers. Works with go test. Use it in the terminal or browser accordi

Dec 30, 2022
Go testing in the browser. Integrates with `go test`. Write behavioral tests in Go.
 Go testing in the browser. Integrates with `go test`. Write behavioral tests in Go.

GoConvey is awesome Go testing Welcome to GoConvey, a yummy Go testing tool for gophers. Works with go test. Use it in the terminal or browser accordi

Dec 30, 2022
This testing tool surrounds go-ethereum with cannon to catch the blocks of retesteth going into go-ethereum and test cannon with them

Siege This testing tool surrounds go-ethereum with cannon to catch the blocks of retesteth going into go-ethereum and test cannon with them. Usage Sta

Mar 15, 2022
Robust framework for running complex workload scenarios in isolation, using Go; for integration, e2e tests, benchmarks and more! 💪

e2e Go Module providing robust framework for running complex workload scenarios in isolation, using Go and Docker. For integration, e2e tests, benchma

Jan 5, 2023
Fortio load testing library, command line tool, advanced echo server and web UI in go (golang). Allows to specify a set query-per-second load and record latency histograms and other useful stats.
 Fortio load testing library, command line tool, advanced echo server and web UI in go (golang). Allows to specify a set query-per-second load and record latency histograms and other useful stats.

Fortio Fortio (Φορτίο) started as, and is, Istio's load testing tool and now graduated to be its own project. Fortio is also used by, among others, Me

Jan 2, 2023
siusiu (suite-suite harmonics) a suite used to manage the suite, designed to free penetration testing engineers from learning and using various security tools, reducing the time and effort spent by penetration testing engineers on installing tools, remembering how to use tools.
 siusiu (suite-suite harmonics) a suite used to manage the suite, designed to free penetration testing engineers from learning and using various security tools, reducing the time and effort spent by penetration testing engineers on installing tools, remembering how to use tools.

siusiu (suite-suite harmonics) a suite used to manage the suite, designed to free penetration testing engineers from learning and using various security tools, reducing the time and effort spent by penetration testing engineers on installing tools, remembering how to use tools.

Dec 12, 2022
A yaml data-driven testing format together with golang testing library

Specimen Yaml-based data-driven testing Specimen is a yaml data format for data-driven testing. This enforces separation between feature being tested

Nov 24, 2022
Record and replay your HTTP interactions for fast, deterministic and accurate tests

go-vcr go-vcr simplifies testing by recording your HTTP interactions and replaying them in future runs in order to provide fast, deterministic and acc

Dec 25, 2022
A simple and expressive HTTP server mocking library for end-to-end tests in Go.

mockhttp A simple and expressive HTTP server mocking library for end-to-end tests in Go. Installation go get -d github.com/americanas-go/mockhttp Exa

Dec 19, 2021
How we can run unit tests in parallel mode with failpoint injection taking effect and without injection race

This is a simple demo to show how we can run unit tests in parallel mode with failpoint injection taking effect and without injection race. The basic

Oct 31, 2021
Snapshot - snapshot provides a set of utility functions for creating and loading snapshot files for using snapshot tests.

Snapshot - snapshot provides a set of utility functions for creating and loading snapshot files for using snapshot tests.

Jan 27, 2022
Package for comparing Go values in tests

Package for equality of Go values This package is intended to be a more powerful and safer alternative to reflect.DeepEqual for comparing whether two

Dec 29, 2022
Ruby on Rails like test fixtures for Go. Write tests against a real database

testfixtures Warning: this package will wipe the database data before loading the fixtures! It is supposed to be used on a test database. Please, doub

Jan 8, 2023
Automatically update your Go tests

autogold - automatically update your Go tests autogold makes go test -update automatically update your Go tests (golden files and Go values in e.g. fo

Dec 25, 2022
A simple `fs.FS` implementation to be used inside tests.

testfs A simple fs.FS which is contained in a test (using testing.TB's TempDir()) and with a few helper methods. PS: This lib only works on Go 1.16+.

Mar 3, 2022