or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration.md core-dsl.md decorators.md extensions.md index.md reporters.md reporting.md table-driven-testing.md types.md

tile.json

Ginkgo v2

Ginkgo is a mature testing framework for Go designed to help you write expressive behavioral tests. It provides a rich Domain-Specific Language (DSL) for organizing specs with containers, setup/teardown hooks, table-driven tests, parallel execution, and comprehensive reporting. Ginkgo builds on top of Go's testing foundation and is complemented by the Gomega matcher library.

Package Information

Package Name: github.com/onsi/ginkgo/v2
Package Type: golang
Language: Go
Version: 2.27.2
Installation: go get github.com/onsi/ginkgo/v2

Core Imports

import (
    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"  // Recommended matcher library
)

Non-dot import (to avoid naming conflicts):

import (
    "github.com/onsi/ginkgo/v2"
    "github.com/onsi/ginkgo/v2/types"
)

Specific sub-packages:

import (
    "github.com/onsi/ginkgo/v2/dsl/core"
    "github.com/onsi/ginkgo/v2/dsl/decorators"
    "github.com/onsi/ginkgo/v2/dsl/table"
    "github.com/onsi/ginkgo/v2/dsl/reporting"
    "github.com/onsi/ginkgo/v2/reporters"
    "github.com/onsi/ginkgo/v2/types"
    "github.com/onsi/ginkgo/v2/formatter"
    "github.com/onsi/ginkgo/v2/extensions/globals"
)

Basic Usage

package books_test

import (
    "testing"
    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
)

func TestBooks(t *testing.T) {
    RegisterFailHandler(Fail)
    RunSpecs(t, "Books Suite")
}

var _ = Describe("Book", func() {
    var book *Book

    BeforeEach(func() {
        book = &Book{
            Title:  "Les Miserables",
            Author: "Victor Hugo",
            Pages:  1488,
        }
    })

    When("the category is set", func() {
        BeforeEach(func() {
            book.Category = "Fiction"
        })

        It("returns the category", func() {
            Expect(book.Category).To(Equal("Fiction"))
        })
    })

    It("can be loaded from JSON", func() {
        data := `{"title":"Les Miserables","author":"Victor Hugo"}`
        err := book.LoadFromJSON(data)
        Expect(err).ToNot(HaveOccurred())
        Expect(book.Title).To(Equal("Les Miserables"))
    })
})

Architecture

Ginkgo organizes tests using a hierarchical structure:

Container Nodes: Describe, Context, When organize specs into logical groups
Subject Nodes: It and Specify define individual test cases
Setup Nodes: BeforeEach, JustBeforeEach, AfterEach, JustAfterEach for test setup/teardown
Suite Nodes: BeforeSuite, AfterSuite for suite-level setup/teardown
Reporting Nodes: Track and report on test execution
Decorators: Modify behavior of nodes (labels, timeouts, retries, etc.)

Capabilities

Core DSL

The main testing DSL with container nodes, subject nodes, and lifecycle hooks.

// Container nodes for organizing specs
func Describe(text string, args ...any) bool
func Context(text string, args ...any) bool
func When(text string, args ...any) bool

// Subject nodes for individual tests
func It(text string, args ...any) bool
func Specify(text string, args ...any) bool

// Setup and teardown hooks
func BeforeEach(args ...any) bool
func AfterEach(args ...any) bool
func JustBeforeEach(args ...any) bool
func JustAfterEach(args ...any) bool

// Suite lifecycle
func BeforeSuite(body any, args ...any) bool
func AfterSuite(body any, args ...any) bool
func RunSpecs(t GinkgoTestingT, description string, args ...any) bool

Core DSL Documentation

Decorators

Modify node behavior with labels, timeouts, retries, ordering, and more.

// Labels and filtering
func Label(labels ...string) Labels
func SemVerConstraint(constraints ...string) SemVerConstraints

// Retry and stability
func FlakeAttempts(attempts uint) FlakeAttempts
func MustPassRepeatedly(count uint) MustPassRepeatedly

// Timeouts and interrupts
func NodeTimeout(timeout time.Duration) NodeTimeout
func SpecTimeout(timeout time.Duration) SpecTimeout
func GracePeriod(gracePeriod time.Duration) GracePeriod

// Execution control
const Ordered           // Run specs sequentially
const Serial            // Never run in parallel
const ContinueOnFailure // Continue after failures in Ordered containers
const Focus             // Focus on specific specs
const Pending           // Mark specs as pending

// Progress reporting
func PollProgressAfter(interval time.Duration) PollProgressAfter
func PollProgressInterval(interval time.Duration) PollProgressInterval
const SuppressProgressReporting

