assert.Empty: comprehensive doc of "Empty"-ness rules #1753

dolmen · 2025-05-28T16:36:16Z

Summary

Document the assert.Empty rules more comprehensively. This exposes our quirks to the user to avoid wrong expectations.

Add many many many more test cases that document edges cases and will allow to catch breaking changes and avoid regressions.

Changes

improve doc of assert.Empty, assert.NotEmpty (and their generated childs in package require)
add many test cases for the internal isEmpty. They are added in the current style for now, but I have plans for a future refactoring (using table tests).

Motivation

assert.Empty has quirks which desserve to be documented for our users, and for contributors.

The extensive test suite will help to ease future refactorings of Testify internals by catch breaking changes.

Related issues

dolmen · 2025-05-28T16:38:58Z

Cc: @PeterEFinch could you review this?

assert/assertions_test.go

ccoVeille · 2025-05-28T17:37:44Z

I learned things BTW

assert/assertions_test.go

PeterEFinch · 2025-05-29T10:45:57Z

assert/assertions.go

+// Empty asserts that the given value is "empty".
+//
+// [Zero values](https://go.dev/ref/spec#The_zero_value) are "Empty".
+// Arrays are "Empty" if every element is the zero value of the type (stricter than "Empty").
+//
+// Slices, maps and channels with zero length are "Empty".
+//
+// Pointer values are "Empty" if the pointer is nil or if the pointed value is "Empty".


This comment is definitely an improvement and aligns with what is I see is implemented.

I was also wondering if the current implementation:

testify/assert/assertions.go

Lines 770 to 773 in 3c1541a

default:

zero := reflect.Zero(objValue.Type())

return reflect.DeepEqual(object, zero.Interface())

}

is in any way different to

default: return objValue.IsZero() }

if so that might be worthwhile highlighting (I doubt there is any difference though).

reflect.Value.IsZero() did not exist when assert.Empty has been added.

It is a good idea for a future refactoring. That's why we first need a strong test suite.

PeterEFinch · 2025-05-29T11:26:40Z

assert/assertions_test.go

+	True(t, isEmpty(error(nil)))
+	True(t, isEmpty((*int)(nil)))
+	True(t, isEmpty((*string)(nil)))
+	True(t, isEmpty(new(string)))


I think your list is pretty extensive.

You could test some interfaces with nil values but have a types associated with them but that might be a bit overkill. For example, you can have err being nil according to the assertions but is not equal to nil

type MyError struct{} func (e *MyError) Error() string { return "my error" } func TestMyError_isNil(t *testing.T) { var e *MyError err := error(e) assert.False(t, err == nil) assert.Empty(t, err) assert.Nil(t, err) assert.Zero(t, err) }

Because testify works at runtime it does not have visibility of your code's interface types, they get always converted into interface{}, eg:

var e *MyError // type: *MyError, value: nil assert.Empty(t, e) ... func Empty(t TestingT, object interface{}, msgAndArgs ...interface{}) bool { object // type: interface{}, value: (*MyError)(nil) ... err := error(e) // type: error, value: (*MyError)(nil) assert.Empty(t, err) ... func Empty(t TestingT, object interface{}, msgAndArgs ...interface{}) bool { object // type: interface{}, value: (*MyError)(nil)

Put simply, testify cannot tell that you passed an interface.

brackendawson · 2025-05-30T09:17:26Z

assert/assertions.go

+// [Zero values](https://go.dev/ref/spec#The_zero_value) are "Empty".
+// Arrays are "Empty" if every element is the zero value of the type (stricter than "Empty").


Malformed Zero values link and missing line break between Zero values and Arrays:

Fixed.

I had to swich all mentions of "Empty" to "empty" because codegen replaces them ("Empty" becomes "Emptyf" in the doc of Emptyf).

Document the assert.Empty rules more comprehensively. This exposes our quirks to the user to avoid wrong expectations. Add many many many more test cases that document edges cases and will allow to catch breaking changes and avoid regressions.

brackendawson

LGTM and renders nice in pkgsite.

