walkwright 0.0.1

package/src/cli.ts

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+import { ensureProject, login } from "./device-auth.js";
+import {
+  defaultReportsUrl,
+  describeConfigPath,
+  readWalkwrightConfig,
+  repoName,
+  writeWalkwrightConfig,
+} from "./project.js";
+import {
+  blank,
+  bold,
+  failure,
+  glyph,
+  line,
+  logo,
+  paint,
+  wordmark,
+} from "./ui.js";
+
+const [command, ...args] = process.argv.slice(2);
+
+switch (command) {
+  case "walk":
+    await walkCommand(args);
+    break;
+  case "login":
+    await loginCommand(args);
+    break;
+  case "--version":
+  case "-v":
+    banner();
+    break;
+  case undefined:
+  case "--help":
+  case "-h":
+  case "?":
+    help();
+    break;
+  default:
+    fail(`unknown command ${command}`, "walkwright --help lists the commands");
+}
+
+function version(): string {
+  const { version: value } = createRequire(import.meta.url)(
+    "../package.json",
+  ) as { version: string };
+
+  return value;
+}
+
+function banner(): void {
+  blank();
+
+  for (const row of logo()) {
+    line(row);
+  }
+
+  blank();
+  line(paint("dim", `   walkwright ${version()}`));
+  blank();
+}
+
+function help(): void {
+  const flag = (name: string, text: string): string =>
+    `  ${paint("code", name.padEnd(20))}${paint("dim", text)}`;
+  const header = (text: string): string => paint("accent", text);
+
+  blank();
+  line(`${wordmark()} ${paint("dim", version())}`);
+  blank();
+  line(header("USAGE"));
+  line(
+    `  ${paint("text", "walkwright walk")} ${paint("dim", "[flags] [playwright args...]")}`,
+  );
+  line(
+    `  ${paint("text", "walkwright login")} ${paint("dim", "[--force] [--url <server>]")}`,
+  );
+  blank();
+  line(header("WALK"));
+  line(
+    flag(
+      "--upload-on-fail",
+      "upload the passing lanes even though the walk failed",
+    ),
+  );
+  line(flag("--no-upload", "skip the upload"));
+  line(flag("--branch <name>", "report under this branch instead of git's"));
+  line(
+    flag("--project <name>", "the playwright project to run (default walk)"),
+  );
+  line(flag("--", "everything after goes to playwright"));
+  blank();
+  line(header("LOGIN"));
+  line(flag("--force", "log in again"));
+  line(
+    flag("--url <server>", `the review console (default ${defaultReportsUrl})`),
+  );
+  blank();
+  line(header("ALSO"));
+  line(flag("--version", "the banner"));
+  line(flag("--help, -h, ?", "this"));
+  blank();
+}
+
+async function loginCommand(args: string[]): Promise<void> {
+  if (args.includes("--help") || args.includes("-h") || args.includes("?")) {
+    help();
+    return;
+  }
+
+  const existing = readWalkwrightConfig();
+  const configFile = describeConfigPath();
+
+  if (existing !== undefined && !args.includes("--force")) {
+    line(
+      paint("ok", glyph.ok),
+      ` already set up ${paint("dim", glyph.dot)} project ${bold(existing.project)}`,
+    );
+    line(paint("dim", `  ${configFile} ${glyph.dot} --force to log in again`));
+    return;
+  }
+
+  const url = urlArg(args) ?? defaultReportsUrl;
+
+  try {
+    const sessionToken = await login(url);
+    const project = await ensureProject(url, sessionToken, repoName());
+
+    writeWalkwrightConfig({ url, ...project });
+    line(
+      paint("ok", glyph.ok),
+      ` wrote ${paint("code", configFile)} ${paint("dim", glyph.dot)} project ${bold(project.project)}`,
+    );
+  } catch (error) {
+    failure(describe(error), "run walkwright login again");
+    process.exit(1);
+  }
+}
+
+async function walkCommand(args: string[]): Promise<void> {
+  let uploadOnFail = false;
+  let noUpload = false;
+  let branch: string | undefined;
+  let project: string | undefined;
+  const forwarded: string[] = [];
+
+  let index = 0;
+  let own = true;
+
+  while (index < args.length) {
+    const arg = args[index];
+
+    if (arg === undefined) {
+      break;
+    }
+
+    if (!own) {
+      forwarded.push(arg);
+      index += 1;
+      continue;
+    }
+
+    switch (arg) {
+      case "--":
+        own = false;
+        index += 1;
+        break;
+      case "--help":
+      case "-h":
+      case "?":
+        help();
+        return;
+      case "--upload-on-fail":
+        uploadOnFail = true;
+        index += 1;
+        break;
+      case "--no-upload":
+        noUpload = true;
+        index += 1;
+        break;
+      case "--branch":
+        branch = requiredValue(args, index, arg);
+        index += 2;
+        break;
+      case "--project":
+        project = requiredValue(args, index, arg);
+        index += 2;
+        break;
+      default:
+        forwarded.push(arg);
+        index += 1;
+    }
+  }
+
+  if (uploadOnFail && noUpload) {
+    fail(
+      "--upload-on-fail and --no-upload cannot be used together",
+      "pick one",
+    );
+  }
+
+  const resolver = createRequire(join(process.cwd(), "package.json"));
+
+  let playwrightCli: string;
+
+  try {
+    playwrightCli = resolver.resolve("@playwright/test/cli");
+  } catch {
+    fail(
+      "@playwright/test is not installed in this project",
+      "pnpm add -D @playwright/test, then run walkwright walk again",
+    );
+  }
+
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  env["WALK_RECORDING"] = "1";
+
+  if (uploadOnFail) {
+    env["WALKWRIGHT_UPLOAD_ON_FAIL"] = "1";
+  }
+
+  if (noUpload) {
+    env["WALKWRIGHT_NO_UPLOAD"] = "1";
+  }
+
+  if (branch !== undefined) {
+    env["WALKWRIGHT_BRANCH"] = branch;
+  }
+
+  const exitCode = await runPlaywright(playwrightCli, project, forwarded, env);
+  process.exit(exitCode);
+}
+
+function requiredValue(args: string[], index: number, flag: string): string {
+  const value = args[index + 1];
+
+  if (value === undefined || value.startsWith("--")) {
+    fail(`${flag} needs a value`, `walkwright walk ${flag} <value>`);
+  }
+
+  return value;
+}
+
+async function runPlaywright(
+  playwrightCli: string,
+  project: string | undefined,
+  forwarded: string[],
+  env: NodeJS.ProcessEnv,
+): Promise<number> {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      [playwrightCli, "test", `--project=${project ?? "walk"}`, ...forwarded],
+      { stdio: "inherit", env, cwd: process.cwd() },
+    );
+
+    child.on("error", (error) => {
+      reject(error);
+    });
+
+    child.on("exit", (exitCode) => {
+      resolve(exitCode ?? 1);
+    });
+  });
+}
+
+function urlArg(args: string[]): string | undefined {
+  const index = args.indexOf("--url");
+
+  if (index === -1) {
+    return undefined;
+  }
+
+  const value = args[index + 1];
+
+  if (value === undefined || value.startsWith("--")) {
+    fail("--url needs a value", "walkwright login --url https://…");
+  }
+
+  return value;
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function fail(message: string, hint: string): never {
+  failure(message, hint);
+  process.exit(1);
+}

package/src/config.ts

@@ -0,0 +1,16 @@
+import type { ReporterDescription } from "@playwright/test";
+
+import type { RecorderFixtures } from "./recorder.js";
+import type { ReporterOptions } from "./reporter.js";
+
+const recording = process.env["WALK_RECORDING"] === "1";
+
+export const walk = {
+  recording,
+
+  reporter(options: ReporterOptions): ReporterDescription[] {
+    return recording ? [["walkwright/reporter", options]] : [];
+  },
+
+  use: { recording } satisfies Pick<RecorderFixtures, "recording">,
+};

package/src/descriptor.ts

@@ -0,0 +1,179 @@
+import { z } from "zod";
+
+import type { LocatorDescriptor, Text } from "./locator.js";
+import { locatorDescriptorSchema, textSchema } from "./locator.js";
+
+export interface ParamDecl {
+  name: string;
+}
+
+export const paramDeclSchema: z.ZodType<ParamDecl> = z.object({
+  name: z.string(),
+});
+
+export type ElementDescriptor =
+  | { locator: LocatorDescriptor; params?: ParamDecl[] }
+  | { surface: NestedSurfaceDescriptor }
+  | { overlay: OverlayDescriptor; open?: OpaqueImpl }
+  | { opaque: true; provenance: "hand" };
+
+export interface OpaqueImpl {
+  opaque: true;
+  provenance: "hand";
+}
+
+const opaqueImplSchema: z.ZodType<OpaqueImpl> = z.object({
+  opaque: z.literal(true),
+  provenance: z.literal("hand"),
+});
+
+export const elementDescriptorSchema: z.ZodType<ElementDescriptor> = z.lazy(
+  () =>
+    z.union([
+      z.object({
+        locator: locatorDescriptorSchema,
+        params: z.array(paramDeclSchema).optional(),
+      }),
+      z.object({ surface: nestedSurfaceDescriptorSchema }),
+      z.object({
+        overlay: overlayDescriptorSchema,
+        open: opaqueImplSchema.optional(),
+      }),
+      z.object({ opaque: z.literal(true), provenance: z.literal("hand") }),
+    ]),
+);
+
+export interface ActionDescriptor {
+  name: string;
+  impl: OpaqueImpl;
+}
+
+export const actionDescriptorSchema: z.ZodType<ActionDescriptor> = z.object({
+  name: z.string(),
+  impl: opaqueImplSchema,
+});
+
+export interface RegexDescriptor {
+  pattern: string;
+  flags?: string;
+}
+
+export const regexDescriptorSchema: z.ZodType<RegexDescriptor> = z.object({
+  pattern: z.string(),
+  flags: z.string().optional(),
+});
+
+export type CaptureRuleDescriptor =
+  | { element: string[]; text: string; match?: RegexDescriptor }
+  | { match: RegexDescriptor; text: string };
+
+export const captureRuleDescriptorSchema: z.ZodType<CaptureRuleDescriptor> =
+  z.union([
+    z.object({
+      element: z.array(z.string()),
+      text: z.string(),
+      match: regexDescriptorSchema.optional(),
+    }),
+    z.object({ match: regexDescriptorSchema, text: z.string() }),
+  ]);
+
+export interface CaptureDescriptor {
+  rules: CaptureRuleDescriptor[];
+}
+
+export const captureDescriptorSchema: z.ZodType<CaptureDescriptor> = z.object({
+  rules: z.array(captureRuleDescriptorSchema),
+});
+
+export interface SurfaceDescriptor {
+  elements: Record<string, ElementDescriptor>;
+  actions?: ActionDescriptor[];
+  capture?: CaptureDescriptor;
+}
+
+const surfaceShape = {
+  elements: z.record(
+    z.string(),
+    z.lazy((): z.ZodType<ElementDescriptor> => elementDescriptorSchema),
+  ),
+  actions: z.array(actionDescriptorSchema).optional(),
+  capture: captureDescriptorSchema.optional(),
+};
+
+export interface NestedSurfaceDescriptor extends SurfaceDescriptor {
+  root?: LocatorDescriptor;
+}
+
+export const nestedSurfaceDescriptorSchema: z.ZodType<NestedSurfaceDescriptor> =
+  z.lazy(() =>
+    z.object({
+      root: locatorDescriptorSchema.optional(),
+      ...surfaceShape,
+    }),
+  );
+
+export interface OverlayDescriptor extends SurfaceDescriptor {
+  root: LocatorDescriptor;
+  name?: Text;
+  recorder: { label: string };
+  close: { esc: boolean; button?: LocatorDescriptor };
+}
+
+export const overlayDescriptorSchema: z.ZodType<OverlayDescriptor> = z.lazy(
+  () =>
+    z.object({
+      root: locatorDescriptorSchema,
+      name: textSchema.optional(),
+      recorder: z.object({ label: z.string() }),
+      close: z.object({
+        esc: z.boolean(),
+        button: locatorDescriptorSchema.optional(),
+      }),
+      ...surfaceShape,
+    }),
+);
+
+export type ReadyDescriptor = { selector: string } | { opaque: true };
+
+const readyDescriptorSchema: z.ZodType<ReadyDescriptor> = z.union([
+  z.object({ selector: z.string() }),
+  z.object({ opaque: z.literal(true) }),
+]);
+
+export interface PageDescriptor extends SurfaceDescriptor {
+  path: string;
+  name: string;
+  recorder?: { group?: string[]; label?: string };
+  ready?: ReadyDescriptor;
+  header?: Text;
+  anchor?: LocatorDescriptor | { opaque: true };
+}
+
+export const pageDescriptorSchema: z.ZodType<PageDescriptor> = z.object({
+  path: z.string(),
+  name: z.string(),
+  recorder: z
+    .object({
+      group: z.array(z.string()).optional(),
+      label: z.string().optional(),
+    })
+    .optional(),
+  ready: readyDescriptorSchema.optional(),
+  header: textSchema.optional(),
+  anchor: z
+    .union([locatorDescriptorSchema, z.object({ opaque: z.literal(true) })])
+    .optional(),
+  ...surfaceShape,
+});
+
+export interface AppDescriptor {
+  ready?: ReadyDescriptor;
+  pages: PageDescriptor[];
+  capture?: CaptureDescriptor;
+}
+
+export const appDescriptorSchema: z.ZodType<AppDescriptor> = z.object({
+  ready: readyDescriptorSchema.optional(),
+  pages: z.array(pageDescriptorSchema),
+  capture: captureDescriptorSchema.optional(),
+});

package/src/device-auth.ts

@@ -0,0 +1,188 @@
+import { execFileSync } from "node:child_process";
+
+import type { WalkwrightConfig } from "./project.js";
+import { blank, bold, glyph, line, paint, prompt, pulse } from "./ui.js";
+
+const clientId = "walk-cli";
+
+interface DeviceCode {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  verification_uri_complete: string;
+  expires_in: number;
+  interval: number;
+}
+
+interface DeviceTokenResponse {
+  error?: string;
+  access_token?: string;
+  session?: { token?: string };
+}
+
+export async function login(baseUrl: string): Promise<string> {
+  const base = baseUrl.replace(/\/$/, "");
+
+  const code = await postJson<DeviceCode>(`${base}/api/auth/device/code`, {
+    client_id: clientId,
+  });
+
+  blank();
+  line(
+    prompt(
+      `open ${paint("code", code.verification_uri)} and enter  ${bold(paint("accent", code.user_code))}`,
+    ),
+  );
+  openBrowser(code.verification_uri_complete);
+
+  const stop = pulse(paint("dim", "  waiting for approval"));
+
+  let token: string;
+
+  try {
+    token = await poll(base, code);
+  } catch (error) {
+    stop();
+    throw error;
+  }
+
+  stop();
+  line(paint("ok", glyph.ok), ` approved${await approvedAs(base, token)}`);
+
+  return token;
+}
+
+async function approvedAs(base: string, token: string): Promise<string> {
+  try {
+    const response = await fetch(`${base}/api/auth/get-session`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+
+    if (!response.ok) {
+      return "";
+    }
+
+    const body = (await response.json()) as { user?: { name?: string } } | null;
+    const name = body?.user?.name;
+
+    return name === undefined || name === "" ? "" : ` as ${bold(name)}`;
+  } catch {
+    return "";
+  }
+}
+
+async function poll(base: string, code: DeviceCode): Promise<string> {
+  const deadline = Date.now() + code.expires_in * 1000;
+  let intervalMs = Math.max(1, code.interval) * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+
+    const response = await fetch(`${base}/api/auth/device/token`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        device_code: code.device_code,
+        client_id: clientId,
+      }),
+    });
+
+    const body = (await response.json()) as DeviceTokenResponse;
+
+    if (response.ok) {
+      const token = body.session?.token ?? body.access_token;
+
+      if (token === undefined) {
+        throw new Error("device login succeeded but returned no session token");
+      }
+
+      return token;
+    }
+
+    if (body.error === "authorization_pending") {
+      continue;
+    }
+
+    if (body.error === "slow_down") {
+      intervalMs += 1000;
+      continue;
+    }
+
+    throw new Error(
+      body.error === "expired_token" || body.error === "access_denied"
+        ? "that didn't work — the code may have expired. run walkwright login again."
+        : `that didn't work — ${body.error ?? String(response.status)}. run walkwright login again.`,
+    );
+  }
+
+  throw new Error(
+    "that didn't work — the code expired. run walkwright login again.",
+  );
+}
+
+export async function ensureProject(
+  baseUrl: string,
+  sessionToken: string,
+  name: string,
+): Promise<Pick<WalkwrightConfig, "project" | "token">> {
+  const base = baseUrl.replace(/\/$/, "");
+
+  const response = await fetch(`${base}/api/projects/ensure`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${sessionToken}`,
+    },
+    body: JSON.stringify({ name }),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `project setup failed — ${String(response.status)} from ${base}`,
+    );
+  }
+
+  return (await response.json()) as Pick<WalkwrightConfig, "project" | "token">;
+}
+
+async function postJson<Body>(url: string, payload: unknown): Promise<Body> {
+  let response: Response;
+
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+  } catch {
+    throw new Error(`can't reach ${new URL(url).origin}`);
+  }
+
+  if (!response.ok) {
+    throw new Error(`${String(response.status)} from ${url}`);
+  }
+
+  return (await response.json()) as Body;
+}
+
+function openBrowser(url: string): void {
+  const [command, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+
+  try {
+    execFileSync(command, args, { stdio: "ignore" });
+  } catch {
+    return;
+  }
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise<void>((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}