feat: Don’t use Playwright’s BrowserContext options object format directly; introduce AuthContext abstraction

Author: smockle

.github/actions/auth/README.md

@@ -23,6 +23,6 @@ Authenticate with Playwright and save session state. Supports HTTP Basic and for
 
 ### Outputs
 
-#### `playwright_context_options`
+#### `auth_context`
 
-Stringified JSON object containing [Playwright `BrowserContext`](https://playwright.dev/docs/api/class-browsercontext) options, including `httpCredentials` and `storageState`. For example: `{"httpCredentials":{"username":"some-user",password:"correct-horse-battery-staple"},"storageState":"/tmp/.auth/12345678/sessionState.json"}`
+Stringified JSON object containing `username`, `password`, `cookies`, and/or `localStorage` from an authenticated session. For example: `{"username":"some-user","password":"correct-horse-battery-staple","cookies":[{"name":"theme-preference","value":"light","domain":"primer.style","path":"/"}],"localStorage":{"https://primer.style":{"theme-preference":"light"}}}`

.github/actions/auth/action.yml

@@ -13,8 +13,8 @@ inputs:
     required: true
 
 outputs:
-  playwright_context_options:
-    description: "Stringified JSON object containing Playwright 'BrowserContext' options, including 'httpCredentials' and 'storageState'"
+  auth_context:
+    description: "Stringified JSON object containing 'username', 'password', 'cookies', and/or 'localStorage' from an authenticated session"
 
 runs:
   using: "node20"

.github/actions/auth/src/index.ts

@@ -1,3 +1,4 @@
+import type { AuthContextOutput } from "./types.d.js";
 import crypto from "node:crypto";
 import process from "node:process";
 import * as url from "node:url";
@@ -67,16 +68,22 @@ export default async function () {
       // This occurs if HTTP Basic auth succeeded, or if the page does not require authentication.
     }
 
-    // Write authenticated session state to a file and output its path
-    await context.storageState({ path: sessionStatePath });
-    core.info(`Wrote authenticated session state to ${sessionStatePath}`);
-    core.setOutput(
-      "playwright_context_options",
-      JSON.stringify({
-        httpCredentials: { username, password },
-        storageState: sessionStatePath,
-      })
-    );
+    // Output authenticated session state
+    const { cookies, origins } = await context.storageState();
+    const authContextOutput: AuthContextOutput = {
+      username,
+      password,
+      cookies,
+      localStorage: origins.reduce((acc, { origin, localStorage }) => {
+        acc[origin] = localStorage.reduce((acc, { name, value }) => {
+          acc[name] = value;
+          return acc;
+        }, {} as Record<string, string>);
+        return acc;
+      }, {} as Record<string, Record<string, string>>),
+    };
+    core.setOutput("auth_context", JSON.stringify(authContextOutput));
+    core.debug("Output: 'auth_context'");
   } catch (error) {
     if (page) {
       core.info(`Errored at page URL: ${page.url()}`);

.github/actions/auth/src/types.d.ts

@@ -0,0 +1,23 @@
+export type Cookie = {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+};
+
+export type LocalStorage = {
+  [origin: string]: {
+    [key: string]: string;
+  };
+};
+
+export type AuthContextOutput = {
+  username?: string;
+  password?: string;
+  cookies?: Cookie[];
+  localStorage?: LocalStorage;
+};

.github/actions/find/README.md

@@ -15,9 +15,9 @@ https://primer.style
 https://primer.style/octicons/
 ```
 
-#### `playwright_context_options`
+#### `auth_context`
 
-**Optional** Stringified JSON object containing [Playwright `BrowserContext`](https://playwright.dev/docs/api/class-browsercontext) options, including `httpCredentials` and `storageState`. For example: `{"httpCredentials":{"username":"some-user",password:"correct-horse-battery-staple"},"storageState":"/tmp/.auth/12345678/sessionState.json"}`
+**Optional** Stringified JSON object containing `username`, `password`, `cookies`, and/or `localStorage` from an authenticated session. For example: `{"username":"some-user","password":"correct-horse-battery-staple","cookies":[{"name":"theme-preference","value":"light","domain":"primer.style","path":"/"}],"localStorage":{"https://primer.style":{"theme-preference":"light"}}}`
 
 ### Outputs
 

.github/actions/find/action.yml

@@ -6,8 +6,8 @@ inputs:
     description: "Newline-delimited list of URLs to check for accessibility issues"
     required: true
     multiline: true
-  playwright_context_options:
-    description: "Stringified JSON object containing Playwright 'BrowserContext' options, including 'httpCredentials' and 'storageState'"
+  auth_context:
+    description: "Stringified JSON object containing 'username', 'password', 'cookies', and/or 'localStorage' from an authenticated session"
     required: false
 
 outputs:

.github/actions/find/src/AuthContext.ts

@@ -0,0 +1,50 @@
+import type playwright from "playwright";
+import type { Cookie, LocalStorage, AuthContextInput } from "./types.js";
+
+export class AuthContext implements AuthContextInput {
+  readonly username?: string;
+  readonly password?: string;
+  readonly cookies?: Cookie[];
+  readonly localStorage?: LocalStorage;
+
+  constructor({ username, password, cookies, localStorage }: AuthContextInput) {
+    this.username = username;
+    this.password = password;
+    this.cookies = cookies;
+    this.localStorage = localStorage;
+  }
+
+  toPlaywrightBrowserContextOptions(): playwright.BrowserContextOptions {
+    const playwrightBrowserContextOptions: playwright.BrowserContextOptions =
+      {};
+    if (this.username && this.password) {
+      playwrightBrowserContextOptions.httpCredentials = {
+        username: this.username,
+        password: this.password,
+      };
+    }
+    if (this.cookies || this.localStorage) {
+      playwrightBrowserContextOptions.storageState = {
+        // Add default values for fields Playwright requires which aren’t actually required by the Cookie API.
+        cookies:
+          this.cookies?.map((cookie) => ({
+            expires: -1,
+            httpOnly: false,
+            secure: false,
+            sameSite: "Lax",
+            ...cookie,
+          })) ?? [],
+        // Transform the localStorage object into the shape Playwright expects.
+        origins:
+          Object.entries(this.localStorage ?? {}).map(([origin, kv]) => ({
+            origin,
+            localStorage: Object.entries(kv).map(([name, value]) => ({
+              name,
+              value,
+            })),
+          })) ?? [],
+      };
+    }
+    return playwrightBrowserContextOptions;
+  }
+}

.github/actions/find/src/findForUrl.ts

@@ -1,10 +1,12 @@
 import type { Finding } from './types.d.js';
 import AxeBuilder from '@axe-core/playwright'
 import playwright from 'playwright';
+import { AuthContext } from './authContext.js';
 
-export async function findForUrl(url: string, playwrightContextOptions?: playwright.BrowserContextOptions): Promise<Finding[]> {
+export async function findForUrl(url: string, authContext?: AuthContext): Promise<Finding[]> {
   const browser = await playwright.chromium.launch({ headless: true, executablePath: process.env.CI ? '/usr/bin/google-chrome' : undefined });
-  const context = await browser.newContext(playwrightContextOptions);
+  const contextOptions = authContext?.toPlaywrightBrowserContextOptions() ?? {};
+  const context = await browser.newContext(contextOptions);
   const page = await context.newPage();
   await page.goto(url);
 

.github/actions/find/src/index.ts

@@ -1,22 +1,21 @@
-import type playwright from "playwright";
+import type { AuthContextInput } from "./types.js";
 import core from "@actions/core";
+import { AuthContext } from "./authContext.js";
 import { findForUrl } from "./findForUrl.js";
 
 export default async function () {
   core.info("Starting 'find' action");
   const urls = core.getMultilineInput("urls", { required: true });
   core.debug(`Input: 'urls: ${JSON.stringify(urls)}'`);
-  const playwrightContextOptions: playwright.BrowserContextOptions = JSON.parse(
-    core.getInput("playwright_context_options", { required: false }) ?? "{}"
+  const authContextInput: AuthContextInput = JSON.parse(
+    core.getInput("auth_context", { required: false }) ?? "{}"
   );
-  if (playwrightContextOptions?.httpCredentials?.password) {
-    core.setSecret(playwrightContextOptions.httpCredentials.password);
-  }
+  const authContext = new AuthContext(authContextInput);
 
   let findings = [];
   for (const url of urls) {
     core.info(`Scanning ${url}`);
-    const findingsForUrl = await findForUrl(url, playwrightContextOptions);
+    const findingsForUrl = await findForUrl(url, authContext);
     if (findingsForUrl.length === 0) {
       core.info(`No accessibility gaps were found on ${url}`);
       continue;

.github/actions/find/src/types.d.ts

@@ -5,4 +5,28 @@ export type Finding = {
   problemUrl: string;
   solutionShort: string;
   solutionLong?: string;
-}
+};
+
+export type Cookie = {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+};
+
+export type LocalStorage = {
+  [origin: string]: {
+    [key: string]: string;
+  };
+};
+
+export type AuthContextInput = {
+  username?: string;
+  password?: string;
+  cookies?: Cookie[];
+  localStorage?: LocalStorage;
+};