Go Testing reference

These are the main building blocks you can use to integrate Go tests with Allure by using the github.com/allure-framework/allure-go/commons/gotest package. Import it under the allure alias:

import allure "github.com/allure-framework/allure-go/commons/gotest"

Test functions

allure.Test

allure.Test(t, name, body, options...) reports one named Allure test result. It creates a Go subtest via t.Run(name, ...), so failures, skips, logs, cleanups, steps, and attachments stay attached to the correct result, and standard go test -run filtering keeps working:

func TestLogin(t *testing.T) {
    allure.Test(t, "logs in with valid credentials", func(a *allure.Context) {
        // ...
    }, allure.WithOwner("qa-team"))
}

One Go test function may contain multiple allure.Test calls; each produces a separate Allure result.

allure.Wrap

allure.Wrap(t, body, options...) reports the current Go test as exactly one Allure result. It uses t.Name() as the result name and does not create a child subtest:

func TestLogin(t *testing.T) {
    allure.Wrap(t, func(a *allure.Context) {
        // ...
    })
}

allure.Wrap may be called only once per test, and cannot be combined with allure.Test on the same *testing.T — use allure.Test when one Go test should produce multiple named Allure results.

allure.Step

The package-level generic allure.Step(a, name, body) reports a step whose body returns a typed value:

session := allure.Step(a, "create session", func(a *allure.Context) string {
    return "session-1"
})

For steps without a return value, use the a.Step method instead.

Statuses

The reported test status follows the outcome of the Go test: passed, failed (after t.Error, t.Fatal, or a failed assertion), or skipped (after t.Skip). A panic in the test body is reported as broken with the panic message and stack trace, and is then re-raised for go test to handle as usual.

Static options

Options are passed as trailing arguments to allure.Test and allure.Wrap. They apply before the test body runs, which makes them visible to test plan filtering. Prefer options for metadata known up front; use the runtime context API for metadata discovered during execution.

Labels

• allure.WithLabel(name, value)
• allure.WithLabels(labels...) — takes model.Label values
• allure.WithTag(value)
• allure.WithSeverity(value)
• allure.WithOwner(value)
• allure.WithAllureID(id)

Hierarchies

• allure.WithEpic(value)
• allure.WithFeature(value)
• allure.WithStory(value)
• allure.WithParentSuite(value)
• allure.WithSuite(value)
• allure.WithSubSuite(value)
• allure.WithPackage(value)

Setting any of the parentSuite, suite, or subSuite labels disables the automatic suite hierarchy derived from the test file path.

Links

• allure.WithLink(url, name, linkType)
• allure.WithLinks(links...) — takes model.Link values
• allure.WithIssue(name, url)
• allure.WithTMS(name, url)

Parameters

• allure.WithParameter(name, value)
• allure.WithParameterOptions(name, value, options)

allure.ParameterOptions controls display and history behavior:

allure.WithParameterOptions("password", "qwerty", allure.ParameterOptions{
    Excluded: true,                      // do not affect the history ID
    Mode:     model.ParameterModeMasked, // model.ParameterModeDefault, Masked, or Hidden
})

Descriptions and identity

• allure.WithDescription(markdown)
• allure.WithDescriptionHTML(html)
• allure.WithDisplayName(name) — overrides the name shown in the report
• allure.WithTestCaseName(name) — sets the logical test case name
• allure.WithTestCaseID(id) — overrides the computed test case ID
• allure.WithHistoryID(id) — overrides the computed history ID

Test plan

• allure.WithTestPlan(plan) — uses an already loaded *testplan.Plan instead of ALLURE_TESTPLAN_PATH
• allure.WithTestPlanPath(path) — loads a test plan from a specific file

Advanced

• allure.WithWriter(writer) — routes this test's artifacts through a custom writer.Writer, for example an in-memory writer in adapter tests
• allure.WithClock(now) — replaces the millisecond timestamp source
• allure.WithIDGenerator(newID) — replaces the UUID generator

Runtime context API

The test body receives an *allure.Context (named a by convention) that combines access to the underlying *testing.T with Allure reporting methods.

Bridge to testing.T

