diff --git a/README.md b/README.md index 99b34dd10..cf27f1f4b 100644 --- a/README.md +++ b/README.md @@ -21,12 +21,25 @@ This is the go-openapi fork of the great [testify](https://github.com/stretchr/t > [!NOTE] > This is the home of `github.com/go-openapi/testify/v2`, an active, opinionated fork of `github.com/stretchr/testify`. -Main features: - -* zero external dependencies -* opt-in dependencies for extra features (e.g. asserting YAML, colorized output) -* assertions using generic types (see [a basic example][example-with-generics-url]). [Read the fully story with generics][doc-generics] -* [searchable documentation][doc-url] +## Why choose `go-openapi/testify/v2` + +* 95% compatible with `stretchr/testify` — if you already use it, our migration tool automates the switch +* Actively maintained: regular fixes and evolutions, many PRs proposed upstream are already in +* Zero external dependencies — you import what you need, with opt-in modules for extras (e.g. YAML, colorized output) +* Modernized codebase targeting go1.24+ +* Go routine leak detection built in: zero-setup, no false positives, works with parallel tests (unlike `go.uber.org/goleak`) +* File descriptor leak detection (linux-only) +* Type-safe assertions with generics (see [a basic example][example-with-generics-url]) — migration to generics can be automated too. [Read the full story][doc-generics] +* Safe async assertions, extended JSON & YAML assertions +* Coming in `v2.5.0`: non-flaky async assertions using `synctest`, and internal tools exposed as standalone modules (spew, unified diff, goleak) +* We take documentation seriously: [searchable doc site][doc-url] with testable examples and a complete tutorial, plus detailed [godoc][godoc-url] for every assertion + +### This fork isn't for everyone + +* You need the `mock` package — we removed it and won't bring it back. For suites, we're [open to discussion][suite-discussion] about a redesigned approach +* Your project must support Go versions older than 1.24 +* You rely on `testifylint` or other tooling that expects the `stretchr/testify` import path +* You need 100% API compatibility — we're at 95%, and the remaining 5% are intentional removals ## Announcements @@ -174,6 +187,7 @@ Maintainers can cut a new release by either: [doc-roadmap]: https://go-openapi.github.io/testify/project/maintainers/roadmap +[suite-discussion]: https://github.com/go-openapi/testify/discussions/75 [test-badge]: https://github.com/go-openapi/testify/actions/workflows/go-test.yml/badge.svg [test-url]: https://github.com/go-openapi/testify/actions/workflows/go-test.yml diff --git a/docs/doc-site/project/README.md b/docs/doc-site/project/README.md index 28ccc0232..7b8e85a19 100644 --- a/docs/doc-site/project/README.md +++ b/docs/doc-site/project/README.md @@ -3,6 +3,7 @@ title: README description: | Introducing go-openapi/testify/v2. + - Why choose testify/v2 - Approach - Main features - Differences with v1 @@ -11,6 +12,26 @@ weight: 2 **The v2 our tests wanted** +## Why choose `go-openapi/testify/v2` + +* 95% compatible with `stretchr/testify` — if you already use it, our migration tool automates the switch +* Actively maintained: regular fixes and evolutions, many PRs proposed upstream are already in +* Zero external dependencies — you import what you need, with opt-in modules for extras (e.g. YAML, colorized output) +* Modernized codebase targeting go1.24+ +* Go routine leak detection built in: zero-setup, no false positives, works with parallel tests (unlike `go.uber.org/goleak`) +* File descriptor leak detection (linux-only) +* Type-safe assertions with generics (see [a basic example](../usage/EXAMPLES.md)) — migration to generics can be automated too. [Read the full story](../usage/GENERICS.md) +* Safe async assertions, extended JSON & YAML assertions +* Coming in `v2.5.0`: non-flaky async assertions using `synctest`, and internal tools exposed as standalone modules (spew, unified diff, goleak) +* We take documentation seriously: [searchable doc site](../../api/) with testable examples and a complete tutorial, plus detailed [godoc][godoc-url] for every assertion + +### This fork isn't for everyone + +* You need the `mock` package — we removed it and won't bring it back. For suites, we're [open to discussion](https://github.com/go-openapi/testify/discussions/75) about a redesigned approach +* Your project must support Go versions older than 1.24 +* You rely on `testifylint` or other tooling that expects the `stretchr/testify` import path +* You need 100% API compatibility — we're at 95%, and the remaining 5% are intentional removals + ## Motivation See [why we wanted a v2](./MOTIVATION.md). diff --git a/docs/doc-site/project/contributing/STYLE.md b/docs/doc-site/project/contributing/STYLE.md index 8eeff5725..1c8ee1865 100644 --- a/docs/doc-site/project/contributing/STYLE.md +++ b/docs/doc-site/project/contributing/STYLE.md @@ -74,12 +74,12 @@ Here are the reasons why they are disabled (update: Feb. 2026, `golangci-lint v2 ```yaml disable: - - depguard # we don't want to configure rules to constrain import. That's the reviewer's job + - depguard # we don't want to configure rules to constrain imports. That's the reviewer's job - exhaustruct # we don't want to configure regexp's to check type name. That's the reviewer's job - - funlen # we accept cognitive complexity as a meaningful metric, but function length is relevant + - funlen # we accept cognitive complexity as a meaningful metric, but function length is not relevant - godox # we don't see any value in forbidding TODO's etc in code - nlreturn # we usually apply this "blank line" rule to make code less compact. We just don't want to enforce it - - nonamedreturns # we don't see any valid reason why we couldn't used named returns + - nonamedreturns # we don't see any valid reason why we couldn't use named returns - noinlineerr # there is no value added forbidding inlined err - paralleltest # we like parallel tests. We just don't want them to be enforced everywhere - recvcheck # we like the idea of having pointer and non-pointer receivers