or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-dsl.mddecorators.mdextensions.mdindex.mdreporters.mdreporting.mdtable-driven-testing.mdtypes.md
tile.json

types.mddocs/

Core Types

Ginkgo provides comprehensive type definitions for reports, states, locations, events, and enumerations used throughout the framework.

Constants

const VERSION = "2.27.2"
const GINKGO_VERSION = "2.27.2"
const GINKGO_FOCUS_EXIT_CODE = 197

var GINKGO_TIME_FORMAT = "01/02/06 15:04:05.999"

The time format can be customized via the GINKGO_TIME_FORMAT environment variable.

Report Types

These types have been covered in detail in Reporting Documentation and Configuration Documentation, but are summarized here for completeness.

###Report

Complete suite execution report.

type Report struct {
    SuitePath                  string
    SuiteDescription           string
    SuiteLabels                []string
    SuiteSemVerConstraints     []string
    SuiteSucceeded             bool
    SuiteHasProgrammaticFocus  bool
    SpecialSuiteFailureReasons []string
    PreRunStats                PreRunStats
    StartTime                  time.Time
    EndTime                    time.Time
    RunTime                    time.Duration
    SuiteConfig                SuiteConfig
    SpecReports                SpecReports
}

Methods:

func (report Report) Add(other Report) Report

SpecReport

Individual spec execution report.

type SpecReport struct {
    // Hierarchy
    ContainerHierarchyTexts             []string
    ContainerHierarchyLocations         []CodeLocation
    ContainerHierarchyLabels            [][]string
    ContainerHierarchySemVerConstraints [][]string

    // Leaf node information
    LeafNodeType              NodeType
    LeafNodeLocation          CodeLocation
    LeafNodeLabels            []string
    LeafNodeSemVerConstraints []string
    LeafNodeText              string

    // Execution details
    SpecPriority         int
    State                SpecState
    IsSerial             bool
    IsInOrderedContainer bool
    StartTime            time.Time
    EndTime              time.Time
    RunTime              time.Duration
    ParallelProcess      int
    RunningInParallel    bool

    // Failure and retry information
    Failure               Failure
    NumAttempts           int
    MaxFlakeAttempts      int
    MaxMustPassRepeatedly int

    // Output and reporting
    CapturedGinkgoWriterOutput string
    CapturedStdOutErr          string
    ReportEntries              ReportEntries
    ProgressReports            []ProgressReport
    AdditionalFailures         []AdditionalFailure
    SpecEvents                 SpecEvents
}

Methods:

func (report SpecReport) FullText() string
func (report SpecReport) Failed() bool
func (report SpecReport) IsSerial() bool
func (report SpecReport) IsInOrderedContainer() bool
func (report SpecReport) CombinedOutput() string
func (report SpecReport) Labels() []string
func (report SpecReport) SemVerConstraints() []string
func (report SpecReport) MatchesLabelFilter(query string) (bool, error)
func (report SpecReport) MatchesSemVerFilter(version string) (bool, error)
func (report SpecReport) FileName() string
func (report SpecReport) LineNumber() int
func (report SpecReport) FailureMessage() string
func (report SpecReport) FailureLocation() CodeLocation
func (report SpecReport) Timeline() Timeline

SpecReports

Collection of spec reports with filtering and counting methods.

type SpecReports []SpecReport

Methods:

func (reports SpecReports) WithLeafNodeType(nodeTypes NodeType) SpecReports
func (reports SpecReports) WithState(states SpecState) SpecReports
func (reports SpecReports) CountWithState(states SpecState) int
func (reports SpecReports) CountOfFlakedSpecs() int
func (reports SpecReports) CountOfRepeatedSpecs() int

PreRunStats

Statistics before suite execution.

type PreRunStats struct {
    TotalSpecs       int
    SpecsThatWillRun int
}

ConstructionNodeReport

Report available during tree construction phase.

type ConstructionNodeReport struct {
    CodeLocation                        CodeLocation
    ContainerHierarchyTexts             []string
    ContainerHierarchyLocations         []CodeLocation
    ContainerHierarchyLabels            [][]string
    ContainerHierarchySemVerConstraints [][]string
    IsSerial                            bool
    IsInOrderedContainer                bool
}

Methods:

func (report ConstructionNodeReport) FullText() string
func (report ConstructionNodeReport) Labels() []string

Failure Types

Failure

Detailed failure information.

type Failure struct {
    Message        string
    Location       CodeLocation
    TimelineLocation TimelineLocation
    ForwardedPanic string

    // Node context
    FailureNodeContext        FailureNodeContext
    FailureNodeType           NodeType
    FailureNodeLocation       CodeLocation
    FailureNodeContainerIndex int

    // Progress and additional failures
    ProgressReport    ProgressReport
    AdditionalFailure *AdditionalFailure
}

Methods:

func (f Failure) IsZero() bool
func (f Failure) GetTimelineLocation() TimelineLocation

FailureNodeContext

Context describing where a failure occurred.

type FailureNodeContext uint

