Testing WebView2 without pretending it is a normal browser

The desktop test opens a settings window, finds a live debugging port, and still times out looking for the Save button. The attachment succeeded, but it landed on a blank WebView2 target created during startup instead of the product page. Adding ten seconds to the locator only makes the wrong connection fail more slowly.

That pattern is common because a WebView2 test crosses more boundaries than a normal browser test. The Windows host must start, the control must initialize with remote debugging enabled, a CDP endpoint must answer, and the intended web target must become visible. Only then does ordinary Playwright locator work begin.

Know what Playwright can actually control

A WebView2 desktop application has at least two relevant layers. The host is native Windows code, often WinForms, WPF, or WinUI. Inside that host, the WebView2 runtime renders HTML, CSS, and JavaScript with Microsoft Edge technology. Playwright reaches the second layer by attaching to the runtime through the Chrome DevTools Protocol.

That distinction decides what the test can prove. A locator can click a button rendered inside the document. It cannot click a WinForms toolbar that happens to sit above the WebView, dismiss a native update window, or inspect the host application's title bar. Those controls do not become DOM nodes merely because the same window also contains web content.

The app must opt into the connection before the WebView2 environment is created. Playwright's WebView2 guide documents two setup routes: put --remote-debugging-port=<port> in WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS, or pass the argument when the application creates its WebView2 environment. After that runtime is listening, chromium.connectOverCDP() can attach to an HTTP endpoint or its WebSocket URL.

This is not the same lifecycle as chromium.launch(). Playwright did not start the browser process with its curated launch arguments. It discovers an already running Chromium-based process and exposes the existing default browser context through browser.contexts(). The API documentation explicitly describes CDP attachment as significantly lower fidelity than a Playwright protocol connection. That warning should affect the test plan. Basic page actions and assertions are a reasonable starting point, while any advanced feature must be proven against the exact WebView2 Runtime and Playwright version used in CI.

A useful failure model has five checkpoints. First, did the host process remain alive? Second, did the WebView2 runtime publish the debugging endpoint? Third, did that endpoint list the expected target? Fourth, did the test select that target rather than another page? Fifth, did the product perform the user-visible result? Treating all five as “the Playwright test” hides the useful evidence.

Consider a desktop client that loads its main application at https://desktop.example.test/, then opens a native Preferences dialog. Playwright can test a web-rendered Preferences route if it becomes a CDP page or frame. It cannot assume that a native Preferences dialog is reachable. The same button label on screen does not make those surfaces equivalent.

The boundary also matters when a flow mixes layers. Suppose the web page contains an “Open certificate” button, while the host handles the click by opening a Windows certificate chooser. The click may succeed and the DOM may remain unchanged. Waiting for a web dialog event will not make the native chooser appear in Playwright because page.on('dialog') covers JavaScript dialogs such as alert, confirm, and prompt. A full test needs a deliberate handoff to a desktop automation tool, or the application needs an approved test route that supplies the certificate without navigating native UI.

This limitation is not a reason to abandon the approach. It is a reason to keep the claim narrow. WebView2 tests are valuable for integration defects that a normal Edge tab cannot reproduce: host-provided initialization, embedded navigation, runtime policy, profile behavior, and communication between the page and the desktop host. Regular browser tests should still carry most pure web behavior because they are faster to provision and easier to isolate.

Prove the endpoint and target before debugging locators

A refused connection is not a locator failure. Neither is an endpoint that answers but lists only a sign-in control when the test expects the main window. Diagnose the transport before changing test code.

Start with the HTTP discovery endpoints on the same Windows machine that launched the application. The command below makes no assertion about a page. It proves whether the selected port answers and prints the target inventory returned by that process.

#!/usr/bin/env bash
set -euo pipefail

endpoint="${WEBVIEW2_CDP_ENDPOINT:-http://127.0.0.1:9222}"

curl --fail --silent --show-error "${endpoint}/json/version"
printf '\n'
curl --fail --silent --show-error "${endpoint}/json/list"
printf '\n'

Run it while the desktop app is visibly open. If the first request cannot connect, inspect the host process exit code and its standard error before looking at Playwright. Confirm that the environment variable reached the process that creates WebView2, that the chosen port was unused, and that the flag was present before WebView2 initialization. Restarting only the test client will not repair an app that created its runtime without the flag.

