Documentation
¶
Index ¶
- Constants
- Variables
- func LoadPackage(env *lisp.LEnv) *lisp.LVal
- type Test
- type TestSuite
- func (s *TestSuite) Add(t *Test) error
- func (s *TestSuite) AddBenchmark(b *Test) error
- func (s *TestSuite) Benchmark(i int) *Test
- func (s *TestSuite) Benchmarks() []string
- func (s *TestSuite) CloneNative() any
- func (s *TestSuite) DefineBenchmark(name string, fun *lisp.LVal) error
- func (s *TestSuite) DefineTest(name string, fun *lisp.LVal) error
- func (s *TestSuite) Len() int
- func (s *TestSuite) MacroAssertEqual(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal
- func (s *TestSuite) MacroAssertNil(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal
- func (s *TestSuite) MacroAssertNot(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal
- func (s *TestSuite) MacroAssertNotNil(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal
- func (s *TestSuite) MacroAssertNumEq(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal
- func (s *TestSuite) MacroAssertStringEq(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal
- func (s *TestSuite) MacroBenchmarkSimple(env *lisp.LEnv, args *lisp.LVal) *lisp.LValdeprecated
- func (s *TestSuite) MacroTestLet(env *lisp.LEnv, args *lisp.LVal) *lisp.LValdeprecated
- func (s *TestSuite) MacroTestLetSeq(env *lisp.LEnv, args *lisp.LVal) *lisp.LValdeprecated
- func (s *TestSuite) Macros() []lisp.LBuiltinDef
- func (s *TestSuite) OpBenchmark(env *lisp.LEnv, args *lisp.LVal) *lisp.LValdeprecated
- func (s *TestSuite) OpTest(env *lisp.LEnv, args *lisp.LVal) *lisp.LValdeprecated
- func (s *TestSuite) Ops() []lisp.LBuiltinDefdeprecated
- func (s *TestSuite) Test(i int) *Test
- func (s *TestSuite) Tests() []string
Constants ¶
const DefaultPackageName = "testing"
DefaultPackageName is the package name used by LoadPackage.
const DefaultSuiteSymbol = "test-suite"
Variables ¶
var CoreForms = []string{"test", "benchmark", "test-let", "test-let*", "benchmark-simple"}
CoreForms are the test definition forms. They are core lisp forms (issue #736): a test body is code written in the caller's package, like a defun body, so the forms that wrap one in a lambda belong to package lisp, where they act in the caller's package. LoadPackage re-exports each under package testing as the very same function value, so (use-package 'testing) and testing:test keep working and mean exactly lisp:test.
Functions ¶
Types ¶
type TestSuite ¶
type TestSuite struct {
// contains filtered or unexported fields
}
TestSuite is an ordered set of named tests.
A TestSuite's own bookkeeping is safe for concurrent use, so one suite may be registered into, and read from, any number of environments at once. LoadPackage gives every environment its own suite, so the ordinary path never shares one, but NewTestSuite and EnvTestSuite are exported with no stated scope: an embedder that installs one suite into several runtimes is doing something the API permits. Evaluating a `test` or `benchmark` form writes the suite's maps, and two goroutines writing one Go map is `fatal error: concurrent map writes`, which is thrown by the runtime and cannot be recovered. The mutex below is what keeps that from being reachable. See issue #420.
What this does NOT promise is anything about running a registered test. A Test's Fun is a lambda closed over the environment that defined it, so evaluating it from a different runtime is environment sharing, which is a separate question from whether the suite is a safe container.
Template publication rejects suites, even empty ones. Template-based runners load this package and register their tests separately in each VM.
func EnvTestSuite ¶
EnvTestSuite returns the suite installed in env, or nil if there is none. The suite is returned by pointer and is safe to use while other environments holding the same suite are evaluating.
"None" includes a runtime that never loaded this package at all. The map lookup is nil-checked because Registry.Package returns a nil *Package for an unregistered name and Package.Get dereferences pkg.symbols, so using it unchecked turned "does this runtime have a suite?" -- the question the nil return advertises -- into a nil pointer dereference in the host. See issue #425.
func NewTestSuite ¶
func NewTestSuite() *TestSuite
NewTestSuite returns an empty suite. The result may be installed into any number of environments and used from all of them concurrently.
func (*TestSuite) AddBenchmark ¶ added in v1.13.0
func (*TestSuite) Benchmarks ¶ added in v1.13.0
func (*TestSuite) CloneNative ¶ added in v1.61.0
CloneNative copies registry bookkeeping for within-VM value copies. Test functions are retained by pointer and still belong to their original VM. This does not transfer a populated suite across runtimes: Template rejects suites, and each VM must register and execute its own tests.
func (*TestSuite) DefineBenchmark ¶ added in v1.73.0
DefineBenchmark registers fun, a function of one argument (the iteration count), as the benchmark named name. It is how lisp:benchmark registers into the suite installed as testing:test-suite.
func (*TestSuite) DefineTest ¶ added in v1.73.0
DefineTest registers fun, a function of no arguments, as the test named name. It is how lisp:test registers into the suite installed as testing:test-suite.
func (*TestSuite) MacroAssertEqual ¶
func (*TestSuite) MacroAssertNil ¶
func (*TestSuite) MacroAssertNot ¶
func (*TestSuite) MacroAssertNotNil ¶
func (*TestSuite) MacroAssertNumEq ¶
func (*TestSuite) MacroAssertStringEq ¶
func (*TestSuite) Macros ¶
func (s *TestSuite) Macros() []lisp.LBuiltinDef
Macros returns the testing package's macros for an embedder that assembles the package by hand: lisp's test-let, test-let* and benchmark-simple (see CoreForms), then the assert macros. Register them with AddMacros next to the suite binding and Ops. LoadPackage itself re-exports lisp's forms by value rather than registering them anew.
func (*TestSuite) Ops
deprecated
func (s *TestSuite) Ops() []lisp.LBuiltinDef
Ops returns lisp's test and benchmark special operators, for an embedder that assembles the testing package by hand. They resolve testing:test-suite in the calling environment; embedders must install that binding as well as the ops.
Deprecated: test and benchmark are core lisp forms since issue #736, and every environment with package lisp already has them. Hand assembly needs only the suite binding and the assert macros; LoadPackage re-exports lisp's forms under package testing instead of registering these.
Source Files