kunai-runner 6.10.101

package/lib/login-adapters/incommon-seamlessaccess.ts

@@ -0,0 +1,56 @@
+import type { Page } from "@playwright/test";
+import type { LoginAdapter, LoginCredentials } from "./types";
+import { handleDuoMfa } from "./duo-mfa";
+
+/**
+ * InCommonSeamlessAccessAdapter
+ *
+ * Logs in via the **InCommon / SeamlessAccess** waypoint that appears on the
+ * standard Dataverse login page ("Log In via Your Institution").
+ *
+ * Flow:
+ *   1. Click "Log In via Your Institution"
+ *   2. Land on wayfinder.incommon.org → click the SeamlessAccess button
+ *   3. Land on service.seamlessaccess.org → search for the institution
+ *   4. Select the institution link → forward to sso.unc.edu
+ *   5. Fill username / password on UNC SSO
+ *   6. Handle optional Duo MFA challenge
+ *
+ * Required env vars (read at call time — never at import time):
+ *   INCOMMON_INSTITUTION_SEARCH   Text to type into the SeamlessAccess search
+ *                                 box (defaults to "chapel hill")
+ *   INCOMMON_INSTITUTION_LINK     Accessible name (or partial) of the result
+ *                                 link to click (defaults to
+ *                                 "University of North Carolina")
+ */
+export class InCommonSeamlessAccessAdapter implements LoginAdapter {
+  async login(page: Page, credentials: LoginCredentials): Promise<void> {
+    const institutionSearch =
+      process.env.INCOMMON_INSTITUTION_SEARCH ?? "chapel hill";
+    const institutionLink =
+      process.env.INCOMMON_INSTITUTION_LINK ?? "University of North Carolina";
+
+    // 1. Click "Log In via Your Institution" on the Dataverse login page
+    await page.waitForURL(/loginpage/);
+    await page.getByRole("link", { name: /Log In via Your Inst/i }).click();
+
+    // 2. InCommon wayfinder → SeamlessAccess button
+    await page.waitForURL(/wayfinder\.incommon\.org/);
+    await page.locator("a.d-flex.sa-button").click();
+
+    // 3. SeamlessAccess → search for institution
+    await page.waitForURL(/service\.seamlessaccess\.org/);
+    await page.locator("#searchinput").type(institutionSearch);
+    await page.getByRole("link", { name: institutionLink }).click();
+
+    // 4. UNC SSO credential entry
+    await page.waitForURL(/sso\.unc\.edu/);
+    await page.locator("#username").fill(credentials.username);
+    await page.locator("#nextBtn").click();
+    await page.locator("#password").fill(credentials.password);
+    await page.locator("#submitBtn").click();
+
+    // 5. Handle Duo MFA (no-op if device is already trusted)
+    await handleDuoMfa(page);
+  }
+}