A current curl build commonly reports a refused local connection with a line shaped like curl: (7) Failed to connect to 127.0.0.1 port 9222. The exact wording can vary by curl and operating system version, but the important fact is that no HTTP server accepted the request. By contrast, an HTTP response from /json/version shows that a CDP server is present. It does not prove that the expected application target exists.

The /json/list response gives the next useful facts: target type, title, URL, identifier, and a debugger WebSocket URL where available. Read the returned values from the run rather than copying an expected array into the test. An assertion against hard-coded diagnostic data cannot discover a missing target.

For repeatable CI evidence, keep a small helper that rejects an empty inventory and prints only fields needed for triage. Export it as an async function rather than a top-level script body. Top-level await is available in an ES module you run directly, but not inside a hook callback, so the function form is the one you can await from global setup, from an afterEach failure hook, and from a standalone script alike.

type CdpTarget = {
  id?: string;
  type?: string;
  title?: string;
  url?: string;
  webSocketDebuggerUrl?: string;
};

export async function reportCdpTargets(
  endpoint = process.env.WEBVIEW2_CDP_ENDPOINT ?? 'http://127.0.0.1:9222',
): Promise<CdpTarget[]> {
  const response = await fetch(endpoint + '/json/list');
  if (!response.ok) {
    throw new Error(
      'CDP target discovery returned HTTP ' +
        response.status +
        ' ' +
        response.statusText,
    );
  }

  const targets = (await response.json()) as CdpTarget[];
  if (targets.length === 0) {
    throw new Error('CDP endpoint is ready, but it returned no targets');
  }

  console.table(
    targets.map(target => ({
      id: target.id ?? '<missing>',
      type: target.type ?? '<missing>',
      title: target.title ?? '<missing>',
      url: target.url ?? '<missing>',
      hasWebSocketUrl: Boolean(target.webSocketDebuggerUrl),
    })),
  );

  return targets;
}

This helper has a real failure path. It fails if discovery returns a non-success status or an empty target list, and it displays live target data otherwise. It does not claim that any target is the product page. The actual test must make that decision with product-specific identity.

Timing produces a near-miss that looks like a bad port. The host may be running while WebView2 is still initializing, so the endpoint refuses connections for a short period and then appears. Poll discovery with a bounded deadline instead of sleeping for an arbitrary fixed delay. A bounded poll ends as soon as the endpoint is ready and still fails with a transport-specific message if readiness never arrives.

A different near-miss occurs when another process already owns the selected port. In that case, /json/version can return valid Chromium information and connectOverCDP() can succeed, but /json/list contains unrelated tabs. Record the app process ID, selected port, and target URLs together. A green handshake against somebody else's browser is worse than a clean connection refusal because the suite proceeds with false confidence.

Application logs make readiness more precise. If the host owns the code, emit a line after CoreWebView2InitializationCompleted reports success, and include the case identifier without secrets. That log establishes WebView initialization, while the HTTP probe establishes CDP availability. Neither substitutes for the other. A successful initialization event with no port suggests launch configuration. A live port with no intended page suggests target creation or navigation.

Do not log the complete WebSocket debugger URL into broadly retained output unless your security review allows it. The endpoint grants powerful control over the attached content. CI artifacts should contain enough information to identify the runtime and target without turning a debugging channel into a reusable credential.

Attach to the right WebView, not the first page

The shortest sample uses browser.contexts()[0].pages()[0]. That is acceptable for a tiny demonstration with one control and one page. It is a weak identity rule for a desktop product.

Several legitimate targets can exist at once. An app might create a splash WebView, an authentication WebView, the primary client, and a hidden help surface. Startup timing can also leave the primary target at about:blank before it navigates. Taking the first array entry says nothing about which product surface the test controls.

Select by something the application owns. A stable URL prefix is better than array position. Pair it with a DOM marker such as the product heading or a test-safe build identifier. The URL distinguishes the target, while the marker catches a server that accidentally serves the wrong page at the expected origin.

The fixture below launches one app for each test, assigns a fresh profile directory, waits for the CDP endpoint, attaches to the default context, and waits for a matching target URL. It also captures host output and discovered pages in Playwright attachments. Replace the sample executable path and URL prefix with values from your application.