const (
    FailureNodeContextInvalid FailureNodeContext = iota
    FailureNodeIsLeafNode
    FailureNodeAtTopLevel
    FailureNodeInContainer
)

Methods:

func (fnc FailureNodeContext) String() string
func (fnc *FailureNodeContext) UnmarshalJSON(b []byte) error
func (fnc FailureNodeContext) MarshalJSON() ([]byte, error)

AdditionalFailure

Failures that occur after the initial failure (typically in cleanup).

type AdditionalFailure struct {
    State   SpecState
    Failure Failure
}

Methods:

func (f AdditionalFailure) GetTimelineLocation() TimelineLocation

Location Types

CodeLocation

Source code location with stack trace.

type CodeLocation struct {
    FileName       string
    LineNumber     int
    FullStackTrace string
}

Methods:

func (cl CodeLocation) String() string
func (cl CodeLocation) ContentsOfLine() string

TimelineLocation

Location of an event in the spec's execution timeline.

type TimelineLocation struct {
    Offset int
    Order  int
    Time   time.Time
}

Progress and Event Types

ProgressReport

Progress information for running specs.

type ProgressReport struct {
    // Current execution state
    CurrentNodeType     NodeType
    CurrentNodeText     string
    CurrentNodeLocation CodeLocation
    CurrentStepText     string

    // Context
    ParallelProcess   int
    RunningInParallel bool
    Time              time.Time

    // Hierarchy
    ContainerHierarchyTexts []string
    LeafNodeText            string

    // Goroutine information
    SpecGoroutine      Goroutine
    Goroutines         []Goroutine
    AdditionalReports  []string

    // Output
    CapturedGinkgoWriterOutput string
    CapturedStdOutErr          string
    ReportEntries              ReportEntries
}

Methods:

func (pr ProgressReport) GetTimelineLocation() TimelineLocation

ReportEntry

Custom report entry attached to spec.

type ReportEntry struct {
    Visibility       ReportEntryVisibility
    Location         CodeLocation
    Time             time.Time
    TimelineLocation TimelineLocation
    Name             string
    Value            any
}

Methods:

func (entry ReportEntry) GetRawValue() any
func (entry ReportEntry) StringRepresentation() string
func (entry ReportEntry) GetTimelineLocation() TimelineLocation

ReportEntries

Collection of report entries.

type ReportEntries []ReportEntry

Methods:

func (entries ReportEntries) HasVisibility(
    visibilities ...ReportEntryVisibility,
) ReportEntries
func (entries ReportEntries) WithName(name string) ReportEntry

SpecEvent

Event that occurs during spec execution.

type SpecEvent struct {
    SpecEventType    SpecEventType
    Message          string
    CodeLocation     CodeLocation
    TimelineLocation TimelineLocation
    NodeType         NodeType
    Duration         time.Duration
}

Methods:

func (se SpecEvent) GetTimelineLocation() TimelineLocation
func (se SpecEvent) IsOnlyVisibleAtVeryVerbose() bool

SpecEvents

Collection of spec events.

type SpecEvents []SpecEvent

Methods:

func (events SpecEvents) WithType(eventType SpecEventType) SpecEvents

Timeline

Ordered collection of timeline events.

type TimelineEvent interface {
    GetTimelineLocation() TimelineLocation
}

type Timeline []TimelineEvent

Methods:

func (t Timeline) Len() int
func (t Timeline) Less(i, j int) bool
func (t Timeline) Swap(i, j int)
func (t Timeline) WithoutHiddenReportEntries() Timeline
func (t Timeline) WithoutVeryVerboseSpecEvents() Timeline

Goroutine Information

Goroutine

Information about a goroutine.

type Goroutine struct {
    ID    uint64
    State string
    Stack []byte
}

Enumeration Types

NodeType

Type of Ginkgo node.

type NodeType uint

const (
    NodeTypeInvalid NodeType = iota
    NodeTypeContainer
    NodeTypeIt
    NodeTypeBeforeEach
    NodeTypeJustBeforeEach
    NodeTypeAfterEach
    NodeTypeJustAfterEach
    NodeTypeBeforeAll
    NodeTypeAfterAll
    NodeTypeBeforeSuite
    NodeTypeAfterSuite
    NodeTypeSynchronizedBeforeSuite
    NodeTypeSynchronizedAfterSuite
    NodeTypeReportBeforeEach
    NodeTypeReportAfterEach
    NodeTypeReportBeforeSuite
    NodeTypeReportAfterSuite
    NodeTypeCleanupInvalid
    NodeTypeCleanupAfterEach
    NodeTypeCleanupAfterAll
    NodeTypeCleanupAfterSuite
)

Methods:

func (nt NodeType) String() string
func (nt NodeType) Is(nodeTypes NodeType) bool

Type Collections:

var NodeTypesForContainerAndIt NodeType
var NodeTypesForSuiteLevelNodes NodeType
var NodeTypesAllowedDuringCleanupInterrupt NodeType
var NodeTypesAllowedDuringReportInterrupt NodeType

