tap

Documentation

Overview

Package tap implements support for the Test Anything Protocol, a language-agnostic format for outputting the results of tests: https://testanything.org.

Index

• type Directive
• type Document
  • func Parse(input []byte) (*Document, error)
  • func (d *Document) WriteTo(w io.Writer) (int64, error)
• type Object
• type Plan
  • func (p Plan) String() string
  • func (p Plan) Type() Type
• type Producer
  • func NewProducer(w io.Writer) *Producer
  • func (p *Producer) Ok(test bool, description string)
  • func (p *Producer) Plan(count int)
  • func (p *Producer) Skip() *Producer
  • func (p *Producer) Todo() *Producer
  • func (p *Producer) YAML(input []byte)
• type TestLine
  • func (t TestLine) Type() Type
• type Type
• type Version
  • func (v Version) String() string
  • func (v Version) Type() Type

Examples

• Producer (Many_test)
• Producer (Single_test)
• Producer (Skip_todo_alternating)
• Producer.Skip
• Producer.Todo
• Producer.YAML

Types

type Directive

type Directive int

Directive represents a TAP directive (TODO|SKIP|<none>)

const (
	None Directive = iota
	Todo
	Skip
)

Valid Tap directives.

type Document

type Document struct {
	Version   Version
	Plan      Plan
	TestLines []TestLine
}

Document represents a complete TAP document.

func Parse

func Parse(input []byte) (*Document, error)

Parse parses the given input string into a Document. The input is allowed to contain garbage lines; The parser will skip them and parse as much of the input as possible. The only exception is that the first line of input must be a TAP version header of the form "TAP version XXX".

func (*Document) WriteTo

func (d *Document) WriteTo(w io.Writer) (int64, error)

WriteTo writes this document to the given Writer as a formatted TAP output stream.

type Object

type Object interface {
	Type() Type
}

Object is a TAP element such as a test line, plan, version header, or Yaml block.

type Plan

type Plan struct {
	Start int
	End   int
}

Plan represents a TAP plan line.

func (Plan) String

func (p Plan) String() string

func (Plan) Type

func (p Plan) Type() Type

Type implements Object.

type Producer

type Producer struct {
	// contains filtered or unexported fields
}

Producer produces TAP output.

This producer always includes test numbers.

Example (Many_test)

package main

import (
	"os"

	"go.fuchsia.dev/fuchsia/tools/testing/tap"
)

func main() {
	p := tap.NewProducer(os.Stdout)
	p.Plan(4)
	p.Ok(true, "- this test passed")
	p.Ok(false, "")
}

Output:

TAP version 13
1..4
ok 1 - this test passed
not ok 2

Example (Single_test)

package main

import (
	"os"

	"go.fuchsia.dev/fuchsia/tools/testing/tap"
)

func main() {
	p := tap.NewProducer(os.Stdout)
	p.Plan(1)
	p.Ok(true, "- this test passed")
}

Output:

TAP version 13
1..1
ok 1 - this test passed

Example (Skip_todo_alternating)

package main

import (
	"os"

	"go.fuchsia.dev/fuchsia/tools/testing/tap"
)

func main() {
	p := tap.NewProducer(os.Stdout)
	p.Plan(4)
	p.Skip().Ok(true, "implement this test")
	p.Todo().Ok(false, "oh no!")
	p.Skip().Ok(false, "skipped another")
	p.Todo().Skip().Todo().Ok(true, "please don't write code like this")
}

Output:

TAP version 13
1..4
ok 1 # SKIP implement this test
not ok 2 # TODO oh no!
not ok 3 # SKIP skipped another
ok 4 # TODO please don't write code like this

func NewProducer

func NewProducer(w io.Writer) *Producer

NewProducer creates a new Producer that writes to the given Writer.

func (*Producer) Ok

func (p *Producer) Ok(test bool, description string)

Ok outputs a test line containing the given description and starting with either "ok" if test is true or "not ok" if false. If this producer was created using Todo or Skip, then the corresponding directive is also printed, and the description is used as the explanation of that directive.

func (*Producer) Plan

func (p *Producer) Plan(count int)

Plan outputs the TAP plan line: 1..count. If count <= 0, nothing is printed

func (*Producer) Skip

func (p *Producer) Skip() *Producer

Skip returns a new Producer that prints SKIP directives.

Example

package main

import (
	"os"

	"go.fuchsia.dev/fuchsia/tools/testing/tap"
)

func main() {
	p := tap.NewProducer(os.Stdout)
	p.Plan(1)
	p.Skip().Ok(true, "implement this test")
}

Output:

TAP version 13
1..1
ok 1 # SKIP implement this test

func (*Producer) Todo

func (p *Producer) Todo() *Producer

Todo returns a new Producer that prints TODO directives.

Example

package main

import (
	"os"

	"go.fuchsia.dev/fuchsia/tools/testing/tap"
)

func main() {
	p := tap.NewProducer(os.Stdout)
	p.Plan(1)
	p.Todo().Ok(true, "implement this test")
}

Output:

TAP version 13
1..1
ok 1 # TODO implement this test

func (*Producer) YAML

func (p *Producer) YAML(input []byte)

YAML produces a YAML block from the given input. This will indent the input data. The caller should not do this themselves.

Example

p := tap.NewProducer(os.Stdout)
p.Plan(1)
p.Ok(true, "passed")
bytes, err := yaml.Marshal(struct {
	Name  string    `yaml:"name"`
	Start time.Time `yaml:"start_time"`
	End   time.Time `yaml:"end_time"`
}{
	Name:  "foo_test",
	Start: time.Date(2019, 1, 1, 12, 30, 0, 0, time.UTC),
	End:   time.Date(2019, 1, 1, 12, 40, 0, 0, time.UTC),
})
if err != nil {
	panic(err)
}
p.YAML(bytes)

Output:

TAP version 13
1..1
ok 1 passed
 ---
 name: foo_test
 start_time: 2019-01-01T12:30:00Z
 end_time: 2019-01-01T12:40:00Z
 ...

type TestLine

type TestLine struct {
	Ok          bool
	Count       int
	Description string
	Directive   Directive
	Explanation string
	Diagnostic  string
	YAML        string
}

TestLine represents a TAP test line beginning with "ok" or "not ok".

func (TestLine) Type

func (t TestLine) Type() Type

Type implements Object.

type Type

type Type int

Type describes the type of TAP Object returned by the Parser.

const (
	// VersionType is the type returned by a Version Object.
	VersionType Type = iota

	// PlanType is the type returned by a Plan Object.
	PlanType

	// TestLineType is the type returned by a TestLine.
	TestLineType
)

type Version

type Version int

Version represents a TAP version line.

func (Version) String

func (v Version) String() string

func (Version) Type

func (v Version) Type() Type

Type implements Object.