import {
  test as base,
  expect,
  type Browser,
  type BrowserContext,
  type Page,
} from '@playwright/test';
import {
  execFileSync,
  spawn,
  type ChildProcessWithoutNullStreams,
} from 'node:child_process';
import {
  accessSync,
  constants,
  mkdtempSync,
  rmSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';

const appPath = process.env.WEBVIEW2_APP_PATH;
if (!appPath) {
  throw new Error('WEBVIEW2_APP_PATH must point to the desktop app executable');
}
accessSync(appPath, constants.X_OK);

async function waitForCdp(
  endpoint: string,
  child: ChildProcessWithoutNullStreams,
  timeoutMs = 20_000,
): Promise<void> {
  const deadline = Date.now() + timeoutMs;
  let lastError = 'CDP endpoint did not answer';

  while (Date.now() < deadline) {
    if (child.exitCode !== null) {
      throw new Error('Desktop app exited with code ' + child.exitCode);
    }

    try {
      const response = await fetch(endpoint + '/json/version');
      if (response.ok) return;
      lastError = 'CDP discovery returned HTTP ' + response.status;
    } catch (error) {
      lastError = error instanceof Error ? error.message : String(error);
    }

    await new Promise(resolve => setTimeout(resolve, 200));
  }

  throw new Error('WebView2 CDP readiness timed out: ' + lastError);
}

function urlForEvidence(rawUrl: string): string {
  try {
    const url = new URL(rawUrl);
    if (url.protocol === 'http:' || url.protocol === 'https:') {
      return url.origin + url.pathname;
    }
    return url.protocol === 'about:'
      ? url.protocol + url.pathname
      : url.protocol + '<redacted>';
  } catch {
    return '<unparseable-url>';
  }
}

async function waitForTarget(
  context: BrowserContext,
  urlPrefix: string,
  timeoutMs = 20_000,
): Promise<Page> {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const page = context.pages().find(candidate =>
      candidate.url().startsWith(urlPrefix),
    );
    if (page) return page;
    await new Promise(resolve => setTimeout(resolve, 100));
  }

  throw new Error(
    'No WebView2 page matched ' +
      JSON.stringify(urlPrefix) +
      '. Saw: ' +
      JSON.stringify(context.pages().map(page => urlForEvidence(page.url()))),
  );
}

export const test = base.extend<{ webViewPage: Page }>({
  webViewPage: async ({ playwright }, use, testInfo) => {
    const portBase = Number(
      process.env.WEBVIEW2_CDP_PORT_BASE ?? '12000',
    );
    if (!Number.isInteger(portBase)) {
      throw new Error('WEBVIEW2_CDP_PORT_BASE must be an integer');
    }

    const port = portBase + testInfo.workerIndex;
    const endpoint = 'http://127.0.0.1:' + port;
    const profileDir = mkdtempSync(
      path.join(tmpdir(), 'webview2-' + testInfo.workerIndex + '-'),
    );
    const targetUrlPrefix =
      process.env.WEBVIEW2_TARGET_URL_PREFIX ??
      'https://desktop.example.test/';

    const child = spawn(appPath, [], {
      env: {
        ...process.env,
        WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS:
          '--remote-debugging-port=' + port,
        WEBVIEW2_USER_DATA_FOLDER: profileDir,
      },
      stdio: 'pipe',
      windowsHide: true,
    });

    const started = new Promise<void>((resolve, reject) => {
      child.once('spawn', resolve);
      child.once('error', reject);
    });

    let stdout = '';
    let stderr = '';
    child.stdout.on('data', chunk => {
      stdout += chunk.toString();
    });
    child.stderr.on('data', chunk => {
      stderr += chunk.toString();
    });

    let browser: Browser | undefined;
    try {
      await started;
      await waitForCdp(endpoint, child);
      browser = await playwright.chromium.connectOverCDP(endpoint);

      const context = browser.contexts()[0];
      if (!context) {
        throw new Error(
          'CDP connection exposed no default browser context',
        );
      }

      const page = await waitForTarget(context, targetUrlPrefix);
      await testInfo.attach('webview2-targets.json', {
        body: Buffer.from(
          JSON.stringify(
            context.pages().map(candidate => ({
              selected: candidate === page,
              url: urlForEvidence(candidate.url()),
            })),
            null,
            2,
          ),
        ),
        contentType: 'application/json',
      });

      await use(page);
    } finally {
      await testInfo.attach('webview2-host-stdout.txt', {
        body: Buffer.from(stdout),
        contentType: 'text/plain',
      });
      await testInfo.attach('webview2-host-stderr.txt', {
        body: Buffer.from(stderr),
        contentType: 'text/plain',
      });

      if (browser) {
        await browser.close().catch(() => {});
      }

      if (child.pid && child.exitCode === null) {
        try {
          execFileSync('taskkill', [
            '/PID',
            String(child.pid),
            '/T',
            '/F',
          ]);
        } catch {
          if (child.exitCode === null) {
            throw new Error(
              'Failed to terminate WebView2 host process tree',
            );
          }
        }
      }

      rmSync(profileDir, { recursive: true, force: true });
    }
  },
});