…nercloud/fleeting-plugin-hetzner!273) This MR contains the following updates: | Package | Change | Age | Confidence | |---|---|---|---| | [github.com/stretchr/testify](https://github.com/stretchr/testify) | `v1.10.0` -> `v1.11.0` | [![age](https://developer.mend.io/api/mc/badges/age/go/github.com%2fstretchr%2ftestify/v1.11.0?slim=true)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://developer.mend.io/api/mc/badges/confidence/go/github.com%2fstretchr%2ftestify/v1.10.0/v1.11.0?slim=true)](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>stretchr/testify (github.com/stretchr/testify)</summary> ### [`v1.11.0`](https://github.com/stretchr/testify/releases/tag/v1.11.0) [Compare Source](stretchr/testify@v1.10.0...v1.11.0) #### What's Changed ##### Functional Changes v1.11.0 Includes a number of performance improvements. - Call stack perf change for CallerInfo by [@mikeauclair](https://github.com/mikeauclair) in [#1614](stretchr/testify#1614) - Lazily render mock diff output on successful match by [@mikeauclair](https://github.com/mikeauclair) in [#1615](stretchr/testify#1615) - assert: check early in Eventually, EventuallyWithT, and Never by [@cszczepaniak](https://github.com/cszczepaniak) in [#1427](stretchr/testify#1427) - assert: add IsNotType by [@bartventer](https://github.com/bartventer) in [#1730](stretchr/testify#1730) - assert.JSONEq: shortcut if same strings by [@dolmen](https://github.com/dolmen) in [#1754](stretchr/testify#1754) - assert.YAMLEq: shortcut if same strings by [@dolmen](https://github.com/dolmen) in [#1755](stretchr/testify#1755) - assert: faster and simpler isEmpty using reflect.Value.IsZero by [@dolmen](https://github.com/dolmen) in [#1761](stretchr/testify#1761) - suite: faster methods filtering (internal refactor) by [@dolmen](https://github.com/dolmen) in [#1758](stretchr/testify#1758) ##### Fixes - assert.ErrorAs: log target type by [@craig65535](https://github.com/craig65535) in [#1345](stretchr/testify#1345) - Fix failure message formatting for Positive and Negative asserts in [#1062](stretchr/testify#1062) - Improve ErrorIs message when error is nil but an error was expected by [@tsioftas](https://github.com/tsioftas) in [#1681](stretchr/testify#1681) - fix Subset/NotSubset when calling with mixed input types by [@siliconbrain](https://github.com/siliconbrain) in [#1729](stretchr/testify#1729) - Improve ErrorAs failure message when error is nil by [@ccoVeille](https://github.com/ccoVeille) in [#1734](stretchr/testify#1734) - mock.AssertNumberOfCalls: improve error msg by [@3scalation](https://github.com/3scalation) in [#1743](stretchr/testify#1743) ##### Documentation, Build & CI - docs: Fix typo in README by [@alexandear](https://github.com/alexandear) in [#1688](stretchr/testify#1688) - Replace deprecated io/ioutil with io and os by [@alexandear](https://github.com/alexandear) in [#1684](stretchr/testify#1684) - Document consequences of calling t.FailNow() by [@greg0ire](https://github.com/greg0ire) in [#1710](stretchr/testify#1710) - chore: update docs for Unset [#1621](stretchr/testify#1621) by [@techfg](https://github.com/techfg) in [#1709](stretchr/testify#1709) - README: apply gofmt to examples by [@alexandear](https://github.com/alexandear) in [#1687](stretchr/testify#1687) - refactor: use %q and %T to simplify fmt.Sprintf by [@alexandear](https://github.com/alexandear) in [#1674](stretchr/testify#1674) - Propose Christophe Colombier (ccoVeille) as approver by [@brackendawson](https://github.com/brackendawson) in [#1716](stretchr/testify#1716) - Update documentation for the Error function in assert or require package by [@architagr](https://github.com/architagr) in [#1675](stretchr/testify#1675) - assert: remove deprecated build constraints by [@alexandear](https://github.com/alexandear) in [#1671](stretchr/testify#1671) - assert: apply gofumpt to internal test suite by [@ccoVeille](https://github.com/ccoVeille) in [#1739](stretchr/testify#1739) - CI: fix shebang in .ci.\*.sh scripts by [@dolmen](https://github.com/dolmen) in [#1746](stretchr/testify#1746) - assert,require: enable parallel testing on (almost) all top tests by [@dolmen](https://github.com/dolmen) in [#1747](stretchr/testify#1747) - suite.Passed: add one more status test report by [@Ararsa-Derese](https://github.com/Ararsa-Derese) in [#1706](stretchr/testify#1706) - Add Helper() method in internal mocks and assert.CollectT by [@dolmen](https://github.com/dolmen) in [#1423](stretchr/testify#1423) - assert.Same/NotSame: improve usage of Sprintf by [@ccoVeille](https://github.com/ccoVeille) in [#1742](stretchr/testify#1742) - mock: enable parallel testing on internal testsuite by [@dolmen](https://github.com/dolmen) in [#1756](stretchr/testify#1756) - suite: cleanup use of 'testing' internals at runtime by [@dolmen](https://github.com/dolmen) in [#1751](stretchr/testify#1751) - assert: check test failure message for Empty and NotEmpty by [@ccoVeille](https://github.com/ccoVeille) in [#1745](stretchr/testify#1745) - deps: fix dependency cycle with objx (again) by [@dolmen](https://github.com/dolmen) in [#1567](stretchr/testify#1567) - assert.Empty: comprehensive doc of "Empty"-ness rules by [@dolmen](https://github.com/dolmen) in [#1753](stretchr/testify#1753) - doc: improve godoc of top level 'testify' package by [@dolmen](https://github.com/dolmen) in [#1760](stretchr/testify#1760) - assert.ErrorAs: simplify retrieving the type name by [@ccoVeille](https://github.com/ccoVeille) in [#1740](stretchr/testify#1740) - assert.EqualValues: improve test coverage to 100% by [@dolmen](https://github.com/dolmen) in [#1763](stretchr/testify#1763) - suite.Run: simplify running of Setup/TeardownSuite by [@renzoarreaza](https://github.com/renzoarreaza) in [#1769](stretchr/testify#1769) - assert.CallerInfo: micro optimization by using LastIndexByte by [@dolmen](https://github.com/dolmen) in [#1767](stretchr/testify#1767) - assert.CallerInfo: micro cleanup by [@dolmen](https://github.com/dolmen) in [#1768](stretchr/testify#1768) - assert: refactor Test*FileExists and Test*DirExists tests to enable parallel testing by [@dolmen](https://github.com/dolmen) in [#1766](stretchr/testify#1766) - suite.Run: refactor handling of stats for improved readability by [@dolmen](https://github.com/dolmen) in [#1764](stretchr/testify#1764) - tests: improve captureTestingT helper by [@ccoVeille](https://github.com/ccoVeille) in [#1741](stretchr/testify#1741) - build(deps): bump actions/checkout from 4 to 5 by [@dependabot](https://github.com/dependabot)\[bot] in [#1778](stretchr/testify#1778) #### New Contributors - [@greg0ire](https://github.com/greg0ire) made their first contribution in [#1710](stretchr/testify#1710) - [@techfg](https://github.com/techfg) made their first contribution in [#1709](stretchr/testify#1709) - [@mikeauclair](https://github.com/mikeauclair) made their first contribution in [#1614](stretchr/testify#1614) - [@cszczepaniak](https://github.com/cszczepaniak) made their first contribution in [#1427](stretchr/testify#1427) - [@architagr](https://github.com/architagr) made their first contribution in [#1675](stretchr/testify#1675) - [@tsioftas](https://github.com/tsioftas) made their first contribution in [#1681](stretchr/testify#1681) - [@siliconbrain](https://github.com/siliconbrain) made their first contribution in [#1729](stretchr/testify#1729) - [@bartventer](https://github.com/bartventer) made their first contribution in [#1730](stretchr/testify#1730) - [@Ararsa-Derese](https://github.com/Ararsa-Derese) made their first contribution in [#1706](stretchr/testify#1706) - [@renzoarreaza](https://github.com/renzoarreaza) made their first contribution in [#1769](stretchr/testify#1769) - [@3scalation](https://github.com/3scalation) made their first contribution in [#1743](stretchr/testify#1743) **Full Changelog**: <stretchr/testify@v1.10.0...v1.11.0> </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

This PR contains the following updates: | Package | Change | Age | Confidence | |---|---|---|---| | [github.com/stretchr/testify](https://github.com/stretchr/testify) | `v1.10.0` -> `v1.11.1` | [![age](https://developer.mend.io/api/mc/badges/age/go/github.com%2fstretchr%2ftestify/v1.11.1?slim=true)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://developer.mend.io/api/mc/badges/confidence/go/github.com%2fstretchr%2ftestify/v1.10.0/v1.11.1?slim=true)](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>stretchr/testify (github.com/stretchr/testify)</summary> ### [`v1.11.1`](https://github.com/stretchr/testify/releases/tag/v1.11.1) [Compare Source](stretchr/testify@v1.11.0...v1.11.1) This release fixes [#1785](stretchr/testify#1785) introduced in v1.11.0 where expected argument values implementing the stringer interface (`String() string`) with a method which mutates their value, when passed to mock.Mock.On (`m.On("Method", <expected>).Return()`) or actual argument values passed to mock.Mock.Called may no longer match one another where they previously did match. The behaviour prior to v1.11.0 where the stringer is always called is restored. Future testify releases may not call the stringer method at all in this case. #### What's Changed - Backport [#1786](stretchr/testify#1786) to release/1.11: mock: revert to pre-v1.11.0 argument matching behavior for mutating stringers by [@brackendawson](https://github.com/brackendawson) in [#1788](stretchr/testify#1788) **Full Changelog**: <stretchr/testify@v1.11.0...v1.11.1> ### [`v1.11.0`](https://github.com/stretchr/testify/releases/tag/v1.11.0) [Compare Source](stretchr/testify@v1.10.0...v1.11.0) #### What's Changed ##### Functional Changes v1.11.0 Includes a number of performance improvements. - Call stack perf change for CallerInfo by [@mikeauclair](https://github.com/mikeauclair) in [#1614](stretchr/testify#1614) - Lazily render mock diff output on successful match by [@mikeauclair](https://github.com/mikeauclair) in [#1615](stretchr/testify#1615) - assert: check early in Eventually, EventuallyWithT, and Never by [@cszczepaniak](https://github.com/cszczepaniak) in [#1427](stretchr/testify#1427) - assert: add IsNotType by [@bartventer](https://github.com/bartventer) in [#1730](stretchr/testify#1730) - assert.JSONEq: shortcut if same strings by [@dolmen](https://github.com/dolmen) in [#1754](stretchr/testify#1754) - assert.YAMLEq: shortcut if same strings by [@dolmen](https://github.com/dolmen) in [#1755](stretchr/testify#1755) - assert: faster and simpler isEmpty using reflect.Value.IsZero by [@dolmen](https://github.com/dolmen) in [#1761](stretchr/testify#1761) - suite: faster methods filtering (internal refactor) by [@dolmen](https://github.com/dolmen) in [#1758](stretchr/testify#1758) ##### Fixes - assert.ErrorAs: log target type by [@craig65535](https://github.com/craig65535) in [#1345](stretchr/testify#1345) - Fix failure message formatting for Positive and Negative asserts in [#1062](stretchr/testify#1062) - Improve ErrorIs message when error is nil but an error was expected by [@tsioftas](https://github.com/tsioftas) in [#1681](stretchr/testify#1681) - fix Subset/NotSubset when calling with mixed input types by [@siliconbrain](https://github.com/siliconbrain) in [#1729](stretchr/testify#1729) - Improve ErrorAs failure message when error is nil by [@ccoVeille](https://github.com/ccoVeille) in [#1734](stretchr/testify#1734) - mock.AssertNumberOfCalls: improve error msg by [@3scalation](https://github.com/3scalation) in [#1743](stretchr/testify#1743) ##### Documentation, Build & CI - docs: Fix typo in README by [@alexandear](https://github.com/alexandear) in [#1688](stretchr/testify#1688) - Replace deprecated io/ioutil with io and os by [@alexandear](https://github.com/alexandear) in [#1684](stretchr/testify#1684) - Document consequences of calling t.FailNow() by [@greg0ire](https://github.com/greg0ire) in [#1710](stretchr/testify#1710) - chore: update docs for Unset [#1621](stretchr/testify#1621) by [@techfg](https://github.com/techfg) in [#1709](stretchr/testify#1709) - README: apply gofmt to examples by [@alexandear](https://github.com/alexandear) in [#1687](stretchr/testify#1687) - refactor: use %q and %T to simplify fmt.Sprintf by [@alexandear](https://github.com/alexandear) in [#1674](stretchr/testify#1674) - Propose Christophe Colombier (ccoVeille) as approver by [@brackendawson](https://github.com/brackendawson) in [#1716](stretchr/testify#1716) - Update documentation for the Error function in assert or require package by [@architagr](https://github.com/architagr) in [#1675](stretchr/testify#1675) - assert: remove deprecated build constraints by [@alexandear](https://github.com/alexandear) in [#1671](stretchr/testify#1671) - assert: apply gofumpt to internal test suite by [@ccoVeille](https://github.com/ccoVeille) in [#1739](stretchr/testify#1739) - CI: fix shebang in .ci.\*.sh scripts by [@dolmen](https://github.com/dolmen) in [#1746](stretchr/testify#1746) - assert,require: enable parallel testing on (almost) all top tests by [@dolmen](https://github.com/dolmen) in [#1747](stretchr/testify#1747) - suite.Passed: add one more status test report by [@Ararsa-Derese](https://github.com/Ararsa-Derese) in [#1706](stretchr/testify#1706) - Add Helper() method in internal mocks and assert.CollectT by [@dolmen](https://github.com/dolmen) in [#1423](stretchr/testify#1423) - assert.Same/NotSame: improve usage of Sprintf by [@ccoVeille](https://github.com/ccoVeille) in [#1742](stretchr/testify#1742) - mock: enable parallel testing on internal testsuite by [@dolmen](https://github.com/dolmen) in [#1756](stretchr/testify#1756) - suite: cleanup use of 'testing' internals at runtime by [@dolmen](https://github.com/dolmen) in [#1751](stretchr/testify#1751) - assert: check test failure message for Empty and NotEmpty by [@ccoVeille](https://github.com/ccoVeille) in [#1745](stretchr/testify#1745) - deps: fix dependency cycle with objx (again) by [@dolmen](https://github.com/dolmen) in [#1567](stretchr/testify#1567) - assert.Empty: comprehensive doc of "Empty"-ness rules by [@dolmen](https://github.com/dolmen) in [#1753](stretchr/testify#1753) - doc: improve godoc of top level 'testify' package by [@dolmen](https://github.com/dolmen) in [#1760](stretchr/testify#1760) - assert.ErrorAs: simplify retrieving the type name by [@ccoVeille](https://github.com/ccoVeille) in [#1740](stretchr/testify#1740) - assert.EqualValues: improve test coverage to 100% by [@dolmen](https://github.com/dolmen) in [#1763](stretchr/testify#1763) - suite.Run: simplify running of Setup/TeardownSuite by [@renzoarreaza](https://github.com/renzoarreaza) in [#1769](stretchr/testify#1769) - assert.CallerInfo: micro optimization by using LastIndexByte by [@dolmen](https://github.com/dolmen) in [#1767](stretchr/testify#1767) - assert.CallerInfo: micro cleanup by [@dolmen](https://github.com/dolmen) in [#1768](stretchr/testify#1768) - assert: refactor Test*FileExists and Test*DirExists tests to enable parallel testing by [@dolmen](https://github.com/dolmen) in [#1766](stretchr/testify#1766) - suite.Run: refactor handling of stats for improved readability by [@dolmen](https://github.com/dolmen) in [#1764](

dolmen requested review from brackendawson and ccoVeille and removed request for brackendawson May 28, 2025 16:39

dolmen mentioned this pull request May 28, 2025

assert: add NoFieldIsZero #1591

Open

dolmen added documentation internal/testing Changes purely related to the testify testsuites pkg-assert Change related to package testify/assert pkg-require Change related to package testify/require labels May 28, 2025

ccoVeille reviewed May 28, 2025

View reviewed changes

assert/assertions_test.go Show resolved Hide resolved

assert/assertions_test.go Show resolved Hide resolved

assert/assertions_test.go Show resolved Hide resolved

ccoVeille reviewed May 28, 2025

View reviewed changes

assert/assertions_test.go Show resolved Hide resolved

PeterEFinch reviewed May 29, 2025

View reviewed changes

brackendawson requested changes May 30, 2025

View reviewed changes

dolmen force-pushed the dolmen/comprehensive-Empty-doc-and-tests branch from eb38cdb to 706c004 Compare May 30, 2025 14:23

dolmen marked this pull request as draft May 30, 2025 14:27

dolmen force-pushed the dolmen/comprehensive-Empty-doc-and-tests branch 3 times, most recently from 39a9613 to 6485e37 Compare May 30, 2025 15:23

dolmen requested a review from ccoVeille May 30, 2025 22:09

ccoVeille approved these changes May 31, 2025

View reviewed changes

dolmen force-pushed the dolmen/comprehensive-Empty-doc-and-tests branch from 6485e37 to 77158ae Compare June 1, 2025 21:30

brackendawson approved these changes Jun 2, 2025

View reviewed changes

dolmen marked this pull request as ready for review June 2, 2025 22:10

dolmen merged commit c519b79 into master Jun 2, 2025
16 checks passed

SaveTheRbtz mentioned this pull request Aug 26, 2025

build(deps): bump github.com/stretchr/testify from 1.10.0 to 1.11.0 in /pkg SaveTheRbtz/zstd-seekable-format-go#210

Closed

brackendawson deleted the dolmen/comprehensive-Empty-doc-and-tests branch August 27, 2025 10:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

assert.Empty: comprehensive doc of "Empty"-ness rules #1753

assert.Empty: comprehensive doc of "Empty"-ness rules #1753

Uh oh!

dolmen commented May 28, 2025 •

edited

Loading

Uh oh!

dolmen commented May 28, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ccoVeille commented May 28, 2025

Uh oh!

Uh oh!

PeterEFinch May 29, 2025

Uh oh!

dolmen May 30, 2025

Uh oh!

PeterEFinch May 29, 2025

Uh oh!

brackendawson May 30, 2025

Uh oh!

brackendawson May 30, 2025

Uh oh!

dolmen May 30, 2025

Uh oh!

brackendawson left a comment

Uh oh!

Uh oh!

	default:
	zero := reflect.Zero(objValue.Type())
	return reflect.DeepEqual(object, zero.Interface())
	}

		// [Zero values](https://go.dev/ref/spec#The_zero_value) are "Empty".
		// Arrays are "Empty" if every element is the zero value of the type (stricter than "Empty").

assert.Empty: comprehensive doc of "Empty"-ness rules #1753

assert.Empty: comprehensive doc of "Empty"-ness rules #1753

Uh oh!

Conversation

dolmen commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Motivation

Related issues

Uh oh!

dolmen commented May 28, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ccoVeille commented May 28, 2025

Uh oh!

Uh oh!

PeterEFinch May 29, 2025

Choose a reason for hiding this comment

Uh oh!

dolmen May 30, 2025

Choose a reason for hiding this comment

Uh oh!

PeterEFinch May 29, 2025

Choose a reason for hiding this comment

Uh oh!

brackendawson May 30, 2025

Choose a reason for hiding this comment

Uh oh!

brackendawson May 30, 2025

Choose a reason for hiding this comment

Uh oh!

dolmen May 30, 2025

Choose a reason for hiding this comment

Uh oh!

brackendawson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dolmen commented May 28, 2025 •

edited

Loading