Fix `hardhat-ethers-chai-matchers` by alcuadrado · Pull Request #7993 · NomicFoundation/hardhat

alcuadrado · 2026-02-24T00:45:21Z

This PR is a result of investigating #7726 and replaces it

This PR introduces to three fixes to hardhat-ethers-chai-matchers:

It remove all the usages of assertHardhatInvariant with assert.fail with descriptive messages. The assertHardhatInvariant function should only be used for things that should always be true. It should not be used to validate inputs or return values.
It preservers all the error.causes
It removes HardhatErrors from within assertions, as they play nicely with mocha.

It also introduces a small formatting improvement to a hardhat-mocha error message.

…t invariants

changeset-bot · 2026-02-24T00:45:31Z

🦋 Changeset detected

Latest commit: 692a28f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@nomicfoundation/hardhat-ethers-chai-matchers	Patch
@nomicfoundation/hardhat-mocha	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Copilot

Pull request overview

This PR refactors error handling in hardhat-ethers-chai-matchers by replacing HardhatError instances with more descriptive assertion failures and improving error context preservation.

Changes:

Replaced assertHardhatInvariant and HardhatError usages with chaiAssert.fail() and descriptive error messages throughout the matchers
Ensured error.cause is preserved in catch blocks for better error debugging
Added blank line before error message output in hardhat-mocha for better formatting

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
v-next/hardhat-mocha/src/unhandled-rejection-mocha-hook.ts	Added blank line before error message output
v-next/hardhat-ethers-chai-matchers/test/matchers/reverted/revertedWithPanic.ts	Updated tests to use `assertThrows` instead of `assertThrowsHardhatError`
v-next/hardhat-ethers-chai-matchers/test/matchers/reverted/revertedWithCustomError.ts	Updated tests to use `assertThrows` instead of `assertThrowsHardhatError`
v-next/hardhat-ethers-chai-matchers/test/matchers/reverted/revertedWith.ts	Updated tests to use `assertThrows` instead of `assertThrowsHardhatError`
v-next/hardhat-ethers-chai-matchers/test/matchers/reverted/revert.ts	Updated tests to use `assertThrows` and `assertRejects` instead of hardhat-specific error assertions
v-next/hardhat-ethers-chai-matchers/test/matchers/reverted/legacyReverted.ts	Updated tests to use `assertThrows` and `assertRejects` instead of hardhat-specific error assertions
v-next/hardhat-ethers-chai-matchers/test/matchers/events.ts	Updated tests to use `assertRejects` instead of `assertRejectsWithHardhatError`
v-next/hardhat-ethers-chai-matchers/test/matchers/changeTokenBalance.ts	Updated tests and error message expectations to use new assertion format
v-next/hardhat-ethers-chai-matchers/test/matchers/changeEtherBalances.ts	Updated tests to use `assertThrows` instead of `assertThrowsHardhatError`
v-next/hardhat-ethers-chai-matchers/test/matchers/changeEtherBalance.ts	Updated tests and error message expectations to use new assertion format
v-next/hardhat-ethers-chai-matchers/src/internal/utils/prevent-chaining.ts	Replaced `HardhatError` with `chaiAssert.fail()` for matcher chaining errors
v-next/hardhat-ethers-chai-matchers/src/internal/utils/build-assert.ts	Replaced `HardhatError` with `chaiAssert.fail()` for assertion errors
v-next/hardhat-ethers-chai-matchers/src/internal/utils/balance.ts	Added error cause preservation in balance retrieval error handling
v-next/hardhat-ethers-chai-matchers/src/internal/utils/asserts.ts	Replaced `assertHardhatInvariant` with `chaiAssert` methods and preserved error causes
v-next/hardhat-ethers-chai-matchers/src/internal/utils/account.ts	Replaced `HardhatError` with `chaiAssert.fail()` for address validation
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/withArgs.ts	Replaced `HardhatError` with `chaiAssert.fail()` for validation errors
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/reverted/utils.ts	Added error cause preservation in decoding error handling
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/reverted/revertedWithPanic.ts	Added error cause preservation in panic code validation
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/reverted/revertedWithCustomError.ts	Replaced `HardhatError` with `chaiAssert.fail()` for validation errors
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/reverted/revertedWith.ts	Replaced `HardhatError` with `chaiAssert.fail()` for validation errors
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/reverted/revert.ts	Replaced `HardhatError` with `chaiAssert.fail()` and improved error messages
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/reverted/legacyReverted.ts	Replaced `HardhatError` with `chaiAssert.fail()` for deprecation error
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/emit.ts	Replaced `HardhatError` with `chaiAssert.fail()` and preserved error cause
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/changeTokenBalance.ts	Replaced `assertHardhatInvariant` with `chaiAssert` methods and improved error messages
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/changeEtherBalances.ts	Replaced `HardhatError` with `chaiAssert.fail()` and improved error messages
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/changeEtherBalance.ts	Replaced `assertHardhatInvariant` with `chaiAssert` methods and refactored balance retrieval
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/big-number.ts	Replaced `HardhatError` with `chaiAssert.fail()` for unknown comparison operation
v-next/hardhat-ethers-chai-matchers/src/internal/matchers/addressable.ts	Replaced `assertHardhatInvariant` with `chaiAssert.ok()` and improved error message
v-next/hardhat-ethers-chai-matchers/package.json	Removed `@nomicfoundation/hardhat-errors` dependency

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

