use-profiles

Using Playwright Authentication Profiles

Purpose

Load saved Playwright storageState authentication profiles before browser automation work. This eliminates the need to log in manually at the start of every browser session.

When This Applies

This skill applies when ALL of the following are true:

1. The current project has a .playwright/profiles.json file
2. Browser automation work is about to begin (using Playwright MCP tools)
3. The target page requires authentication

Profile Discovery

Check for .playwright/profiles.json at the project root. Read it to discover available profiles. The file contains entries like:

{
  "profiles": {
    "admin": {
      "loginUrl": "https://example.com/login",
      "description": "Full permissions"
    }
  }
}

Each profile has a corresponding storageState file at .playwright/profiles/<role-name>.json.

Profile Selection

Determine which profile to use based on conversation context:

• If the user mentions a specific role (e.g., "test the admin dashboard", "check the speaker view"), match it to a profile name from the config.
• If the user does not specify a role and only one profile exists, use it automatically.
• If the user does not specify a role and multiple profiles exist, ask which one to use. Present the available profiles with their descriptions.

Loading a Profile

Before navigating to any authenticated page, load and validate the profile:

1. Verify the storageState file exists at .playwright/profiles/<role-name>.json. If it does not exist, inform the user and suggest running /setup-profiles to create it.

2. Read the storageState JSON file. It contains cookies and origins (localStorage) arrays.

3. Pre-load health check (RT-08): Before injecting cookies, inspect the cookie health:

   • For any cookie whose value starts with base64- (Supabase auth): decode the base64 payload (Buffer.from(value.slice(7), 'base64').toString()), parse the JSON, and check expires_at. If expires_at < Date.now()/1000, the session is expired.
   • For any cookie whose value looks like a JWT (three dot-separated base64url segments): decode the middle segment, parse the JSON, and check exp. If exp < Date.now()/1000, the JWT is expired.
   • For standard cookies: check the expires field. If expires > 0 and expires < Date.now()/1000, the cookie is expired.
   • Count session-only cookies (expires <= 0). If >30% of cookies are session-only, note this.

   Report a summary: "Profile health: N valid, N expired, N session-only."

   If ALL auth-relevant cookies (names matching /auth|session|token|sid|jwt|identity|logged/i) are expired: Do not load the cookies. Instead, report: "All auth cookies in [role] profile are expired. Run /setup-profiles to refresh." Do not waste time loading dead cookies, navigating, and hitting a redirect.

   If some cookies are valid: Proceed to load them, but note the warnings.

4. Cross-contamination check (RT-10): Check the domains of all cookies in the profile. Extract unique domains. If cookies span more than 3 distinct domains that don't match the loginUrl hostname from the profile config, warn: "Profile contains cookies from N unrelated domains — consider recapturing with /setup-profiles for a cleaner profile."

5. Use browser_run_code (MCP tool: mcp__playwright__browser_run_code) to restore cookies only. Do NOT navigate to the app's origin to set localStorage first — this triggers client-side auth libraries (e.g., Supabase) that may clear the restored cookies.

   async (page) => {
     const state = STATE_JSON_HERE;
     await page.context().addCookies(state.cookies);
     return "Profile loaded";
   };
   

6. Navigate directly to the target authenticated page. The cookies will be sent with the request and the app will recognize the session.

Session Expiry Detection

After loading a profile and navigating to the target page, check whether the session is still valid. The primary heuristic: if the browser is redirected to a URL matching the loginUrl from the profile config, the session has likely expired.

If expiry is detected:

• Inform the user that the session for the profile appears to have expired
• Suggest running /setup-profiles to refresh it
• Do not attempt to log in automatically

This detection is best-effort. Not all apps redirect to the same login URL, so some expired sessions may not be caught by this heuristic. The user can always run /setup-profiles manually to refresh any profile.

Missing Profiles

If .playwright/profiles.json exists but references profiles whose storageState files are missing (e.g., after a fresh clone), inform the user:

"This project has Playwright profiles configured but the authentication state files are missing (they are gitignored and need to be created locally). Run /setup-profiles to authenticate."

No Profile Config

If .playwright/profiles.json does not exist, this skill does not apply. Do not suggest creating profiles unless the user is explicitly asking about authenticated browser automation.