// Advanced
func Offset(offset int) Offset
func SpecPriority(priority int) SpecPriority

Decorators Documentation

Table-Driven Testing

Create parameterized tests with table entries.

// Table creation
func DescribeTable(description string, args ...any) bool
func DescribeTableSubtree(description string, args ...any) bool

// Entry creation
func Entry(description any, args ...any) TableEntry

Table-Driven Testing Documentation

Reporting

Generate reports, add report entries, and access current spec information.

// Report entry management
func AddReportEntry(name string, args ...any)

// Current spec information
func CurrentSpecReport() SpecReport
func CurrentTreeConstructionNodeReport() ConstructionNodeReport

// Reporting lifecycle hooks
func ReportBeforeEach(body any, args ...any) bool
func ReportAfterEach(body any, args ...any) bool
func ReportBeforeSuite(body any, args ...any) bool
func ReportAfterSuite(text string, body any, args ...any) bool

// Report visibility constants
const ReportEntryVisibilityAlways
const ReportEntryVisibilityFailureOrVerbose
const ReportEntryVisibilityNever

Reporting Documentation

Configuration

Suite configuration, reporter settings, and Go flags.

// Configuration structures
type SuiteConfig struct {
    RandomSeed            int64
    RandomizeAllSpecs     bool
    FocusStrings          []string
    SkipStrings           []string
    LabelFilter           string
    FailOnPending         bool
    FailFast              bool
    FlakeAttempts         int
    Timeout               time.Duration
    ParallelProcess       int
    ParallelTotal         int
    // ... additional fields
}

type ReporterConfig struct {
    NoColor        bool
    Verbose        bool
    VeryVerbose    bool
    FullTrace      bool
    JSONReport     string
    JUnitReport    string
    // ... additional fields
}

// Configuration access
func GinkgoConfiguration() (SuiteConfig, ReporterConfig)
func GinkgoRandomSeed() int64
func GinkgoParallelProcess() int
func GinkgoLabelFilter() string

Configuration Documentation

Core Types

Type definitions for reports, states, locations, and events.

// Report types
type Report struct {
    SuiteDescription string
    SuitePath        string
    SuiteSucceeded   bool
    StartTime        time.Time
    EndTime          time.Time
    RunTime          time.Duration
    SpecReports      SpecReports
    // ... additional fields
}

type SpecReport struct {
    ContainerHierarchyTexts []string
    LeafNodeType            NodeType
    LeafNodeText            string
    State                   SpecState
    RunTime                 time.Duration
    Failure                 Failure
    // ... additional fields
}

// Enumeration types
type NodeType uint
type SpecState uint
type SpecEventType uint
type ReportEntryVisibility uint

// Code location and debugging
type CodeLocation struct {
    FileName       string
    LineNumber     int
    FullStackTrace string
}

Types Documentation

Built-in Reporters

Generate reports in various formats (JSON, JUnit, Teamcity).

// Report generation
func GenerateJSONReport(report types.Report, destination string) error
func GenerateJUnitReport(report types.Report, dst string) error
func GenerateTeamcityReport(report types.Report, dst string) error

// Report merging
func MergeAndCleanupJSONReports(sources []string, destination string) ([]string, error)
func MergeAndCleanupJUnitReports(sources []string, dst string) ([]string, error)

// Custom reporters
type Reporter interface {
    SuiteWillBegin(report types.Report)
    WillRun(report types.SpecReport)
    DidRun(report types.SpecReport)
    SuiteDidEnd(report types.Report)
    // ... additional methods
}

Reporters Documentation

Failure Handling

Control test failures and interrupts.

// Failure functions
func Fail(message string, callerSkip ...int)
func AbortSuite(message string, callerSkip ...int)
func Skip(message string, callerSkip ...int)
func GinkgoRecover()

// Defer cleanup
func DeferCleanup(args ...any)

Documentation and Output

Document spec steps and control output.

// Documentation
func By(text string, callback ...func())

// Output management
var GinkgoWriter GinkgoWriterInterface
var GinkgoLogr logr.Logger

func GinkgoT(optionalOffset ...int) FullGinkgoTInterface
func GinkgoTB(optionalOffset ...int) *GinkgoTBWrapper
func PauseOutputInterception()
func ResumeOutputInterception()

// Progress reporting
func AttachProgressReporter(reporter func() string) func()

Utilities and Helpers

Helper functions and global state management.

// Helper marking
func GinkgoHelper()

// Preview specs without running
func PreviewSpecs(description string, args ...any) Report

Extensions Documentation

Version Information

const GINKGO_VERSION = "2.27.2"