github-actions · 2026-02-24T00:50:11Z

hardhat

Total size of the bundle: 245M
Total number of dependencies (including transitive): 48

List of dependencies (sorted by size)

238M	total
37M	@nomicfoundation/edr-linux-x64-musl
37M	@nomicfoundation/edr-linux-x64-gnu
34M	@nomicfoundation/edr-linux-arm64-musl
34M	@nomicfoundation/edr-linux-arm64-gnu
25M	@nomicfoundation/edr-darwin-x64
24M	@nomicfoundation/edr-win32-x64-msvc
21M	@nomicfoundation/edr-darwin-arm64
7.3M	@sentry/core
5.2M	zod
2.7M	micro-eth-signer
1.9M	@noble/curves
1.7M	undici
1.2M	@noble/hashes
1.1M	@nomicfoundation/hardhat-utils
884K	@nomicfoundation/hardhat-vendored
864K	@streamparser/json
624K	micro-packed
592K	tsx
556K	@nomicfoundation/hardhat-errors
492K	@scure/bip39
476K	@nomicfoundation/edr
408K	json-stream-stringify
368K	ethereum-cryptography
344K	fast-equals
332K	@streamparser/json-node
320K	enquirer
320K	@nomicfoundation/hardhat-zod-utils
288K	semver
200K	ws
180K	chokidar
176K	get-tsconfig
168K	@scure/base
160K	esbuild
136K	adm-zip
96K	@scure/bip32
92K	chalk
72K	@nomicfoundation/solidity-analyzer
68K	debug
60K	readdirp
56K	rfdc
48K	ansi-colors
44K	resolve.exports
40K	resolve-pkg-maps
36K	p-map
24K	strip-ansi
24K	env-paths
24K	ansi-regex
20K	ms

alcuadrado · 2026-02-24T00:53:44Z

I'll fix the chai v5 workflow tomorrow.

kanej · 2026-02-24T11:29:00Z

+            assertIsNotNull(
+              receipt,
+              "Transaction's receipt cannot be fetched from the network",
+            );


This makes sense if we assume chai matchers can never be used against a non-automining chain, are we happy with that assumption?

I didn't change that assumption here. It was always present. I guess we can create an issue to revisit it if needed. @ChristopherDedominici

Note that these matchers may assume a few extra things that are only present in dev networks.

I created this PR (still in draft), to address the issue: #7997