export { expect } from '@playwright/test';

The fixture deliberately does not call context.close(). CDP exposes the existing default context, and Playwright documents that the default browser context cannot be closed. Calling browser.close() on a connected browser disposes the Playwright connection; the separate taskkill step owns termination of the Windows host process tree.

The URL helper removes queries and fragments before attaching target evidence. The fixture still attaches host standard output and error exactly as the app emits them, so use that part only with a test logging mode that excludes secrets or apply an application-specific redactor before testInfo.attach().

The URL selection can still be too broad. If two windows share the same origin, add a path segment or another stable application identifier. Do not select by a translated title if CI runs multiple locales. Do not use visible text alone before identifying the target because an authentication page can contain the same brand heading as the main client.

Here is a product assertion that can fail for a meaningful regression. It confirms both the page identity and the persisted user result. It does not pass merely because the connection returned an object.

import { test, expect } from './webview2.fixture';

test('saves the API server address', async ({ webViewPage }) => {
  await expect(
    webViewPage.getByRole('heading', {
      name: 'Connection settings',
    }),
  ).toBeVisible();

  await webViewPage
    .getByRole('textbox', { name: 'API server address' })
    .fill('https://api.staging.example.test');

  await webViewPage
    .getByRole('button', { name: 'Save settings' })
    .click();

  await expect(webViewPage.getByRole('status')).toHaveText(
    'Connection settings saved',
  );
  await expect(
    webViewPage.getByRole('textbox', {
      name: 'API server address',
    }),
  ).toHaveValue('https://api.staging.example.test');
});

A change that removes the heading, prevents the save, changes the status, or loses the value makes this test fail. The oracle is tied to observable product state, not to the hard-coded fixture setup.

Target replacement is another failure mode worth testing. Some desktop apps destroy the sign-in WebView and create a new main WebView after authentication. A stored Page from before sign-in can close even though the application looks healthy. Listen for a new page in the existing context or reacquire by URL after the transition. Evidence for this case is a page.on('close') event followed by a new entry in context.pages(), not a slow locator on the old object.

A web popup can look similar but leaves different evidence. window.open() creates another Playwright Page in the context. A same-page navigation changes the existing page URL. A native desktop window does neither. Recording those events turns three visually similar outcomes into separate branches instead of one generic timeout.

Isolate ports and profiles before running in parallel

Two isolated CDP ports can still share browser state. WebView2 uses a user data folder for cookies, local storage, caches, permissions, and other runtime data. Playwright's WebView2 guide warns that the default folder is shared across instances and recommends a separate WEBVIEW2_USER_DATA_FOLDER for each test.

Shared state creates failures that are convincing for the wrong reason. A first-run test skips onboarding because a previous test completed it. An authentication test starts already signed in. One worker clears site data while another worker is saving settings. Retrying often passes because the competing process has finished, which hides the contamination rather than fixing it.

A fresh folder per test gives the strongest isolation, as the fixture above does with mkdtempSync(). The cost is startup time. Every test creates a desktop process, initializes WebView2, attaches over CDP, then tears the process down. On a large suite, that cost can dominate the assertions.

A worker-scoped app is faster, but every test handled by that worker shares the profile and host lifetime. Use that design only when the suite has a tested reset operation. “The tests do not normally change state” is not a reset operation. Add a canary that reads real storage or a first-run product marker before each scenario and fails when residue exists.

