Playwright 1.63 Can Persist OPFS: Isolate Proxy Region Test State

Microsoft released Playwright 1.63 on September 4, 2026. The browser context storageState() API now has an opt-in opfs option that includes the origin private file system in a storage-state snapshot. That snapshot can be restored into a later browser context.

This is valuable when an authorized test depends on files that a web application stores in OPFS. It also expands the amount of browser state that a proxy-backed test can carry between runs. If one saved state is reused across countries, accounts or experiment groups, a result that appears geographic may actually come from previously restored local state.

Public source note: Microsoft Playwright, “Playwright v1.63.0,” released September 4, 2026; Microsoft Playwright, BrowserContext API reference, reviewed September 10, 2026.

What changed in Playwright 1.63

Playwright already supported saving cookies and local storage, with options for IndexedDB and virtual WebAuthn credentials. Version 1.63 adds OPFS as another explicit storage-state component:

const state = await context.storageState({
  path: statePath,
  opfs: true
});

The API reference says setting opfs to true includes the origin private file system in the snapshot. It also notes that OPFS is currently unsupported in ephemeral WebKit contexts.

The option is not enabled merely because storage state is saved. Teams must choose it. That makes upgrade review important: a helper or framework wrapper might start opting in even when an individual test does not visibly mention OPFS.

Why proxy test results can be contaminated

A proxy changes the network path and, depending on configuration, the apparent exit region. It does not automatically reset browser-side state. A restored OPFS snapshot belongs to an origin, and application logic may use those files alongside cookies, IndexedDB, local storage, server state or network signals.

Consider an authorized localization test:

1. a US run receives a market-specific catalog and writes processed data to OPFS;
2. the test saves storage state with OPFS included;
3. an EU run restores the same file;
4. the application reads cached local content before or instead of the new response;
5. the test reports that the EU proxy received US content.

The proxy may be functioning correctly. The browser cohort is not clean.

The reverse can also happen: a deliberately restored file may be necessary to reproduce a workflow. If the harness silently omits OPFS, the test can appear broken even though cookies and local storage were restored.

Inventory every state plane

Do not treat storageState.json as one undifferentiated login artifact. Record each component and why it is included:

Assign a sensitivity class and retention limit to every saved artifact. A state file that includes credentials or application data should not be committed to source control, printed in CI logs or reused outside its approved cohort.

Build a clean-versus-restored matrix

Upgrade testing should separate the route from the state. For every target region, run at least these cases:

1. clean browser context, direct control;
2. clean context through the regional proxy;
3. cookies-only state through the same proxy;
4. cookies plus IndexedDB, if the application requires it;
5. cookies plus OPFS, if OPFS is intentionally required;
6. state created in the same region and restored in that region;
7. state created in one region and restored in another as a negative test;
8. fresh account and existing account, when account state affects localization.

Keep the browser build, target URL, proxy route, viewport, locale, timezone, request headers and test data constant while changing one state dimension. Use the regional localized-price validation guide when currency, tax and market availability are part of the assertion.

Name state by cohort, not convenience

Avoid generic paths such as auth.json. Derive the artifact identity from the dimensions that are allowed to share state:

state/<environment>/<account-class>/<market>/<experiment>/<browser>.json

The path itself should contain no secret or personal identifier. Store the mapping in a protected manifest and record a digest for audit. Reject a job when the requested market, account class or experiment does not match the artifact manifest.

A useful manifest includes:

state_id
created_at
expires_at
environment
browser_build
origin_allowlist
market_cohort
account_class
experiment_id
includes_cookies
includes_indexeddb
includes_opfs
includes_credentials
artifact_digest

Prove whether OPFS changed the result

Use a controlled origin that you own or are authorized to test. Before saving state, write a benign canary file through the application’s normal behavior. Save one snapshot with OPFS and one without it. Restore each into a new context and assert whether the canary is available.

Then run the real workflow with content-level assertions. Compare:

• final URL and redirect chain;
• response status and selected headers;
• response or rendered-content digest;
• application-reported market and currency;
• exit region assertion;
• OPFS canary presence;
• server-side account state;
• screenshot or trace evidence after redaction.

Do not inspect or extract other users’ data. The goal is to validate your own state boundary, not to explore a target’s internal files.

Treat restored files as untrusted input

A saved OPFS snapshot can outlive the session that created it. Apply the same controls used for other test artifacts:

• encrypt it at rest and in transit;
• restrict access by environment and cohort;
• verify integrity before restoration;
• impose a short expiration time;
• prevent production state from entering lower environments;
• redact or exclude customer data;
• delete artifacts according to the approved retention policy;
• rotate the state after account or credential changes.

Do not make the artifact globally writable. Parallel workers should receive immutable inputs or isolated copies. Otherwise one test may mutate the state another test expects.

Distinguish browser support from test intent

The API reference explicitly notes an ephemeral WebKit limitation. Do not silently skip the OPFS assertion when a browser cannot support it. Mark the combination as unsupported, use a separate test design, or run the OPFS-dependent workflow on a supported browser while keeping the limitation visible.

Also avoid assuming browser engines serialize identical application behavior. Run a capability probe before the main suite and store the result with the browser build.

Upgrade rollout plan

1. Inventory every helper that calls storageState() or restores a saved state.
2. Pin Playwright 1.63 and the bundled browser builds in a canary environment.
3. Search generated state manifests for unexpected OPFS inclusion.
4. Run the clean-versus-restored matrix on controlled origins.
5. Confirm cohort keys prevent cross-region and cross-account reuse.
6. Test the ephemeral WebKit limitation explicitly.
7. Inspect CI logs, traces and uploaded artifacts for sensitive state.
8. Define failure gates for state mismatch, stale content and artifact leakage.
9. Roll out by one region or workload at a time.
10. Keep the prior build and state format available for rollback.

For network-path controls, pair this plan with the proxy response freshness validation guide so a restored local file is not mistaken for a fresh regional response.

Checklist

• [ ] OPFS inclusion is intentional and documented.
• [ ] Every storage-state component has an owner and retention limit.
• [ ] State artifacts are keyed by environment, account, market and experiment.
• [ ] Cross-cohort restoration is rejected by the harness.
• [ ] Clean and restored contexts are tested separately.
• [ ] OPFS presence is proven with an authorized canary.
• [ ] Regional proxy identity is verified independently of browser state.
• [ ] Content freshness and market assertions use more than one signal.
• [ ] Ephemeral WebKit is marked unsupported where applicable.
• [ ] Artifacts are encrypted, access-controlled and excluded from source control.
• [ ] Parallel workers cannot mutate a shared state file.
• [ ] A rollback path is documented.

FAQ

Does Playwright 1.63 include OPFS in every storage-state file?

No. The new opfs option is opt-in. Review shared helpers and wrappers because they may enable it centrally.

Does changing the proxy region clear OPFS?

No. A proxy affects network routing. Browser-side state must be isolated or restored deliberately by the test harness.

Can OPFS contain authentication material?

That depends on the application. Treat the snapshot as sensitive until its contents and purpose are classified. Do not assume that a file is harmless because it is not a cookie.

Why test a snapshot without OPFS?

It establishes whether cookies, IndexedDB or server-side state already explain the result. Changing one component at a time makes attribution possible.

Compliance note

Use proxy routes and browser automation only on systems and accounts you are authorized to test. Do not reuse state to bypass authentication, consent, regional controls, rate limits, purchase restrictions or anti-fraud systems. Minimize personal data, protect saved credentials and files, follow destination terms and privacy law, and delete test artifacts when their approved purpose ends.