@ChristopherDedominici how does this work in Hardhat 2, did chai matchers always assume you were running against an automine network?

Yes, in HH2 it works like that. Much of this code was inherited from Waffle, which worked only with Ganache.

Let's not block this PR on the other one though

…rted/utils.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

alcuadrado · 2026-02-24T14:17:14Z

Fixed the windows CI

kanej

Leaving the question of supporting non-automine situations aside, this looks good.

Can I check that the trick to improving the missing await error message is that chai has some inbuilt support for this, and that by changing across to chai's assertions we enable that?

alcuadrado · 2026-02-24T15:36:39Z

Can I check that the trick to improving the missing await error message is that chai has some inbuilt support for this, and that by changing across to chai's assertions we enable that?

hardhat-mocha adds an unhandledRejection listener that prints that if the unhandled rejection's error is an AssertionError.

alcuadrado added 4 commits February 24, 2026 00:40

[hardhat-mocha] Improve unhandled-rejection-mocha-hook

9f1760f

Use chai assertions with descriptive error messages instead of Hardha…

b2be122

…t invariants

Preseve all caught errors as cause

f9b3f04

Don't use HardhatError within assertions

683b3bd

alcuadrado requested review from Copilot and kanej February 24, 2026 00:45

Copilot AI reviewed Feb 24, 2026

View reviewed changes

Comment thread v-next/hardhat-ethers-chai-matchers/src/internal/matchers/reverted/utils.ts

Comment thread v-next/hardhat-ethers-chai-matchers/src/internal/matchers/reverted/utils.ts Outdated

alcuadrado added 2 commits February 24, 2026 00:46

Update lockfile

92284c5

Add changesets

33a3b44

alcuadrado added no docs needed This PR doesn't require links to documentation no peer bump needed labels Feb 24, 2026

alcuadrado requested a review from ChristopherDedominici February 24, 2026 00:56

kanej reviewed Feb 24, 2026

View reviewed changes

Comment thread v-next/hardhat-ethers-chai-matchers/src/internal/utils/balance.ts

kanej reviewed Feb 24, 2026

View reviewed changes

Comment thread v-next/hardhat-ethers-chai-matchers/src/internal/matchers/reverted/legacyReverted.ts

kanej reviewed Feb 24, 2026

View reviewed changes

Comment thread v-next/hardhat-ethers-chai-matchers/package.json

alcuadrado and others added 2 commits February 24, 2026 12:55

Fix the emit.ts module in the v5 workflow

34bdc97

Update v-next/hardhat-ethers-chai-matchers/src/internal/matchers/reve…

1f8b88a

…rted/utils.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

ChristopherDedominici mentioned this pull request Feb 24, 2026

[Chai-matchers] Add polling mechanism when automine is not available #7997

Merged

1 task

Fix addressable.ts so that it works on Chai v5 on Windows

692a28f

kanej approved these changes Feb 24, 2026

View reviewed changes

alcuadrado added this pull request to the merge queue Feb 24, 2026

Merged via the queue into main with commit b581d51 Feb 24, 2026
277 checks passed

alcuadrado deleted the fix-hardhat-ethers-chai-matchers branch February 24, 2026 16:00

github-actions Bot mentioned this pull request Feb 24, 2026

Version Packages (v3) #7987

Merged

Conversation

alcuadrado commented Feb 24, 2026

Uh oh!

changeset-bot Bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

hardhat

Uh oh!

alcuadrado commented Feb 24, 2026

Uh oh!

kanej Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

alcuadrado Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

ChristopherDedominici Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

kanej Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

alcuadrado Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

alcuadrado Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alcuadrado commented Feb 24, 2026

Uh oh!

kanej left a comment

Choose a reason for hiding this comment

Uh oh!

alcuadrado commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

changeset-bot Bot commented Feb 24, 2026 •

edited

Loading

github-actions Bot commented Feb 24, 2026 •

edited

Loading

alcuadrado commented Feb 24, 2026 •

edited

Loading