Testify

---

Testify - Thou Shalt Write Tests

A Go set of packages that provide tools for testifying that your code will behave as you intend.

This is the go-openapi fork of the great testify package.

Why this fork?

From the maintainers of testify, it looks like a v2 is coming up, but they'll do it at their own pace.

We like all the principles they put forward to build this v2. See discussion about v2

However, at go-openapi we would like to address the well-known issues in testify with different priorities.

1. We want first to remove all external dependencies.

For all our libraries and generated test code we don't want test dependencies to drill farther than import github.com/go-openapi/testify/v2, but on some specific (and controlled) occasions.

In this fork, all external stuff is either internalized (go-spew, difflib), removed (mocks, suite, http) or specifically enabled by importing a specific module (github.com/go-openapi/testify/v2/enable/yaml).

2. We want to remove most of the chrome that has been added over the years

The go-openapi libraries and the go-swagger project make a rather limited use of the vast API provided by testify.

With this first version of the fork, we have removed mocks and suite, which we don't use. They might be added later on, with better controlled dependencies.

In the forthcoming maintenance of this fork, much of the "chrome" or "ambiguous" API will be pared down. There is no commitment yet on the stability of the API.

Chrome would be added later: we have the "enable" packages just for that.

3. We hope that this endeavor will help the original project with a live-drill of what a v2 could look like. We are always happy to discuss with people who face the same problems as we do: avoid breaking changes, APIs that became bloated over a decade or so, uncontrolled dependencies, conflicting demands from users etc.

What's next with this project?

1. The first release comes with zero dependencies and an unstable API (see below our use case)
2. |x] This project is going to be injected as the main and sole test dependency of the go-openapi libraries
3. ... and the go-swagger tool
4. [ ) Valuable pending pull requests from the original project could be merged (e.g. JSONEqBytes) or transformed as "enable" modules (e.g. colorized output)
5. Unclear assertions may be provided an alternative verb (e.g. InDelta)
6. Since we have leveled the go requirements to the rest of the go-openapi (currently go1.24) there is quite a bit of relinting lying ahead.

What won't come anytime soon

• mocks: we use mockery and prefer the simpler matryer mocking-style. testify-style mocks are thus not going to be supported anytime soon.
• extra convoluted stuff in the like of InDeltaSlice

Generics adoption

Context from the original repository

Several attempts have been made to introduce generics in the original stretchr/testify repository:

• github.com/stretchr#1308 - Comprehensive refactor replacing interface{} with generic type parameters across assertions (Draft, v2.0.0 milestone)
• github.com/stretchr#1805 - Proposal for generic IsOfType[T]() to avoid dummy value instantiation in type checks
• github.com/stretchr#1685 - Iterator support (iter.Seq) for Contains/ElementsMatch assertions (Go 1.23+)
• github.com/stretchr#1147 - General discussion about generics adoption (marked "Not Planned")

Challenges identified

The original repository's exploration of generics revealed several design challenges:

1. Type inference limitations: Go's type inference struggles with complex generic signatures, often requiring explicit type parameters that burden the API (e.g., Contains[int, int](arr1, arr2))

2. Overly broad type constraints: PR #1308's approach used constraints like ConvertibleToFloat64 that accepted more types than intended, weakening type safety

3. Loss of flexibility: Testify currently compares non-comparable types (slices, maps) via reflect.DeepEqual. Generic constraints would eliminate this capability, as Go generics require comparable or explicitly constrained types

4. Breaking changes: Any comprehensive generics adoption requires a major version bump and Go 1.18+ minimum version

5. Inconsistent design patterns: Different assertions would need different constraint strategies, making a uniform approach difficult

Approach in this fork

This fork targets go1.24 and can leverage generics without backward compatibility concerns.

The approach will be selective and pragmatic rather than comprehensive:

• Targeted improvements where generics provide clear value without compromising existing functionality
• Focus on eliminating anti-patterns like dummy value instantiation in IsType (see #1805)
• Preserve reflection-based flexibility for comparing complex types rather than forcing everything through generic constraints
• Careful constraint design to ensure type safety without being overly restrictive or permissive

The goal is to enhance type safety and developer experience where it matters most, while maintaining the flexibility that makes testify useful for real-world testing scenarios.

Status: Design and exploration phase. Contributions and proposals welcome.

Usage at go-openapi

At this moment, we have identified the following usage in our tools. This API shall remain stable. Currently, there are no guarantees about the entry points not in this list.

TODO: extend the list with usage by go-swagger.

Condition
Contains,Containsf
Empty,Emptyf
Equal,Equalf
EqualError,EqualErrorf
EqualValues,EqualValuesf
Error,Errorf
ErrorContains
ErrorIs
Fail,Failf
FailNow
False,Falsef
Greater
Implements
InDelta,InDeltaf
IsType,IsTypef
JSONEq,JSONEqf
Len,Lenf
Nil,Nilf
NoError,NoErrorf
NotContains,NotContainsf
NotEmpty,NotEmptyf
NotEqual
NotNil,NotNilf
NotPanics
NotZeroG
Panics,PanicsWithValue
Subset
True,Truef
YAMLEq,YAMLEqf
Zero,Zerof

Installation

To use this package in your projects:

    go get github.com/go-openapi/testify/v2

Get started

Features include:

• Easy assertions
• Mocking removed
• Testing suite interfaces and functions removed

Examples

See the original README

Licensing

SPDX-FileCopyrightText: Copyright 2025 go-swagger maintainers

This library ships under the SPDX-License-Identifier: Apache-2.0.

See the license NOTICE, which recalls the licensing terms of all the pieces of software distributed with this fork, including internalized libraries.

• stretchr/testify SPDX-License-Identifier: MIT
• github.com/davecgh/go-spew SPDX-License-Identifier: ISC
• github.com/pmezard/go-difflib SPDX-License-Identifier: MIT-like
• imports SPDX-License-Identifier: MIT

PRs from the original repo

Already merged or incorporated

The following proposed contributions to the original repo have been merged or incorporated with some adaptations into this fork:

• github.com/stretchr#1513 - JSONEqBytes for byte slice JSON comparison
• github.com/stretchr#1772 - YAML library migration to maintained fork (go.yaml.in/yaml)
• github.com/stretchr#1797 - Codegen package consolidation and licensing
• github.com/stretchr#1356 - panic(nil) handling for Go 1.21+

Planned merges

Critical safety fixes (high priority)

• github.com/stretchr#1825 - Fix panic when using EqualValues with uncomparable types
• github.com/stretchr#1818 - Fix panic on invalid regex in Regexp/NotRegexp assertions

Leveraging internalized dependencies (go-spew, difflib)

These improvements apply to the internalized and modernized copies of dependencies in this fork:

• github.com/stretchr#1829 - Fix time.Time rendering in diffs (internalized go-spew)
• github.com/stretchr#1822 - Deterministic map ordering in diffs (internalized go-spew)
• github.com/stretchr#1816 - Fix panic on unexported struct key in map (internalized go-spew - may need deeper fix)

UX improvements

• github.com/stretchr#1223 - Display uint values in decimal instead of hex in diffs

Under consideration

Colorized output

Several PRs propose colorized terminal output with different approaches and dependencies. If implemented, this would be provided as an optional enable/color module:

• github.com/stretchr#1467 - Colorized output with terminal detection (most mature implementation)
• github.com/stretchr#1480 - Colorized diffs via TESTIFY_COLORED_DIFF env var
• github.com/stretchr#1232 - Colorized output for expected/actual/errors
• github.com/stretchr#994 - Colorize expected vs actual values

Contributing

Please feel free to submit issues, fork the repository and send pull requests!

When submitting an issue, we ask that you please include a complete test function that demonstrates the issue. Extra credit for those using Testify to write the test code that demonstrates it.

Code generation is used. Run go generate ./... to update generated files.

See also the CONTRIBUTING guidelines.

The original README