• a.T() — the underlying *testing.T
• a.Name() — the current Go test name
• a.Helper() — marks the caller as a test helper
• a.Errorf(format, args...) — fails the test and records the message as Allure status details
• a.Fatal(args...), a.Fatalf(format, args...) — fail the test with status details and stop execution
• a.FailNow() — fails and stops without a message
• a.Context() — the context.Context carrying the active Allure runtime state; pass it to helper libraries such as httpexchange

Failure messages reported through a.Errorf, a.Fatal, and a.Fatalf appear as the result's status details in the report. Calls made directly on a.T() still fail the test correctly but do not record status details.

Steps

• a.Step(name, body) — reports body as a step; steps nest naturally
• a.StepDisplayName(name) — renames the active step
• a.StepParameter(name, value) — adds a parameter to the active step
• a.StepDescription(markdown), a.StepDescriptionHTML(html) — set the active step description

a.Step("submit credentials", func(a *allure.Context) {
    a.StepParameter("endpoint", "/login")
    a.Step("wait for redirect", func(a *allure.Context) {
        // ...
    })
})

Metadata

• a.Label(name, value)
• a.Link(url, name, linkType)
• a.Parameter(name, value)
• a.Description(markdown), a.DescriptionHTML(html)
• a.DisplayName(name)
• a.TestCaseName(name), a.TestCaseID(id), a.HistoryID(id)

These are the runtime counterparts of the static options. Note that runtime metadata is applied after test plan filtering, so an Allure ID needed for selection must be set with allure.WithAllureID.

Attachments

• a.Attachment(name, content, contentType) — attaches in-memory bytes
• a.AttachmentPath(name, path, contentType) — attaches an existing file

Attachments are added to the active step, or to the test itself when no step is active. For in-memory attachments, the stored file's extension is derived from the content type (for example, application/json produces a .json file); file attachments keep the extension of the source file.

Run-level diagnostics

• a.GlobalAttachment(name, content, contentType), a.GlobalAttachmentPath(name, path, contentType) — attach evidence to the test run as a whole rather than to one test, for example a service log collected once per run
• a.GlobalError(details) — records a run-level error, taking a model.StatusDetails value

Testify assertions

The separate module github.com/allure-framework/allure-go/testify provides drop-in replacements for testify's assert and require packages that report each assertion call as an Allure step:

go get github.com/allure-framework/allure-go/testify/assert
go get github.com/allure-framework/allure-go/testify/require

 import (
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
+	"github.com/allure-framework/allure-go/testify/assert"
+	"github.com/allure-framework/allure-go/testify/require"
 )

The proxy packages mirror the upstream testify API, including assert.New(...) / require.New(...) assertion objects. What is reported depends on the first argument of each call:

• passing the Allure context a reports the assertion as an Allure step; failed assertions add status details, including the expected and actual values,
• passing t or a.T() keeps plain testify behavior without step reporting.

allure.Test(t, "loads profile", func(a *allure.Context) {
    assert.Equal(a, "alice", profile.Name) // reported as a step
    require.NoError(a, err)                // reported as a step
    assert.Equal(t, "alice", profile.Name) // plain testify, no step
})

Test context types from other integrations can opt into step reporting by satisfying testify's TestingT interface and the commons.ContextProvider interface (a Context() context.Context method).

HTTP exchange attachments

The github.com/allure-framework/allure-go/commons/httpexchange package produces attachments in the Allure HTTP Exchange format (application/vnd.allure.http+json, stored with the .httpexchange extension), which report viewers render as structured request/response evidence.

Capture helpers

• httpexchange.NewTransport(ctx, base, options...) — wraps an http.RoundTripper; every request sent through the client is attached to the active test or step
• httpexchange.NewHandler(ctx, next, options...) — wraps an http.Handler; every request received by the server is attached, which suits httptest.Server fakes

client := &http.Client{
    Transport: httpexchange.NewTransport(a.Context(), http.DefaultTransport),
}

server := httptest.NewServer(httpexchange.NewHandler(a.Context(), handler))

Both take the Allure context from a.Context() and safely do nothing when no Allure test is active.