package/lib/login-adapters/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Login Adapter Factory
+ *
+ * Returns the correct LoginAdapter implementation based on the
+ * `LOGIN_ADAPTER` environment variable.
+ *
+ * Supported adapter names (case-insensitive):
+ *
+ *   shibboleth-direct        – Direct IdP selector embedded in the Dataverse
+ *                              login page (e.g. #idpSelectSelector)
+ *   incommon-seamlessaccess  – InCommon / SeamlessAccess waypoint flow
+ *   builtin                  – Dataverse built-in username / password form
+ *
+ * Example .env entry:
+ *
+ *   LOGIN_ADAPTER=incommon-seamlessaccess
+ *
+ * Usage in a setup file:
+ *
+ *   import { getLoginAdapter } from "../../lib/login-adapters";
+ *   const adapter = getLoginAdapter();
+ *   await adapter.login(page, credentials);
+ */
+
+export type { LoginAdapter, LoginCredentials, LoginAdapterName } from "./types";
+export { ShibbolethDirectAdapter } from "./shibboleth-direct";
+export { InCommonSeamlessAccessAdapter } from "./incommon-seamlessaccess";
+export { BuiltinAdapter } from "./builtin";
+
+import type { LoginAdapter, LoginAdapterName } from "./types";
+import { ShibbolethDirectAdapter } from "./shibboleth-direct";
+import { InCommonSeamlessAccessAdapter } from "./incommon-seamlessaccess";
+import { BuiltinAdapter } from "./builtin";
+
+/**
+ * Returns the LoginAdapter configured via the `LOGIN_ADAPTER` env var.
+ *
+ * @throws {Error}  When the env var is missing or the adapter name is unknown.
+ */
+export function getLoginAdapter(): LoginAdapter {
+  const adapterName = process.env.LOGIN_ADAPTER;
+
+  if (!adapterName) {
+    throw new Error(
+      `Missing required environment variable "LOGIN_ADAPTER". ` +
+        `Set it to one of: shibboleth-direct, incommon-seamlessaccess, builtin.`,
+    );
+  }
+
+  const normalized = adapterName.trim().toLowerCase() as LoginAdapterName;
+
+  switch (normalized) {
+    case "shibboleth-direct":
+      return new ShibbolethDirectAdapter();
+
+    case "incommon-seamlessaccess":
+      return new InCommonSeamlessAccessAdapter();
+
+    case "builtin":
+      return new BuiltinAdapter();
+
+    default:
+      throw new Error(
+        `Unknown login adapter "${adapterName}" specified in "LOGIN_ADAPTER". ` +
+          `Valid options are: shibboleth-direct, incommon-seamlessaccess, builtin.`,
+      );
+  }
+}

package/lib/login-adapters/shibboleth-direct.ts

@@ -0,0 +1,34 @@
+import type { Page } from "@playwright/test";
+import type { LoginAdapter, LoginCredentials } from "./types";
+import { handleDuoMfa } from "./duo-mfa";
+
+/**
+ * ShibbolethDirectAdapter
+ *
+ * Logs in via a **direct** Shibboleth IdP selector that is embedded on the
+ * Dataverse login page itself (no InCommon / SeamlessAccess waypoint).
+ *
+ * This is the adapter used by the 21 CFR Part 11 suite, where the target
+ * instance hosts a custom IdP dropdown (e.g. `#idpSelectSelector`) that lets
+ * the user pick `https://sso.unc.edu/idp` before being forwarded to UNC SSO.
+ *
+ * Required env vars (read at call time — never at import time):
+ *   IDP_SELECTOR_VALUE   The <option> value to select in #idpSelectSelector
+ *                        (defaults to "https://sso.unc.edu/idp")
+ */
+export class ShibbolethDirectAdapter implements LoginAdapter {
+  async login(page: Page, credentials: LoginCredentials): Promise<void> {
+    const idpValue =
+      process.env.IDP_SELECTOR_VALUE ?? "https://sso.unc.edu/idp";
+
+    await page.locator("#idpSelectSelector").selectOption(idpValue);
+    await page.getByRole("button", { name: "Continue" }).click({ force: true });
+
+    await page.locator("#username").fill(credentials.username);
+    await page.locator("#nextBtn").click();
+    await page.locator("#password").fill(credentials.password);
+    await page.locator("#submitBtn").click();
+
+    await handleDuoMfa(page);
+  }
+}

package/lib/login-adapters/types.ts

@@ -0,0 +1,21 @@
+import type { Page } from "@playwright/test";
+
+export interface LoginCredentials {
+  username: string;
+  password: string;
+}
+
+/**
+ * A LoginAdapter encapsulates one complete end-to-end authentication flow,
+ * starting from the Dataverse home page (after the "Log In" button has been
+ * confirmed visible) and finishing with the browser landed on an authenticated
+ * Dataverse page.
+ */
+export interface LoginAdapter {
+  login(page: Page, credentials: LoginCredentials): Promise<void>;
+}
+
+export type LoginAdapterName =
+  | "shibboleth-direct"
+  | "incommon-seamlessaccess"
+  | "builtin";

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "kunai-runner",
+  "version": "6.10.101",
+  "description": "High-performance Dataverse Playwright frontend testing framework and E2E automation scaffolding.",
+  "directories": {
+    "doc": "docs",
+    "lib": "lib",
+    "test": "tests"
+  },
+  "files": [
+    "lib/",
+    "tests/",
+    "scripts/",
+    "docs/",
+    "playwright.config.ts",
+    "tsconfig.json",
+    ".env.example",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uncch-rdmc/kunai-runner.git"
+  },
+  "keywords": [
+    "playwright",
+    "dataverse",
+    "e2e",
+    "testing"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/uncch-rdmc/kunai-runner/issues"
+  },
+  "homepage": "https://github.com/uncch-rdmc/kunai-runner#readme",
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "@types/node": "^26.1.0"
+  },
+  "dependencies": {
+    "dotenv": "^17.4.2",
+    "typescript": "^6.0.3"
+  }
+}

package/playwright.config.ts