Example:

if report.LeafNodeType.Is(types.NodeTypeIt) {
    fmt.Println("This is an It node")
}

// Check multiple types
if report.LeafNodeType.Is(types.NodeTypeIt | types.NodeTypeBeforeEach) {
    fmt.Println("This is an It or BeforeEach node")
}

SpecState

State of spec execution.

type SpecState uint

const (
    SpecStateInvalid SpecState = iota
    SpecStatePending
    SpecStateSkipped
    SpecStatePassed
    SpecStateFailed
    SpecStateAborted
    SpecStatePanicked
    SpecStateInterrupted
    SpecStateTimedout
)

Methods:

func (ss SpecState) String() string
func (ss SpecState) Is(states SpecState) bool

State Collections:

var SpecStateFailureStates SpecState

Example:

if report.State.Is(types.SpecStatePassed) {
    fmt.Println("Spec passed")
}

if report.State.Is(types.SpecStateFailureStates) {
    fmt.Println("Spec failed")
}

SpecEventType

Type of spec event.

type SpecEventType uint

const (
    SpecEventInvalid SpecEventType = iota
    SpecEventNodeStart
    SpecEventNodeEnd
    SpecEventSpecRepeat
    SpecEventSpecRetry
    SpecEventByStart
    SpecEventByEnd
    SpecEventProgressReport
)

Methods:

func (set SpecEventType) String() string

ReportEntryVisibility

Visibility level for report entries.

type ReportEntryVisibility uint

const (
    ReportEntryVisibilityAlways ReportEntryVisibility = iota
    ReportEntryVisibilityFailureOrVerbose
    ReportEntryVisibilityNever
)

Methods:

func (rev ReportEntryVisibility) String() string

Stack Trace Management

PruneStack

Removes internal Ginkgo functions from stack traces.

func PruneStack(fullStackTrace string, skip int) string

Parameters:

  • fullStackTrace: Complete stack trace string
  • skip: Number of frames to skip

Example:

stackTrace := debug.Stack()
cleanTrace := types.PruneStack(string(stackTrace), 0)

MarkAsHelper

Marks the calling function as a helper for stack trace purposes.

func MarkAsHelper(optionalSkip ...int)

Label and Filter Types

Labels

Label decorator type.

type Labels []string

Methods:

func (labels Labels) MatchesLabelFilter(filter string) bool

LabelFilter

Compiled label filter function.

type LabelFilter func([]string) bool

ParseLabelFilter

Parses a label filter expression.

func ParseLabelFilter(filter string) (LabelFilter, error)

Example:

filter, err := types.ParseLabelFilter("(integration || unit) && !slow")
if err != nil {
    panic(err)
}

labels := []string{"integration", "api"}
if filter(labels) {
    fmt.Println("Labels match filter")
}

SemVerConstraints

Semantic version constraints decorator.

type SemVerConstraints []string

Methods:

func (constraints SemVerConstraints) MatchesSemVerFilter(filter string) bool

ParseSemVerFilter

Parses a semantic version filter.

func ParseSemVerFilter(filter string) (func([]string) bool, error)

Validation Functions

ValidateAndCleanupLabel

Validates and normalizes a label string.

func ValidateAndCleanupLabel(label string, cl CodeLocation) (string, error)

Example:

cleaned, err := types.ValidateAndCleanupLabel("  Integration Test  ", location)
if err != nil {
    panic(err)
}
// cleaned == "integration test"

MustValidateLabelFilter

Validates a label filter expression.

func MustValidateLabelFilter(filter string) (LabelFilter, error)

Flag and Configuration Generation

GenerateFlagArgs

Generates command-line flag arguments from configuration.

func GenerateFlagArgs(flags GinkgoFlags, bindings any) ([]string, error)

GenerateGinkgoTestRunArgs

Generates arguments for running a Ginkgo test binary.

func GenerateGinkgoTestRunArgs(
    suiteConfig SuiteConfig,
    reporterConfig ReporterConfig,
    goFlagsConfig GoFlagsConfig,
) ([]string, error)

GenerateGoTestCompileArgs

Generates arguments for compiling tests with go test -c.

func GenerateGoTestCompileArgs(
    goFlagsConfig GoFlagsConfig,
    packageToBuild string,
    pathToInvocationPath string,
    preserveSymbols bool,
) ([]string, error)

GenerateGoTestRunArgs

Generates arguments for running non-Ginkgo test binaries.

func GenerateGoTestRunArgs(goFlagsConfig GoFlagsConfig) ([]string, error)

Deprecated Types

For backward compatibility with Ginkgo v1:

// Deprecated aliases for NodeType
var SpecComponentTypeInvalid = NodeTypeInvalid
var SpecComponentTypeContainer = NodeTypeContainer
var SpecComponentTypeIt = NodeTypeIt
var SpecComponentTypeBeforeEach = NodeTypeBeforeEach
// ... etc

These are maintained for compatibility but should not be used in new code.