fix: throw when TestClient.revert is given an invalid snapshot

evm_revert returns false for missing or already-consumed snapshot IDs
instead of a JSON-RPC error. Check that boolean and throw so failed
reverts are observable.

Closes #5064

Author: devtechedge

.changeset/revert-invalid-snapshot.md

@@ -0,0 +1,5 @@
+---
+"viem": patch
+---
+
+Fixed `TestClient.revert` swallowing invalid snapshot IDs.

site/pages/docs/actions/test/revert.md

@@ -6,6 +6,8 @@ description: Revert the state of the blockchain at the current block.
 
 Revert the state of the blockchain at the current block.
 
+Throws if the snapshot ID does not exist or has already been consumed.
+
 ## Usage
 
 :::code-group
@@ -43,4 +45,4 @@ The snapshot ID.
 await testClient.revert({
   id: '0x...' // [!code focus]
 })
-```
+```

src/actions/index.ts

@@ -414,6 +414,7 @@ export {
 export {
   type RevertErrorType,
   type RevertParameters,
+  type SnapshotRevertErrorType,
   revert,
 } from './test/revert.js'
 export {

src/actions/test/revert.test.ts

@@ -40,3 +40,22 @@ test('reverts', async () => {
     }),
   ).toBe(balance)
 })
+
+test('throws on an invalid snapshot id', async () => {
+  await expect(
+    revert(client, { id: '0xffffffffffffffff' }),
+  ).rejects.toMatchInlineSnapshot(`
+    [SnapshotRevertError: Failed to revert to snapshot "0xffffffffffffffff".
+
+    Docs: https://viem.sh/docs/actions/test/revert
+    Version: viem@x.y.z]
+  `)
+})
+
+test('throws when the snapshot has already been consumed', async () => {
+  const id = await snapshot(client)
+  await revert(client, { id })
+  await expect(revert(client, { id })).rejects.toThrowError(
+    `Failed to revert to snapshot "${id}"`,
+  )
+})

src/actions/test/revert.ts

@@ -3,6 +3,7 @@ import type {
   TestClientMode,
 } from '../../clients/createTestClient.js'
 import type { Transport } from '../../clients/transports/createTransport.js'
+import { BaseError } from '../../errors/base.js'
 import type { ErrorType } from '../../errors/utils.js'
 import type { Account } from '../../types/account.js'
 import type { Chain } from '../../types/chain.js'
@@ -14,7 +15,22 @@ export type RevertParameters = {
   id: Quantity
 }
 
-export type RevertErrorType = RequestErrorType | ErrorType
+export type SnapshotRevertErrorType = SnapshotRevertError & {
+  name: 'SnapshotRevertError'
+}
+export class SnapshotRevertError extends BaseError {
+  constructor({ id }: { id: Quantity }) {
+    super(`Failed to revert to snapshot "${id}".`, {
+      name: 'SnapshotRevertError',
+      docsPath: '/docs/actions/test/revert',
+    })
+  }
+}
+
+export type RevertErrorType =
+  | SnapshotRevertErrorType
+  | RequestErrorType
+  | ErrorType
 
 /**
  * Revert the state of the blockchain at the current block.
@@ -43,8 +59,9 @@ export async function revert<
   client: TestClient<TestClientMode, Transport, chain, account, false>,
   { id }: RevertParameters,
 ) {
-  await client.request({
+  const reverted = await client.request({
     method: 'evm_revert',
     params: [id],
   })
+  if (reverted === false) throw new SnapshotRevertError({ id })
 }

src/index.ts

@@ -406,6 +406,7 @@ export type { ResetErrorType, ResetParameters } from './actions/test/reset.js'
 export type {
   RevertErrorType,
   RevertParameters,
+  SnapshotRevertErrorType,
 } from './actions/test/revert.js'
 export type {
   SendUnsignedTransactionErrorType,

src/types/eip1193.ts

@@ -1595,12 +1595,13 @@ export type TestRpcSchema<mode extends string> = [
     ReturnType: Quantity
   },
   /**
-   * @description Revert the state of the blockchain to a previous snapshot. Takes a single parameter, which is the snapshot id to revert to.
+   * @description Revert the state of the blockchain to a previous snapshot. Takes a single parameter, which is the snapshot id to revert to. Returns `true` if the snapshot existed, `false` otherwise.
+   * @link https://hardhat.org/hardhat-network/docs/reference#evm_revert
    */
   {
     Method: 'evm_revert'
     Parameters?: [id: Quantity] | undefined
-    ReturnType: void
+    ReturnType: boolean
   },
   /**
    * @description Enables the automatic mining of new blocks with each new transaction submitted to the network.