@@ -0,0 +1,206 @@
+import { defineConfig } from "@playwright/test";
+import fs from "fs";
+import path from "path";
+const process = (globalThis as any).process;
+
+// Derive the auth file path at config-load time so both the setup project
+// and the suite project reference the same per-endpoint, per-browser file.
+// We inline the slug logic here (rather than importing lib/auth-file.ts)
+// because playwright.config.ts is evaluated before TypeScript compilation.
+function authFilePath(browser: string): string {
+  const url = (process.env.BASE_URL ?? "default").trim();
+  const slug = url
+    .replace(/^https?:\/\//, "")
+    .replace(/\/$/, "")
+    .replace(/[^a-z0-9]/gi, "-")
+    .toLowerCase();
+  return `playwright/.auth/${slug}-${browser}.json`;
+}
+
+const AUTH_CHROMIUM = authFilePath("chromium");
+const AUTH_FIREFOX = authFilePath("firefox");
+const AUTH_WEBKIT = authFilePath("webkit");
+
+/**
+ * Load environment variables from .env at the repository root.
+ * dotenv is a transitive dependency of @playwright/test — no extra install needed.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+require("dotenv").config({ path: path.resolve(__dirname, ".env") });
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: "./tests/suite",
+  timeout: 90000,
+  /* All tests within a project run in strict sequence; projects themselves
+     run one at a time because workers is 1. */
+  workers: 1,
+  fullyParallel: false,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: "html",
+  /* Shared settings for all projects. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    headless: true,
+
+    launchOptions: {
+      slowMo: 2000,
+    },
+
+    // Sets the default viewport size for all tests
+    viewport: { width: 1920, height: 1080 },
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: "on",
+
+    /* Always collect video and screenshots, even when tests pass. See https://playwright.dev/docs/video-and-screenshots */
+    video: {
+      mode: "on",
+      size: { width: 1920, height: 1080 },
+    },
+
+    screenshot: {
+      mode: "on",
+      fullPage: true,
+    },
+  },
+
+  /* Configure the output directory for test artifacts such as screenshots, videos, traces, etc. */
+  outputDir: "test-results/",
+
+  /* Configure projects
+   *
+   * Execution order (workers: 1 → strictly sequential):
+   *
+   *   preflight
+   *     → setup-chromium → suite-chromium
+   *       → setup-firefox → suite-firefox
+   *         → setup-webkit → suite-webkit
+   *
+   * "suite-firefox" declares a dependency on "suite-chromium" and
+   * "suite-webkit" declares a dependency on "suite-firefox", which
+   * enforces the Chromium → Firefox → WebKit ordering even if workers
+   * is ever increased.
+   */
+  projects: [
+    /* =========================================================
+       1. Preflight — Chromium, no auth required, @standard only.
+          The test itself returns immediately when SKIP_PREFLIGHT=true.
+       ========================================================= */
+    {
+      name: "preflight",
+      testMatch: /suite\/01-preflight\.spec\.ts/,
+      tsconfig: "./tests/suite/tsconfig.json",
+      use: {
+        browserName: "chromium",
+        baseURL: process.env.BASE_URL,
+      },
+    },
+
+    /* =========================================================
+       2a. Auth setup — Chromium
+       ========================================================= */
+    {
+      name: "setup-chromium",
+      testMatch: /suite\/auth\.setup\.ts/,
+      tsconfig: "./tests/suite/tsconfig.json",
+      use: {
+        browserName: "chromium",
+        baseURL: process.env.BASE_URL,
+        ...(fs.existsSync(AUTH_CHROMIUM) && {
+          storageState: AUTH_CHROMIUM,
+        }),
+      },
+      dependencies: [],
+    },
+
+    /* =========================================================
+       2b. Auth setup — Firefox
+       ========================================================= */
+    {
+      name: "setup-firefox",
+      testMatch: /suite\/auth\.setup\.ts/,
+      tsconfig: "./tests/suite/tsconfig.json",
+      use: {
+        browserName: "firefox",
+        baseURL: process.env.BASE_URL,
+        ...(fs.existsSync(AUTH_FIREFOX) && {
+          storageState: AUTH_FIREFOX,
+        }),
+      },
+      dependencies: [],
+    },
+
+    /* =========================================================
+       2c. Auth setup — WebKit (Safari)
+       ========================================================= */
+    {
+      name: "setup-webkit",
+      testMatch: /suite\/auth\.setup\.ts/,
+      tsconfig: "./tests/suite/tsconfig.json",
+      use: {
+        browserName: "webkit",
+        baseURL: process.env.BASE_URL,
+        ...(fs.existsSync(AUTH_WEBKIT) && {
+          storageState: AUTH_WEBKIT,
+        }),
+      },
+      dependencies: [],
+    },
+
+    /* =========================================================
+       3a. Main test suite — Chromium
+           Runs first. Firefox suite depends on this completing.
+       ========================================================= */
+    {
+      name: "suite-chromium",
+      testMatch: /suite\/(?!auth\.setup|01-preflight)\d+.*\.spec\.ts/,
+      tsconfig: "./tests/suite/tsconfig.json",
+      use: {
+        browserName: "chromium",
+        baseURL: process.env.BASE_URL,
+        ...(fs.existsSync(AUTH_CHROMIUM) && {
+          storageState: AUTH_CHROMIUM,
+        }),
+      },
+      dependencies: ["setup-chromium"],
+    },
+
+    /* =========================================================
+       3b. Main test suite — Firefox
+           Runs after Chromium suite completes.
+       ========================================================= */
+    {
+      name: "suite-firefox",
+      testMatch: /suite\/(?!auth\.setup|01-preflight)\d+.*\.spec\.ts/,
+      tsconfig: "./tests/suite/tsconfig.json",
+      use: {
+        browserName: "firefox",
+        baseURL: process.env.BASE_URL,
+        ...(fs.existsSync(AUTH_FIREFOX) && {
+          storageState: AUTH_FIREFOX,
+        }),
+      },
+      dependencies: ["setup-firefox", "suite-chromium"],
+    },
+
+    /* =========================================================
+       3c. Main test suite — WebKit (Safari)
+           Runs after Firefox suite completes.
+       ========================================================= */
+    {
+      name: "suite-webkit",
+      testMatch: /suite\/(?!auth\.setup|01-preflight)\d+.*\.spec\.ts/,
+      tsconfig: "./tests/suite/tsconfig.json",
+      use: {
+        browserName: "webkit",
+        baseURL: process.env.BASE_URL,
+        ...(fs.existsSync(AUTH_WEBKIT) && {
+          storageState: AUTH_WEBKIT,
+        }),
+      },
+      dependencies: ["setup-webkit", "suite-firefox"],
+    },
+  ],
+});