For example, an onboarding suite can check the actual storage key the application owns before triggering onboarding. This is not a fabricated fixture check because leaked state changes the value.

import { test, expect } from './webview2.fixture';

test('a fresh profile has not completed onboarding', async ({
  webViewPage,
}) => {
  await expect
    .poll(() =>
      webViewPage.evaluate(() =>
        window.localStorage.getItem('onboardingCompleted'),
      ),
    )
    .toBeNull();

  await expect(
    webViewPage.getByRole('heading', {
      name: 'Welcome to Desktop Client',
    }),
  ).toBeVisible();
});

Choose the key or public UI marker from the application, not from an article. If the product stores onboarding state elsewhere, the test must read that real source or assert the first-run screen. The assertion should fail when a previous run leaves the profile dirty.

Profile isolation does not isolate the backend. Two pristine WebView2 folders can sign in as the same server account and edit the same record. That near-miss produces state leakage even though local cookies and storage are clean. Distinguish it by recording the profile directory, test account identity, and created record identifier. If local storage starts empty but the server immediately returns an old record, fix backend test data rather than rotating another user data folder.

Port isolation has a separate scope. Within one Playwright process, workerIndex gives concurrent workers different offsets. Across two test commands on the same Windows machine, both commands can have worker zero and choose the same base. Give each job a non-overlapping base, reserve ports through the runner, or serialize those jobs. A random number is not a reservation and can collide under load.

Avoid a fixed global 9222 once the suite runs concurrently. The familiar number makes local troubleshooting convenient, but convenience is not ownership. Put the selected endpoint in a per-test attachment so a failure can be matched to its host process and profile without guessing.

Cleanup is part of isolation. Disconnecting Playwright does not prove that the native host and its WebView2 child processes stopped. Check the spawned process tree, terminate it through the harness, and remove the profile directory only after the processes release it. A locked directory at teardown is useful evidence of a lifecycle problem. Silently leaving it behind gives the next run an unplanned source of state and consumes disk on long-lived agents.

There is a trade-off in strict cleanup failures. Failing the test when profile removal fails can mask the original product assertion in a terse reporter. Ignoring cleanup makes future tests unreliable. Keep the original assertion and cleanup result as separate attachments, then fail the job if either contract breaks. A reporter that preserves both errors is worth configuring before broad rollout.

Separate web failures from native desktop failures

A timeout after a click can mean the page never updated, the host opened native UI, the selected WebView was replaced, or a JavaScript dialog blocked progress. The screenshots can look nearly identical when the native window covers the embedded page. Event evidence tells them apart.

Attach listeners before the action. Capture page creation, closure, navigation, console errors, and uncaught page errors. These logs are small enough to keep on every failed run and do not depend on a screenshot catching the right instant.

import type {
  BrowserContext,
  Page,
  TestInfo,
} from '@playwright/test';

export async function recordWebViewEvents(
  context: BrowserContext,
  page: Page,
  testInfo: TestInfo,
): Promise<() => Promise<void>> {
  const events: string[] = [];
  const urlForLog = (rawUrl: string): string => {
    try {
      const url = new URL(rawUrl);
      if (url.protocol === 'http:' || url.protocol === 'https:') {
        return url.origin + url.pathname;
      }
      return url.protocol === 'about:'
        ? url.protocol + url.pathname
        : url.protocol + '<redacted>';
    } catch {
      return '<unparseable-url>';
    }
  };
  const stamp = (message: string) => {
    events.push(new Date().toISOString() + ' ' + message);
  };

  context.on('page', opened =>
    stamp('page opened ' + urlForLog(opened.url())),
  );
  page.on('close', () => stamp('selected page closed'));
  page.on('framenavigated', frame => {
    if (frame === page.mainFrame()) {
      stamp('navigated ' + urlForLog(frame.url()));
    }
  });
  page.on('console', message => {
    if (message.type() === 'error') {
      stamp('console error ' + message.text());
    }
  });
  page.on('pageerror', error =>
    stamp('page error ' + error.message),
  );

  return async () => {
    await testInfo.attach('webview2-events.log', {
      body: Buffer.from(events.join('\n') + '\n'),
      contentType: 'text/plain',
    });
  };
}

This helper is diagnostic rather than an oracle. Call the returned function in test teardown so the events survive a failed assertion. It identifies whether the selected page navigated or closed, but the product test must still assert the intended outcome.

