| name | foundation-test-migration |
| description | Migrating unit tests to foundation unit tests using TestUniverse and devtools_foundation_module. Use when moving tests away from DOM-heavy helpers like describeWithEnvironment or describeWithMockConnection. |
Foundation Test Migration
This skill provides guidance on migrating DevTools unit tests to the "foundation" pattern, which is lighter, avoids global singletons, and is compatible with both Node and Browser runtimes (Isomorphic).
Core Concepts
devtools_foundation_module (BUILD.gn)
Use this template for modules that should be platform-agnostic.
- Enforcement: It type-checks the code against both Browser and Node APIs.
- Constraint: Avoid direct DOM access (like
FileReader or layout metrics) or heavy DevTools dependencies. Use Universe to access services.
TestUniverse
TestUniverse is the preferred way to setup a DevTools-like environment for tests without global singletons.
- Lazy: Dependencies (targetManager, settings, workspace, etc.) are only created when accessed via getters.
- Scoped: Does not install instances as globals (avoids
Common.Settings.Settings.instance()).
- Explicit: Uses
DevToolsContext to manage dependencies.
Migration Guide
1. Replace Heavy Helpers
Avoid describeWithEnvironment or describeWithMockConnection.
Instead, use standard describe and initialize environment hooks at the top-level describe block. Crucial: Without setupRuntimeHooks, tests creating SDK models will crash due to uninitialized experiments (e.g. capture-node-creation-stacks).
import {setupLocaleHooks} from '../../testing/LocaleHelpers.js';
import {setupSettingsHooks} from '../../testing/SettingsHelpers.js';
import {setupRuntimeHooks} from '../../testing/RuntimeHelpers.js';
import {TestUniverse} from '../../testing/TestUniverse.js';
describe('MyComponent', () => {
setupLocaleHooks();
setupSettingsHooks();
setupRuntimeHooks();
let universe: TestUniverse;
beforeEach(() => {
universe = new TestUniverse();
});
});
2. Access Dependencies via Universe
Instead of using SDK.TargetManager.TargetManager.instance(), use universe.targetManager. Use universe.createTarget() instead of the global createTarget.
const target = createTarget();
const targetManager = SDK.TargetManager.TargetManager.instance();
const target = universe.createTarget({url: urlString`http://example.com/`});
const targetManager = universe.targetManager;
Mocking CDP Traffic
If the test used describeWithMockConnection and global setMockConnectionResponseHandler to stub CDP traffic, you can migrate this by passing a MockCDPConnection to universe.createTarget(). This allows stubbing out CDP traffic scoped to a specific target tree rather than globally.
import {MockCDPConnection} from '../../testing/MockCDPConnection.js';
const cdpConnection = new MockCDPConnection([
{
method: 'Network.getResponseBody',
response: () => ({body: 'mocked body', base64Encoded: false}),
}
]);
const target = universe.createTarget({connection: cdpConnection});
[!TIP]
Legacy Target URLs: EnvironmentHelpers.createTarget() defaults to http://example.com/. TestUniverse.createTarget() defaults to about:blank. If your test asserts against specific URLs, remember to pass the URL explicitly.
3. Dealing with Legacy Singletons & Helpers
For large integration tests, you may encounter code that strictly calls SomeModule.instance() or uses complex legacy helpers (like createWorkspaceProject).
Do not use setUpEnvironment() as it will create disconnected singletons. Instead, wire the singletons to your TestUniverse and stub the globals to bridge legacy helpers:
beforeEach(async () => {
universe = new TestUniverse();
const {targetManager, workspace, settings} = universe;
sinon.stub(Workspace.Workspace.WorkspaceImpl, 'instance').returns(workspace);
sinon.stub(SDK.TargetManager.TargetManager, 'instance').returns(targetManager);
sinon.stub(Common.Settings.Settings, 'instance').returns(settings);
SDK.NetworkManager.MultitargetNetworkManager.instance({forceNew: true, targetManager});
await createWorkspaceProject(urlString`file:///path/to/overrides`, [...]);
});
Pitfalls & Troubleshooting
Strict Equality in Protocol Responses (assert.deepEqual)
Protocol requests/responses dynamically generated by Chrome (like Network conditions) can vary slightly (e.g., adding connectionType, urlPattern).
- Problem:
assert.deepEqual(rules, [{...}]) will flake if unrequested fields are present.
- Solution: Use
sinon.spy() for handlers and assert with sinon.assert.calledOnceWithMatch:
const emulateSpy = sinon.spy();
connection.setSuccessHandler('Network.emulateNetworkConditionsByRule', request => {
emulateSpy(request);
return {ruleIds: []};
});
sinon.assert.calledOnceWithMatch(emulateSpy, {
offline: false,
matchedNetworkConditions: [sinon.match({ downloadThroughput: 1000 })],
});
DOM Globals (ReferenceError: FileReader is not defined)
Foundation tests run in Node.js where window, FileReader, and certain DOM string encodings don't exist.
- Fix: Use isomorphic equivalents (e.g.
btoa(), Uint8Array).
- Fix: Abstract the APIs that are different between Node.js and Browser via
front_end/core/platform/api/HostRuntime.ts.
Initialization Order Lockups
If a test times out (5000ms exceeded), it is usually an unhandled promise caused by a missing singleton. Double-check the constructor of the failing manager to see which instance() it listens to, and ensure that dependent singleton was created first.
BUILD.gn Changes
When a module and its tests are ready, update BUILD.gn:
- Change
devtools_module to devtools_foundation_module for both the module and its unittests.
- Ensure the tests are grouped under a
foundation_unittests target in the parent BUILD.gn.
# front_end/my_module/BUILD.gn
devtools_foundation_module("my_module") {
sources = [ "MyModule.ts" ]
deps = [ "../../core/common:bundle" ]
}
devtools_foundation_module("unittests") {
testonly = true
sources = [ "MyModule.test.ts" ]
deps = [
":my_module",
"../../testing",
]
}
Verification
Foundation tests must pass in both Node.js and Browser runtimes.
Run in Node.js
npm test -- front_end/core/sdk/NetworkManager.test.ts --node-unit-tests
Run in Browser
npm test -- front_end/core/sdk/NetworkManager.test.ts