Skip to content

Docs: Update deprecation testing guidance for shared reset #83989

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ciampo merged 1 commit into from
Oct 1, 2026
Merged

Docs: Update deprecation testing guidance for shared reset #83989

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 6 additions & 8 deletions packages/deprecated/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,14 +73,16 @@ _Type_

## Unit testing deprecations

Each deprecation message is logged only once per loaded instance of this package. The exported `logged` object tracks the full message text, so an earlier test can prevent a later test from observing the same warning. Resetting a console spy does not clear this state.
Each deprecation message is logged only once per loaded instance of this package. The exported `logged` object tracks the full message text. Resetting a console spy does not clear this state.

For a suite that exercises a deprecated feature, mark its message as logged in `beforeEach` to suppress it during tests of other behavior. Delete that entry before testing the warning itself, and clean it up in `afterEach` so tests do not depend on their execution order. Limit cleanup to the messages the suite uses.
Gutenberg's internal Vitest setup clears `logged` before each test in Node, jsdom, and Browser Mode. Suites do not need their own deprecation-history cleanup. If every test that triggers a deprecation asserts the warning, no interaction with `logged` is needed. A message still logs only once within a test. See [Expected console calls](/docs/contributors/code/testing-overview.md#expected-console-calls).

For a suite that exercises a deprecated feature, mark its message as logged in `beforeEach` to suppress it during tests of other behavior. Delete that entry before testing the warning itself.

This example uses Vitest and the `toHaveWarnedWith` matcher provided by Gutenberg's test setup:

```js
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { beforeEach, describe, expect, it } from 'vitest';
import deprecated, { logged } from '@wordpress/deprecated';

const DEPRECATION_MESSAGE = 'legacyFeature is deprecated.';
Expand All @@ -90,10 +92,6 @@ describe( 'legacyFeature', () => {
logged[ DEPRECATION_MESSAGE ] = true;
} );

afterEach( () => {
delete logged[ DEPRECATION_MESSAGE ];
} );

it( 'warns that the feature is deprecated', () => {
delete logged[ DEPRECATION_MESSAGE ];
deprecated( 'legacyFeature' );
Expand All @@ -105,7 +103,7 @@ describe( 'legacyFeature', () => {

Setting a `logged` entry also prevents the `deprecated` action from firing. Leave the entry absent when testing that action.

If every test that triggers a deprecation already asserts the warning, delete the message's entry in both `beforeEach` and `afterEach` instead of marking it as logged. This keeps the warning assertions independent without suppressing them.
If your test setup does not clear `logged`, an earlier test can prevent a later test from observing the same warning. Delete the entries for messages your suite uses in `beforeEach` and `afterEach` to keep tests independent. For tests that suppress a warning, set its entry in `beforeEach` instead of deleting it. Limit cleanup to the messages the suite uses.

## Contributing to this package

Expand Down
Loading