A Playwright task can fail even when the script has not changed.
The proxy still works. The cookies still exist. The same user data directory still opens. But after another teammate, worker, or queue picks up the profile, the task lands in the wrong account, the wrong region, or a stale page state.
That is not always a Playwright problem.
It is often a browser profile handoff problem.
This post shows a small manifest, a Node.js preflight helper, and a few launch-time checks you can adapt before calling launchPersistentContext().
A browser profile is not just a folder. In team automation, it carries account state, cookies, local storage, proxy expectations, runtime assumptions, and the last task state.
This is the same layer covered in a broader browser workspace checklist: profile ownership, proxy binding, session state, task logs, review points, and handoff rules should be standardized before automation starts.
The failure mode
A common failure looks like this:
One teammate debugs a profile manually.
They leave it on a different page.
A queue worker later reuses the same profile.
The Playwright script assumes a clean dashboard state.
The browser starts from a modal, expired session, or partially completed flow.
The script retries and creates more noise.
The mistake is not just “someone touched the profile.” The mistake is that the next run had no way to prove whether the profile was safe to use.
What a profile handoff should prove
A good handoff should answer five questions before the script opens the first page:
- Who owns this profile now?
- Which browser runtime should open it?
- Which proxy or region does the profile expect?
- Is the login session still fresh enough?
- Where did the previous run stop?
Without those answers, the right script can run inside the wrong account context.
That is how teams get strange failures. A dashboard loads, but for the wrong account. A session appears valid, but the account has changed. A retry resumes from a page that needs human review.
The fix is not more retries.
The fix is to fail earlier.
Use a small handoff manifest
Start with a small manifest next to the profile metadata.
{
"profile_id": "acct-us-042",
"current_owner": "worker-group-a",
"handoff_to": "worker-group-b",
"expected_proxy_region": "US",
"browser_channel": "chromium",
"runtime_version": "stable-126",
"last_successful_step": "dashboard_loaded",
"last_run_id": "run-2026-07-08-1842",
"requires_human_review": false
}
This file should not be treated as documentation only. The automation runner should read it before launch.
The goal is simple: do not let a worker use a profile unless ownership, region, runtime, and recovery state are clear.
Add a preflight check
Here is a simplified Node.js helper. It assumes your team stores profile metadata and run evidence outside the Playwright script.
import fs from "node:fs/promises";
async function readJson(path) {
const content = await fs.readFile(path, "utf8");
return JSON.parse(content);
}
async function fileExists(path) {
try {
await fs.access(path);
return true;
} catch {
return false;
}
}
export async function preflightProfileHandoff({
manifestPath,
expectedWorker,
expectedRegion
}) {
const manifest = await readJson(manifestPath);
const failures = [];
if (manifest.handoff_to !== expectedWorker) {
failures.push({
gate: "ownership",
expected: expectedWorker,
actual: manifest.handoff_to
});
}
if (manifest.expected_proxy_region !== expectedRegion) {
failures.push({
gate: "proxy_region",
expected: expectedRegion,
actual: manifest.expected_proxy_region
});
}
if (manifest.requires_human_review) {
failures.push({
gate: "review_state",
reason: "Previous run requires human review"
});
}
if (!manifest.last_run_id) {
failures.push({
gate: "evidence",
reason: "No previous run id found"
});
}
const evidencePath = `./evidence/${manifest.last_run_id}/summary.json`;
if (!(await fileExists(evidencePath))) {
failures.push({
gate: "evidence",
reason: `Missing evidence file: ${evidencePath}`
});
}
return {
ok: failures.length === 0,
profile_id: manifest.profile_id,
failures
};
}
Use the result before calling chromium.launchPersistentContext().
const result = await preflightProfileHandoff({
manifestPath: "./profiles/acct-us-042/manifest.json",
expectedWorker: "worker-group-b",
expectedRegion: "US"
});
if (!result.ok) {
console.error("Profile handoff failed");
console.table(result.failures);
process.exit(1);
}
Then launch the persistent context only after the profile passes the handoff gates.
import { chromium } from "playwright";
const context = await chromium.launchPersistentContext(
"./profiles/acct-us-042/user-data",
{
channel: "chrome",
headless: false
}
);
const page = context.pages()[0] || await context.newPage();
The exact fields can change. The rule should not.
If the profile state is unclear, the runner should refuse to start.
Verify visible state after launch
A manifest protects the pre-launch stage. It does not prove that the page state is correct after the browser opens.
After launch, verify a few low-risk visible markers.
async function readVisibleAccountState(page) {
const accountName = await page
.locator("[data-testid='account-name']")
.textContent()
.catch(() => null);
const region = await page
.locator("[data-testid='region']")
.textContent()
.catch(() => null);
return {
accountName: accountName?.trim() || null,
region: region?.trim() || null
};
}
Then compare the result with the task expectation.
const visibleState = await readVisibleAccountState(page);
if (!visibleState.accountName) {
throw new Error("Missing visible account marker after launch");
}
if (visibleState.region !== "US") {
throw new Error(`Unexpected region: ${visibleState.region}`);
}
Do not depend only on cookies.
Cookies can exist while the login session is stale. Local storage can exist while the account has been switched. A profile can open correctly while the task starts from the wrong recovery point.
For handoff safety, visible confirmation matters.
Write evidence for the next run
After the first successful page load, create a new evidence folder for the run.
evidence/
run-2026-07-09-0930/
manifest.snapshot.json
handoff-result.json
first-page.png
console.log
network-summary.json
At minimum, store:
- profile id
- worker id
- runtime version
- proxy label or region
- start URL
- first visible account marker
- first screenshot
- previous run id
- stop reason
This gives the next person a starting point.
It also makes failures easier to discuss. Instead of saying “the profile broke,” the team can ask which gate failed.
Fail closed on unclear state
A handoff should fail closed when the assigned worker does not match the manifest.
It should fail closed when the proxy region does not match the task expectation.
It should fail closed when the previous run ended in a review-required state.
It should fail closed when evidence from the previous run is missing.
It should fail closed when the first visible account marker does not match the intended account.
That may feel strict, but it is cheaper than running a long automation task in an unknown account context.
Treat browser profiles as runtime assets
For Playwright teams, the lesson is simple:
A browser profile is a runtime asset, not just a user data directory.
When multiple people, workers, or AI agents can touch the same account environment, the handoff needs structure. Profile ownership, proxy mapping, session freshness, last-run evidence, and review state should be checked before the next script runs.
That is the difference between copying a folder and safely transferring task context.
In larger teams, this kind of handoff data usually belongs in a shared workspace layer, rather than inside scattered scripts. The practical goal is simple: keep profiles, proxies, task logs, review state, and handoff evidence visible before the next run starts.
Top comments (0)