---
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`).

```ts
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`.

```ts
// OLD
const target = createTarget();
const targetManager = SDK.TargetManager.TargetManager.instance();

// NEW
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.

```ts
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:

```ts
beforeEach(async () => {
  universe = new TestUniverse();
  const {targetManager, workspace, settings} = universe;

  // 1. Stub globals so legacy helpers use TestUniverse components
  sinon.stub(Workspace.Workspace.WorkspaceImpl, 'instance').returns(workspace);
  sinon.stub(SDK.TargetManager.TargetManager, 'instance').returns(targetManager);
  sinon.stub(Common.Settings.Settings, 'instance').returns(settings);

  // 2. Initialize interdependent singletons in the correct order
  SDK.NetworkManager.MultitargetNetworkManager.instance({forceNew: true, targetManager});

  // 3. Now safe to use legacy helpers that rely on the above instances
  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`:

```ts
const emulateSpy = sinon.spy();
connection.setSuccessHandler('Network.emulateNetworkConditionsByRule', request => {
  emulateSpy(request);
  return {ruleIds: []};
});

// Matches only the fields you care about, ignoring extra protocol fields
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`:

1.  Change `devtools_module` to `devtools_foundation_module` for both the module and its unittests.
2.  Ensure the tests are grouped under a `foundation_unittests` target in the parent `BUILD.gn`.

```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
```bash
npm test -- front_end/core/sdk/NetworkManager.test.ts --node-unit-tests
```

### Run in Browser
```bash
npm test -- front_end/core/sdk/NetworkManager.test.ts
```
