integration-singleton-isolation
Use when an integration or unit test mutates module-level state that outlives it, such as `await import('@/…')` for a side effect, a `bind*` or `set` call on an `export default new …` singleton, or an
SKILL.mdplugins/react-frontend-sdlc/skills/integration-singleton-isolation/SKILL.md
GitHubIntegration test isolation for module singletons
Profile keys consumed
make.test_integrationmake.test_unit_clientframework.diframework.stateframework.i18narchitecture.source_rootarchitecture.path_aliases
Run the affected suite through the target mapped by make.test_integration (or
make.test_unit_client for a unit file); skip with a recorded note when the key maps to null.
Overview
A module-level singleton keeps its state for the whole test file. A test that binds a source,
imports a module with side effects, or sets partial state leaks that mutation into every later test
in the file, producing assertions that only pass in one execution order. Reset in afterEach and
keep one behaviour per it.
When to use
- A test calls
await import('@/…')for the side effect, or abind*/setmethod on a singleton. - Adding a test to a
describeblock breaks an unrelated, previously green test. - An assertion passes only because a later mutation has not happened yet.
- A comment says "before X initializes" but nothing in the file pins that precedence.
- Not for: state already scoped per test by the runner (React Testing Library cleanup, a fresh
store created inside the test by
framework.state).
Applicability by repository shape
- React SPA shape (feature modules under the source root, a bootable app, an aggregate CI
target): yes — sixteen
export default new …singletons underarchitecture.source_root, exercised fromtests/integration/**; the locale-formatter core'sbindLanguageSourceis the canonical case. - Next.js app shape (routed pages, no aggregate duplication gate): partial — no
framework.disingleton layer, but the GraphQL client is a module-levelexport default clientthat readsi18n.languageat module evaluation; integration tests live intests/integration/{api,flows}. - Component-library shape (Storybook-first, no bootable app, published package): partial —
tests/integration/componentsholds composition tests only, so module-level mutable state is rare; the reset rule still applies where it exists.
Core pattern
Restore every process-level and singleton-level mutation after each test, and give each behaviour its own case:
import i18n from '@/i18n';
describe('locale formatter service (integration)', () => {
const ORIGINAL_ENV = { ...process.env };
const ORIGINAL_LANGUAGE = i18n.language;
const service = container.resolve<LocaleFormatter>(
LOCALE_FORMATTER_TOKENS.LocaleFormatterService
);
afterEach(async () => {
process.env = { ...ORIGINAL_ENV };
localeFormatterCore.bindLanguageSource(null);
await i18n.changeLanguage(ORIGINAL_LANGUAGE);
});
it('falls back to the environment main language while no source is bound', () => {
delete process.env.REACT_APP_MAIN_LANGUAGE;
expect(service.currency(1234.5)).toBe('1\u00A0234,50\u00A0₴');
});
it('prefers the bound language over the environment main language', async () => {
await i18n.changeLanguage('en');
localeFormatterCore.bindLanguageSource(i18n);
process.env.REACT_APP_MAIN_LANGUAGE = 'uk';
expect(service.currency(1234.5)).toBe('₴1,234.50');
});
});
The second test mutates three things: it binds the source, changes the shared i18n language, and
sets the environment variable the fallback reads. One afterEach reverses all three — unbind,
restore process.env, put the language back — so the first test passes whatever the order. Leaving
the language changed would be the same leak in a slower form: every later test in the run would
format against en. The @/… specifier is whichever alias architecture.path_aliases maps to the
source root.
Splitting and pinning
- Split a merged test. One
itthat asserts, mutates the singleton, then asserts again encodes its own ordering dependency. Twoitblocks with a sharedafterEachassert the same two behaviours and stay order-free. - Pin the precedence. When the resolver is a fallback chain (
explicit ?? bound ?? env), write one test that sets all three and asserts the winner. Reordering the chain then fails a test instead of silently changing behaviour. - Reset through the public API. Use the method the singleton exposes
(
bindLanguageSource(null),set(initialState)); do not reach into private fields, and do not clear the wholeframework.dicontainer — that invalidates spies captured at module load.
Common mistakes
- Resetting in
beforeEachonly — the last test in the file still leaves state behind for the next file when the runner shares a module registry. - Restoring
process.envbut not the singleton, the bound source, or a shared library's own state such as the active i18n language — reverse every mutation the test made, in oneafterEach. - Using
jest.resetModules()as the reset — it gives later tests a different singleton instance than the one the outerdescriberesolved. - Ordering tests so the file passes, instead of removing the dependency.