The Playwright trace, when tracing works for the attached runtime and version, gives another view. Check the action immediately before the timeout. Inspect the locator resolution, the before and after DOM snapshots, the page URL, console output, and relevant network requests. A click recorded against the intended element followed by an unchanged DOM is different from a click that never resolved a locator. Validate trace collection in a pilot because CDP attachment is documented as lower fidelity, and retain host logs even when a trace is available.

A native modal leaves a characteristic gap. The host log may report that it opened a Windows window, while context.pages() gains no page and the selected DOM snapshot stays at the pre-action state. A desktop-level screenshot can confirm the modal. Playwright's page screenshot is not a substitute for an operating system screenshot because it captures the web page, not every native window placed above it.

A JavaScript dialog differs in one decisive way: Playwright emits the page dialog event. Without a listener, Playwright normally dismisses page dialogs automatically; with a listener, that listener must accept or dismiss them. If a registered listener only logs the dialog and never handles it, later actions can stall. Check event handlers before blaming WebView2.

An iframe is another near-miss. Content rendered in a frame remains web content and appears in page.frames(). A frame locator can reach it even when a top-level locator cannot. If the expected URL appears as a child frame, fix frame selection. If no target or frame exists and the host opened a native surface, changing CSS selectors will not help.

Host-to-web messaging deserves its own assertion boundary. A web button may send a message to the native host, which later responds by injecting state into the page. The click proves only the first half. Assert the visible response in the web content, and have the host log a correlation identifier for the received message. If the host logs receipt but the page never changes, investigate the response bridge. If the host sees nothing while the DOM click succeeded, investigate message registration or payload construction.

Do not infer host behavior from a successful page.evaluate(). Evaluation proves that JavaScript ran in the selected document. It says nothing about a native service, system tray action, file write, or registry change unless the application exposes a truthful result back to the page. When the product promise is native, verify it at that layer.

Trace contents also need privacy review. WebView snapshots and network details can contain account data, server addresses, or tokens. Retaining every trace from every successful desktop test may be unnecessary. Keep failure evidence long enough for triage, redact host logs at their source, and never print secrets merely to make a target easier to identify.

Roll the harness into CI without hiding the costs

Start on a Windows runner with one worker and one end-to-end scenario. The first objective is not maximum throughput. It is proving that the packaged desktop app launches unattended, the runtime exposes CDP, the correct target appears, and teardown leaves the machine clean.

The workflow below avoids relying on a pre-existing interactive session. It builds a sample .NET desktop project, installs the JavaScript dependencies after enabling Corepack, and runs only the WebView2 tests. Adapt the project and executable paths to the repository. The structure is runnable once those paths name the actual app.

name: webview2-e2e

on:
  workflow_dispatch:
  pull_request:
    paths:
      - "src/DesktopApp/**"
      - "tests/webview2/**"
      - "playwright.config.ts"
      - "pnpm-lock.yaml"

jobs:
  webview2:
    runs-on: windows-2022
    timeout-minutes: 30

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: "8.0.x"

      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Enable pnpm through Corepack
        shell: pwsh
        run: corepack enable

      - name: Install JavaScript dependencies
        shell: pwsh
        run: pnpm install --frozen-lockfile

      - name: Build the desktop app
        shell: pwsh
        run: >
          dotnet build .\src\DesktopApp\DesktopApp.csproj
          --configuration Release

      - name: Run WebView2 tests
        shell: pwsh
        run: >
          pnpm exec playwright test tests/webview2
          --workers=1
        env:
          WEBVIEW2_APP_PATH: ${{ github.workspace }}\src\DesktopApp\bin\Release\net8.0-windows\DesktopApp.exe
          WEBVIEW2_CDP_PORT_BASE: "12000"
          WEBVIEW2_TARGET_URL_PREFIX: "https://desktop.example.test/"

      - name: Keep failure evidence
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: webview2-test-results
          path: test-results/
          if-no-files-found: warn

The Node setup intentionally does not request pnpm caching before Corepack makes pnpm available. Add package-manager caching only after verifying the runner order used by the chosen action version. A cache optimization should not become the reason the desktop job never reaches the application.