package/scripts/combine_videos.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""
+combine_videos.py
+-----------------
+Walks the Playwright test-results directory, collects every .webm video
+whose parent folder starts with the given suite prefix, concatenates them
+in sorted order, and re-encodes the result as an MPEG-4 file (H.264 + AAC).
+
+Usage
+-----
+    # Unified suite (all tests)
+    python scripts/combine_videos.py --suite suite
+
+    # Custom output filename
+    python scripts/combine_videos.py --suite suite --output my_demo.mp4
+
+    # Absolute output path
+    python scripts/combine_videos.py --suite suite --output ~/Desktop/demo.mp4
+
+Requirements
+------------
+    - Python 3.8+
+    - ffmpeg must be on $PATH  (brew install ffmpeg  /  apt install ffmpeg)
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+RESULTS_ROOT = Path(__file__).resolve().parent.parent / "test-results"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def find_webm_files(results_root: Path, suite: str) -> list[Path]:
+    """
+    Recursively walk *results_root* and return a sorted list of .webm files
+    that live inside folders whose name starts with *suite* + '-'.
+
+    Playwright names each test's output folder as:
+        <suite>-<spec-slug>-<hash>-<test-title>-<project>/
+    All of these sit directly under test-results/, NOT inside a suite
+    sub-directory.  We therefore search the root and filter by prefix.
+    """
+    webm_files: list[Path] = []
+
+    for root, _dirs, files in os.walk(results_root):
+        root_path = Path(root)
+        # Accept the folder if any ancestor (relative to results_root)
+        # starts with the suite prefix, OR if the folder itself does.
+        try:
+            rel = root_path.relative_to(results_root)
+        except ValueError:
+            continue
+
+        parts = rel.parts
+        if not parts:
+            continue  # the root itself — skip
+
+        # Playwright appends the project name as the SUFFIX of each folder:
+        #   <spec-slug>-<test-title>-<project>
+        # We therefore filter by suffix, not prefix.
+        if not parts[0].endswith(f"-{suite}"):
+            continue
+
+        for filename in files:
+            if filename.lower().endswith(".webm"):
+                webm_files.append(root_path / filename)
+
+    if not webm_files:
+        print(
+            f"[ERROR] No .webm files found under: {results_root}\n"
+            f"        (looked for folders ending with '-{suite}')",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    webm_files.sort()  # sort by full path → preserves spec/test ordering
+    return webm_files
+
+
+def check_ffmpeg() -> None:
+    """Abort early with a helpful message if ffmpeg is not available."""
+    try:
+        subprocess.run(
+            ["ffmpeg", "-version"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=True,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        print(
+            "[ERROR] ffmpeg not found on PATH.\n"
+            "  macOS : brew install ffmpeg\n"
+            "  Ubuntu: sudo apt install ffmpeg",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def write_concat_list(webm_files: list[Path], list_path: Path) -> None:
+    """
+    Write an ffmpeg concat-demuxer input file.
+
+    Each line looks like:
+        file '/absolute/path/to/clip.webm'
+    Paths are written as absolute POSIX strings so ffmpeg can find them
+    regardless of where the script is invoked from.
+    """
+    with list_path.open("w", encoding="utf-8") as fh:
+        for p in webm_files:
+            # ffmpeg requires single-quoted paths; escape any embedded quotes
+            safe = str(p.resolve()).replace("'", "'\\''")
+            fh.write(f"file '{safe}'\n")
+
+
+def concat_and_encode(list_path: Path, output_path: Path) -> None:
+    """
+    Use ffmpeg's concat demuxer to stitch the clips together and
+    re-encode as MPEG-4 / H.264 + AAC in a single pass.
+
+    Key flags
+    ---------
+    -f concat           use the concat demuxer (works with .webm inputs)
+    -safe 0             allow absolute paths in the list file
+    -c:v libx264        H.264 video codec
+    -crf 22             quality level (18=near-lossless, 28=smaller file)
+    -preset fast        encoding speed/compression trade-off
+    -c:a aac            AAC audio codec
+    -b:a 128k           audio bitrate
+    -movflags +faststart  move MOOV atom to the front for web streaming
+    -y                  overwrite output without prompting
+    """
+    cmd = [
+        "ffmpeg",
+        "-f", "concat",
+        "-safe", "0",
+        "-i", str(list_path),
+        "-c:v", "libx264",
+        "-crf", "22",
+        "-preset", "fast",
+        "-c:a", "aac",
+        "-b:a", "128k",
+        "-movflags", "+faststart",
+        "-y",
+        str(output_path),
+    ]
+
+    print("\n[ffmpeg] Running:")
+    print("  " + " ".join(cmd) + "\n")
+
+    result = subprocess.run(cmd)
+
+    if result.returncode != 0:
+        print("\n[ERROR] ffmpeg exited with a non-zero status.", file=sys.stderr)
+        sys.exit(result.returncode)
+
+
+# ---------------------------------------------------------------------------
+# Entry-point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Combine Playwright .webm videos into a single MP4."
+    )
+    parser.add_argument(
+        "--suite",
+        required=True,
+        help=(
+            "Playwright project name prefix to collect videos for "
+            "(e.g. 'suite' for the unified suite)."
+        ),
+    )
+    parser.add_argument(
+        "--output",
+        default=None,
+        help=(
+            "Destination MP4 filename (default: test-results/<suite>_combined.mp4)."
+        ),
+    )
+    parser.add_argument(
+        "--results-root",
+        default=str(RESULTS_ROOT),
+        help=f"Override the test-results root directory (default: {RESULTS_ROOT}).",
+    )
+
+    args = parser.parse_args()
+
+    results_root = Path(args.results_root)
+
+    if not results_root.is_dir():
+        print(
+            f"[ERROR] test-results directory not found: {results_root}\n"
+            "  Make sure you have run the Playwright tests first so that "
+            "test-results/ is populated.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if args.output:
+        raw = Path(args.output)
+        # Keep absolute paths as-is; resolve relative paths into test-results/
+        # so the file never lands in the repo root and gets accidentally committed.
+        output_path = raw if raw.is_absolute() else results_root / raw
+    else:
+        output_path = results_root / f"{args.suite}_combined.mp4"
+
+    # -----------------------------------------------------------------------
+    check_ffmpeg()
+
+    webm_files = find_webm_files(results_root, args.suite)
+
+    print(f"[INFO] Suite      : {args.suite}")
+    print(f"[INFO] Source dir : {results_root}  (suffix: -{args.suite})")
+    print(f"[INFO] Output     : {output_path}")
+    print(f"[INFO] Clips found: {len(webm_files)}")
+    for i, f in enumerate(webm_files, 1):
+        print(f"         {i:>3}. {f.relative_to(Path(args.results_root))}")
+
+    # Write the temporary concat list inside the results root so that
+    # relative paths (if any) resolve correctly.
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        suffix="_concat_list.txt",
+        dir=Path(args.results_root),
+        delete=False,
+    ) as tmp:
+        tmp_path = Path(tmp.name)
+
+    try:
+        write_concat_list(webm_files, tmp_path)
+        concat_and_encode(tmp_path, output_path)
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+    print(f"\n[DONE] Combined video saved to:\n  {output_path.resolve()}")
+
+
+if __name__ == "__main__":
+    main()