Building exchanges manually

When the body bytes are already captured by your own code:

• httpexchange.NewExchange(req, requestBody, resp, responseBody, options...) — builds a complete exchange from *http.Request and *http.Response values
• httpexchange.FromRequest(req, body, options...), httpexchange.FromResponse(resp, body, options...) — build the request or response portion separately
• httpexchange.Attach(ctx, name, exchange) — attaches an exchange to the active test or step
• httpexchange.Marshal(exchange) — serializes an exchange to JSON without attaching it

Options

• httpexchange.WithBodyLimit(limit) — limits captured body values, 64 KiB by default; a negative limit captures everything, zero records body metadata without content
• httpexchange.WithRedactedHeaders(names...) — adds header names to redact; Authorization, Proxy-Authorization, Cookie, Set-Cookie, X-Api-Key, and X-Auth-Token are redacted by default
• httpexchange.WithRedactedQueryParameters(names...) — adds query parameters to redact; common token-like names such as token, password, api_key, and client_secret are redacted by default
• httpexchange.WithRedactedFormFields(names...) — adds URL-encoded form fields to redact; the same token-like defaults apply
• httpexchange.WithRedactedCookies(names...) — adds cookie names to redact; by default, all cookie values are redacted
• httpexchange.WithAttachmentName(name) / httpexchange.WithAttachmentNamer(func) — set a fixed or computed attachment name; the default is HTTP <method> <path-and-query>, for example HTTP GET /orders?page=2
• httpexchange.WithStartStop(start, stop) — sets explicit exchange timestamps in Unix epoch milliseconds
• httpexchange.WithError(err) / httpexchange.WithErrorDetails(name, message, stack) — record a transport-level error on the exchange

Redacted values are replaced with the __ALLURE_REDACTED__ sentinel, which report viewers display as a redaction marker.

Building a custom integration with commons

Use the github.com/allure-framework/allure-go/commons module when you need to integrate Allure with a custom test harness, or to write a helper library that reports into whatever Allure test is currently active.

Helper libraries only need the facade functions, which mirror the runtime context API but take a context.Context and return errors. All of them safely do nothing when no Allure runtime is bound to the context:

import commons "github.com/allure-framework/allure-go/commons"

func instrument(ctx context.Context) error {
    if err := commons.Owner(ctx, "qa-team"); err != nil {
        return err
    }
    return commons.Step(ctx, "call login endpoint", func(ctx context.Context) error {
        return commons.Attachment(ctx, "payload", []byte(`{"ok":true}`), commons.AttachmentOptions{
            ContentType: "application/json",
        })
    })
}

The main facade groups are:

• labels and links: Label, Labels, Tag, Severity, Owner, Epic, Feature, Story, ParentSuite, Suite, SubSuite, Package, AllureID, Link, Links, Issue, TMS
• test metadata: Parameter, ParameterWithOptions, Description, DescriptionHTML, DisplayName, TestCaseName, TestCaseID, HistoryID
• steps: Step, StepValue (returns a typed value), StartStep, StopStep, LogStep (records an already completed step), StepDisplayName, StepParameter, StepParameterWithOptions, StepDescription, StepDescriptionHTML
• attachments and diagnostics: Attachment, AttachmentPath, GlobalAttachment, GlobalAttachmentPath, GlobalError

Adapters that manage the test lifecycle themselves build on the lower-level subpackages:

• commons/runtime — the context-bound message bridge; bind ownership with runtime.WithRuntime, runtime.WithTest, runtime.WithFixture, and runtime.WithStep
• commons/writer — result persistence: NewFileSystemWriter for allure-results directories, NewInMemoryWriter for tests, NewMultiWriter to fan out
• commons/model — the serializable Allure result types (TestResult, StepResult, Label, Link, Parameter, Status, StatusDetails, and others)
• commons/testplan — test plan loading and matching: LoadFromEnv, LoadFile, Parse, Includes
• commons/ids — stable identity helpers: New, TestCaseID, HistoryID
• commons/clock — Unix epoch-millisecond timestamp helpers
• commons/lifecycle — lifecycle interfaces and event hooks for adapter authors