One worker is a rollout constraint, not the final architecture. It removes port and profile concurrency while the team learns the runtime's failure signatures. Once the serial job is stable, enable two workers with separate ports and fresh profiles. Then add a second simultaneous job only after giving each process a distinct port range or a real reservation mechanism.

Retries should remain off during the pilot. A retry can tell you that a failure is intermittent, but it cannot make the first attempt trustworthy. If the wider repository requires retries, retain the first attempt's target inventory, host output, event log, and trace independently. Report “passed on retry” as flaky rather than merging it into an ordinary pass.

Split timeouts by boundary. The app launch and CDP readiness poll need one deadline. Target discovery needs another. Product locators use Playwright's action and assertion timeouts. When a job fails, the message should say which deadline expired. Raising the test timeout globally makes an exited process, missing target, and slow server look identical.

Runtime coverage costs machine time. A fixed WebView2 Runtime can give release reproducibility, while the evergreen runtime represents what many installed clients receive. The right matrix depends on how the product ships. Do not invent a version matrix because it sounds comprehensive. Ask which runtime distribution is supported, then test the versions that map to that support policy.

The desktop process should run under a test account with no valuable local data. Remote debugging is a privileged channel. Keep the endpoint local to the runner, avoid production hosts, and stop the process after every test. If a security control forbids remote debugging in the shipping build, use a test build or approved launch configuration rather than weakening the production policy.

A practical migration begins with observation. Add endpoint discovery and target logging to one existing smoke test without changing its assertions. Next, replace pages()[0] with stable target selection. Then introduce unique user data folders and make cleanup failures visible. Finally, parallelize in small increments while watching whether failures cluster around port ownership, profile deletion, or backend data.

Each improvement has a price. Stable target selection needs an application-owned URL or marker. Per-test profiles add startup latency and disk churn. Process-tree cleanup adds Windows-specific harness code. Rich attachments increase artifact size and privacy obligations. CDP attachment itself carries compatibility risk compared with a browser Playwright launches. Those costs are acceptable when the test covers a WebView2 integration risk that a normal browser cannot cover. They are waste when the scenario is only checking ordinary web rendering.

Know when a different tool is the right answer

Do not use this setup to claim full desktop automation. If acceptance depends on native menus, system tray behavior, Windows accessibility properties, drag operations across native controls, or operating system dialogs, add a Windows desktop automation layer. Playwright can remain responsible for the embedded web surface, but one tool should not be credited with evidence collected by another.

Avoid CDP attachment for most pure web scenarios. If the same page can run in a normal Chromium, Firefox, or WebKit test, use regular Playwright projects for broad functional and cross-browser coverage. Keep a smaller WebView2 suite for the integration points created by embedding: startup, host messaging, navigation policy, profile choice, and runtime packaging. This division produces faster feedback without dropping the desktop-specific risks.

Do not attach to an arbitrary third-party desktop application merely because it uses WebView2. The app must expose a debugging endpoint, and the owner must authorize that test access. A port discovered on a developer machine is not permission to automate the process. For software you do not control, use a supported automation interface and a test environment approved by its owner.

Skip the approach when the application cannot produce a stable target identity. A test that guesses among several identical WebViews can pass against the wrong window. Ask the app team for a stable virtual-host URL, a test-safe path, or another observable identifier. If adding that identity is impossible, keep the scenario manual or choose a protocol that can select the intended instance reliably.

Do not use a shared production-like profile to save startup time. The profile may contain credentials, customer data, cached permissions, or extensions unrelated to the test. It also makes failures order-dependent. Create disposable test state and seed only what the scenario needs.

A regular browser mock is not a replacement when the bug lives in the host bridge. Conversely, a full desktop journey is an expensive way to validate a CSS change. Put the test at the lowest layer that can expose the defect. A JavaScript unit test can cover message serialization. A browser test can cover the page reaction to a simulated message. A WebView2 integration test can prove that the real host and embedded page exchange it. A desktop test can prove that a native control triggers the entire chain.

Finally, stop if the team cannot retain enough evidence to distinguish connection, target, web, and native failures. A flaky desktop job with only “timeout exceeded” teaches nobody which boundary broke. Add the process exit code, endpoint probe, live target inventory, selected URL, product assertion, and cleanup result before making the job a release gate. That evidence is the difference between a useful WebView2 test and a browser script pointed at a desktop process.