kunai-runner 6.10.101

package/.env.example

@@ -0,0 +1,68 @@
+# =============================================================================
+# Dataverse VAST Suite — Environment Variables
+# =============================================================================
+# Copy this file to .env and fill in your values.
+# The .env file is gitignored and will never be committed.
+
+# -----------------------------------------------------------------------------
+# Base URL (no trailing slash)
+# -----------------------------------------------------------------------------
+# The single endpoint the entire suite will run against.
+BASE_URL=https://your-dataverse.example.edu
+
+# -----------------------------------------------------------------------------
+# Credentials
+# -----------------------------------------------------------------------------
+# Login credentials for the account used to run the test suite.
+# These replace the previous sensitive-data/user.json file.
+#
+#   DV_USERNAME  — username or email for the Dataverse account
+#   DV_PASSWORD  — password for the Dataverse account
+#   DV_FULL_NAME — display name shown in the Dataverse navbar after login
+#                  (used to detect an existing authenticated session)
+#
+DV_USERNAME=your-username
+DV_PASSWORD=your-password
+DV_FULL_NAME=Your Full Name
+
+# -----------------------------------------------------------------------------
+# Login Adapter
+# -----------------------------------------------------------------------------
+# Select the authentication flow for this endpoint.
+#
+# Available adapters:
+#   shibboleth-direct        — Direct IdP dropdown on the Dataverse login page
+#                              (e.g. #idpSelectSelector with UNC SSO)
+#   incommon-seamlessaccess  — InCommon / SeamlessAccess waypoint flow
+#   builtin                  — Dataverse built-in username / password form
+#
+LOGIN_ADAPTER=incommon-seamlessaccess
+
+# -----------------------------------------------------------------------------
+# Root dataverse collection path (optional)
+# -----------------------------------------------------------------------------
+# Path used by the @standard "Create Dataverse" test as the parent collection.
+# Default: /dataverse/unc
+# Set to "/" for instances whose root IS the top-level dataverse.
+ROOT_DATAVERSE=/dataverse/unc
+
+# -----------------------------------------------------------------------------
+# Adapter-specific options (optional — sensible defaults are built in)
+# -----------------------------------------------------------------------------
+
+# shibboleth-direct: the <option> value to select in #idpSelectSelector
+# IDP_SELECTOR_VALUE=https://sso.unc.edu/idp
+
+# incommon-seamlessaccess: text to type into the SeamlessAccess search box
+# INCOMMON_INSTITUTION_SEARCH=chapel hill
+
+# incommon-seamlessaccess: accessible name (or partial) of the institution link
+# INCOMMON_INSTITUTION_LINK=University of North Carolina
+
+# -----------------------------------------------------------------------------
+# Preflight control
+# -----------------------------------------------------------------------------
+# Set to "true" to skip the preflight project dependency when the target
+# endpoint does not have the standard UNC Dataverse header/footer checks
+# (e.g. when BASE_URL points at a 21 CFR instance).
+# SKIP_PREFLIGHT=true

package/README.md

@@ -0,0 +1,17 @@
+# kunai-runner
+High-performance Dataverse Playwright frontend testing framework and E2E automation scaffolding.
+
+kunai-runner is the foundational open-source automation engine and testing scaffolding for IQSS Dataverse. Built for speed, reliability, and developer ergonomics, it provides the core test runner, DOM assertion utilities, and CI/CD integration pipelines needed to validate complex frontend architectures. Designed to be highly extensible, it serves as the close-quarters framework for writing, structuring, and executing robust end-to-end web UI tests.
+
+## Steps to Use Kunai Runner
+1. Clone the git repository into an empty folder
+2. `cd` into the working directory (the root directory where `playwright.config.ts` exists)
+3. `cp .env.example .env`
+4. Fill `.env` with your installation-specific values:
+   - `BASE_URL` — the Dataverse instance URL
+   - `DV_USERNAME` / `DV_PASSWORD` / `DV_FULL_NAME` — login credentials and navbar display name
+   - `LOGIN_ADAPTER` — authentication flow (`shibboleth-direct`, `incommon-seamlessaccess`, or `builtin`)
+   - See `.env.example` for all available options
+5. `npm install`
+6. `npx playwright install`
+7. `npx playwright test`

package/docs/01_shibboleth_auth.md

@@ -0,0 +1,122 @@
+Title: "01. Authentication Adapters"
+Author: "Snehashish Reddy Manda"
+Email: "msreddy@unc.edu"
+Date: "June 2026"
+```
+
+# 01. Authentication Adapters
+
+The unified VAST Suite supports multiple authentication flows via **login adapters**. The active adapter is selected by setting `LOGIN_ADAPTER` in `.env` — no source code changes required.
+
+---
+
+## Available Adapters
+
+| Adapter | `LOGIN_ADAPTER` value | When to use |
+|---|---|---|
+| **Shibboleth Direct** | `shibboleth-direct` | Dataverse instances with a custom IdP dropdown (`#idpSelectSelector`) on the login page. Used for HPO / 21 CFR instances at UNC. |
+| **InCommon / SeamlessAccess** | `incommon-seamlessaccess` | Standard Dataverse instances accessed via the InCommon federation ("Log In via Your Institution" → SeamlessAccess waypoint). |
+| **Built-in** | `builtin` | Dataverse instances with the built-in username/password form enabled. Useful for local dev or non-federated instances. |
+
+---
+
+## Shibboleth Direct Flow (`shibboleth-direct`)
+
+Used by HPO Dataverse and similar Shibboleth-protected instances.
+
+1. Navigate to the Dataverse homepage
+2. Click **Log In**
+3. Select `https://sso.unc.edu/idp` from the `#idpSelectSelector` dropdown
+4. Click **Continue**
+5. Fill in ONYEN in the username field → click **Next**
+6. Fill in password → click **Submit**
+7. Handle Duo 2FA (see below)
+8. Land back on Dataverse as the authenticated user
+
+The IdP selector value defaults to `https://sso.unc.edu/idp`. Override with `IDP_SELECTOR_VALUE` in `.env` for other institutions.
+
+---
+
+## InCommon / SeamlessAccess Flow (`incommon-seamlessaccess`)
+
+Used by the standard UNC Dataverse instance.
+
+1. Navigate to the Dataverse homepage
+2. Click **Log In**
+3. Click **Log In via Your Institution**
+4. Redirect to InCommon waypoint → click the SeamlessAccess button
+5. Search for institution (default: `chapel hill`) → click the result link
+6. Redirect to UNC SSO → fill ONYEN and password
+7. Handle Duo 2FA (see below)
+8. Land back on Dataverse as the authenticated user
+
+Override the institution search text with `INCOMMON_INSTITUTION_SEARCH` and the institution link name with `INCOMMON_INSTITUTION_LINK` in `.env`.
+
+---
+
+## Duo MFA Challenge
+
+Both Shibboleth-based flows may encounter a Duo 2FA challenge after password submission. The shared [`lib/login-adapters/duo-mfa.ts`](../lib/login-adapters/duo-mfa.ts) helper handles both branches automatically:
+
+- **(A) "Yes, trust this browser" button appears** — click it and wait for redirect back to Dataverse
+- **(B) Device already trusted** — Duo auto-redirects, nothing to do
+
+### Why choose "Yes" (trusted device)?
+
+Clicking **Yes** grants a **7-day** Duo session cookie. Clicking **No** gives a 24-hour cookie.
+
+Because the test suite always re-injects saved cookies before checking whether login is needed (see [Auth State Persistence](#auth-state-persistence) below), the longer cookie lifetime means you only need to manually approve a Duo push **once every 7 days**, regardless of how many individual tests you run.
+
+> **Tip:** Anecdotally, Duo cookies become flaky before the full 7 days expire. Deleting `playwright/.auth/<endpoint-slug>.json` and re-authenticating every 24 hours is the most reliable approach when running tests frequently.
+
+---
+
+## Auth State Persistence
+
+The auth setup step ([`tests/suite/auth.setup.ts`](../tests/suite/auth.setup.ts)) stores session cookies in a per-endpoint file:
+
+```
+playwright/.auth/<endpoint-slug>.json
+```
+
+The slug is derived from `BASE_URL` by stripping the scheme and replacing non-alphanumeric characters with dashes:
+
+```
+https://dataverse-plus-staging.rdmc.unc.edu
+  → playwright/.auth/dataverse-plus-staging-rdmc-unc-edu.json
+```
+
+**Before each run** the setup step:
+1. Loads the saved cookies (if the file exists) into the browser context
+2. Navigates to the homepage
+3. Checks whether `DV_FULL_NAME` is visible inside the navbar user display element
+4. If visible → session is live, authentication skipped
+5. If not visible → runs the full adapter login flow and saves fresh cookies
+
+This means the Duo push only needs to be approved once per valid cookie window.
+
+---
+
+## Credentials
+
+Credentials are supplied via `.env` (gitignored, never committed):
+
+```dotenv
+DV_USERNAME=your-onyen
+DV_PASSWORD=your-password
+DV_FULL_NAME=Your Full Name
+```
+
+- `DV_USERNAME` / `DV_PASSWORD` — credentials for the target Dataverse instance via the configured adapter
+- `DV_FULL_NAME` — the display name Dataverse shows in the navbar after login (used to detect an existing session)
+
+---
+
+## Forcing a Fresh Login
+
+Delete the endpoint's auth file and re-run:
+
+```bash
+rm -f playwright/.auth/dataverse-plus-staging-rdmc-unc-edu.json
+npx playwright test
+```

package/docs/02_versioning_and_release.md

@@ -0,0 +1,146 @@
+Title: "02. Versioning & Release"
+Author: "Snehashish Reddy Manda"
+Email: "msreddy@unc.edu"
+Date: "June 2026"
+```
+
+# 02. Versioning & Release
+
+This document covers the versioning scheme, how releases are published to npm, and how downstream consumers pin to a specific Dataverse version.
+
+---
+
+## Versioning Philosophy
+
+`kunai-runner` tracks the Dataverse version it is designed to test. This makes it easy for an instance operator to find the correct suite for their deployment without reading changelogs.
+
+### Git tag format
+
+```
+DV_MAJOR.DV_MINOR.DV_PATCH.SUITE_PATCH
+```
+
+| Segment | Meaning |
+|---|---|
+| `DV_MAJOR.DV_MINOR.DV_PATCH` | The Dataverse release this suite targets (mirrors the upstream version tag) |
+| `SUITE_PATCH` | Increments with each new kunai-runner release for the same Dataverse version (new tests, bug fixes, etc.) |
+
+**Examples:**
+
+| Git tag | Meaning |
+|---|---|
+| `6.10.1.1` | First kunai-runner release for Dataverse 6.10.1 |
+| `6.10.1.2` | Second kunai-runner release, still targeting Dataverse 6.10.1 |
+| `6.11.0.1` | First kunai-runner release for Dataverse 6.11.0 |
+
+---
+
+## npm Versioning
+
+npm only accepts 3-part semver (`MAJOR.MINOR.PATCH`). The [publish workflow](../.github/workflows/publish.yml) automatically derives a valid npm version from the 4-part Git tag:
+
+```
+npm version = DV_MAJOR.DV_MINOR.(DV_PATCH × 100 + SUITE_PATCH)
+```
+
+| Git tag | npm version |
+|---|---|
+| `6.10.1.1` | `6.10.101` |
+| `6.10.1.2` | `6.10.102` |
+| `6.10.1.10` | `6.10.110` |
+| `6.11.0.1` | `6.11.1` |
+| `6.11.0.2` | `6.11.2` |
+
+> **Constraint:** `SUITE_PATCH` must stay below 100 (i.e. up to 99 suite releases per Dataverse version) to avoid collisions with the next `DV_PATCH`.
+
+The `version` field in [`package.json`](../package.json) is kept at `0.0.0` and is overwritten in-place by the workflow before packing. **Never edit it manually.**
+
+---
+
+## dist-tags
+
+In addition to the versioned npm publish, the workflow moves a **dist-tag** that always points at the latest kunai-runner build for a given Dataverse version.
+
+| dist-tag | Resolves to |
+|---|---|
+| `dv-6.10.1` | Latest `6.10.1.x` suite build |
+| `dv-6.11.0` | Latest `6.11.0.x` suite build |
+| `latest` | Absolute latest suite build across all DV versions |
+
+Inspect the full mapping at any time:
+
+```bash
+npm dist-tag ls kunai-runner
+```
+
+---
+
+## Installing
+
+```bash
+# Latest suite for a specific Dataverse version (recommended for pinned instances)
+npm install kunai-runner@dv-6.10.1
+
+# Absolute latest (always up to date)
+npm install kunai-runner
+
+# Exact npm version (maximum reproducibility)
+npm install kunai-runner@6.10.101
+```
+
+---
+
+## Release Workflow
+
+### Prerequisites (one-time setup)
+
+1. Create an npm **Classic Automation Token** at https://www.npmjs.com/settings/~/tokens
+2. Add it as a GitHub Actions secret named `NPM_TOKEN`:
+   **GitHub repo → Settings → Secrets and variables → Actions → New repository secret**
+
+### Publishing a new release
+
+```bash
+# 1. Commit and push all changes
+git push origin main
+
+# 2. Create and push the 4-part tag
+git tag 6.10.1.1
+git push origin 6.10.1.1
+```
+
+GitHub Actions automatically:
+- Derives the 3-part npm version (`6.10.101`)
+- Overwrites `package.json` version in the checkout
+- Runs `npm ci`
+- Publishes with provenance attestation
+- Moves the `dv-6.10.1` dist-tag to the new version
+
+Watch the run under **Actions** in the GitHub repository.
+
+---
+
+## Recovery: Bad Release
+
+npm versions are immutable after 72 hours. If a bad version ships:
+
+**1. Immediately move `latest` back to the last good version:**
+
+```bash
+npm dist-tag add kunai-runner@6.10.101 latest
+```
+
+**2. Deprecate the bad version:**
+
+```bash
+npm deprecate kunai-runner@6.10.102 "Breaking change — use dv-6.10.1 or upgrade to 6.10.103"
+```
+
+**3. Fix, commit, and tag a new patch:**
+
+```bash
+git tag 6.10.1.3
+git push origin 6.10.1.3
+```
+
+The `dv-6.10.1` dist-tag will automatically move to `6.10.103` once the workflow completes.

package/docs/backlog.md

@@ -0,0 +1,71 @@
+# Test Automation Backlog
+
+> Tracks test cases that are **out of scope for Playwright**, **not suitable for automation**, or **deferred** due to complexity or sprint constraints.  
+> Last updated: June 2026
+
+---
+
+## Legend
+
+| Badge | Meaning |
+|-------|---------|
+| 🚫 **Not Automatable** | Requires human judgement, physical hardware, or a third-party system that cannot be driven programmatically |
+| 🧩 **Playwright Limitation** | Technically automatable but blocked by a known Playwright constraint (e.g. file-system dialogs, browser extensions, OAuth pop-ups) |
+| ⏳ **Deferred** | In scope and automatable — deprioritized due to time, complexity, or dependency on a feature not yet stable |
+| ✅ **Resolved** | Was backlogged; now covered |
+
+---
+
+## @standard Tests
+
+### Preflight
+
+| # | Test Case | Badge | Reason / Notes | Priority |
+|---|-----------|-------|----------------|----------|
+| S-PF-01 | **Contact Email** — Submit a support email via the Support link (navbar) and the Contact link (landing page); verify delivery in the TDX UNC Dataverse support portal inbox; verify the "Contact us for support at…" address | 🚫 **Not Automatable** | Submitting real tickets against production TDX endpoints via automated tooling would risk triggering Falcon Sensor / DDoS protection on production infrastructure. Layout instability of the external portal makes reliable selectors impractical. Manual verification recommended on each release cycle. | Low — manual only |
+
+### Account Creation + Management
+
+| # | Test Case | Badge | Reason / Notes | Priority |
+|---|-----------|-------|----------------|----------|
+| S-AC-01 | **Log in using Username/Email** — Authenticate with a native Dataverse username/email credential | ⏳ **Deferred** | A `builtin` login adapter is implemented (`lib/login-adapters/builtin.ts`) but has not been verified against a live instance. Once confirmed working, set `LOGIN_ADAPTER=builtin` in `.env` to activate this flow. | Low |
+| S-AC-02 | **Log in using ORCID** — Authenticate via the ORCID OAuth provider | ⏳ **Deferred** | ORCID uses a full OAuth redirect flow through an external IdP. Automating it reliably requires either intercepting the OAuth callback (brittle) or scripting the ORCID login page itself (subject to ORCID's bot-detection and ToS). Not impossible — deprioritized. | Low |
+
+### Dataverse Management
+
+| # | Test Case | Badge | Reason / Notes | Priority |
+|---|-----------|-------|----------------|----------|
+| S-DM-01 | **Dataverse Contact Email** — Submit a contact message via the contact popup on a Dataverse collection page; verify the relay email is delivered to the collection author without exposing their address | 🧩 **Playwright Limitation** | The contact popup is protected by a server-side arithmetic CAPTCHA (e.g. "What is 2 + 8?") introduced specifically to prevent automated abuse of the email-relay endpoint. Solving it programmatically requires either OCR/DOM-scraping the challenge value at runtime or patching the CAPTCHA out in a test environment — neither is practical against production. Not automatable on the live environment. | Low — manual only |
+| S-DM-02 | **Theme + Widgets — Header/Link/Text Color Selection** — Click the three color-picker checkboxes on the Theme customization form, select a specific header color, link color, and text color, then save and verify the changes are reflected | 🧩 **Playwright Limitation** | Each checkbox opens a full 2D color-canvas + 1D hue-slider RGB palette. Playwright has no native color-picker API; targeting a precise color requires computing pixel coordinates on the canvas and dispatching raw mouse events — fragile across browser/OS rendering differences. The remaining Theme + Widgets customization (logo, footer, etc.) is covered by tests 05 and 06. | Medium — deferred to future sprint |
+
+### Permissions
+
+| # | Test Case | Badge | Reason / Notes | Priority |
+|---|-----------|-------|----------------|----------|
+| S-PM-01 | **Permissions — Edit Access & Cross-Account Verification** — Change the Dataverse collection's default access settings (e.g. restrict to specific users/groups), then log in as a second account that was not used for collection creation and verify the permission change is enforced | 🚫 **Not Automatable** (this sprint) | The suite is built around a single authenticated session. Multi-account scenarios require either a second identity or full login/logout cycles with careful cookie and storage-state management. All Permissions sub-tests are out of scope for this sprint. | High — revisit when multi-account auth is available |
+
+---
+
+## @21cfr Tests
+
+| # | Test Case | Badge | Reason / Notes | Priority |
+|---|-----------|-------|----------------|----------|
+| — | _No items yet_ | — | — | — |
+
+---
+
+## Cross-Suite / General
+
+| # | Test Case | Badge | Reason / Notes | Priority |
+|---|-----------|-------|----------------|----------|
+| — | _No items yet_ | — | — | — |
+
+---
+
+## Resolved Items
+
+> Items moved here once automation coverage is added.
+
+| # | Test Case | Resolution | Closed |
+|---|-----------|------------|--------|
+| X-CS-01 | **Unified single-suite architecture** — Merge the `standard` and `21cfrpart11` suites into one suite driven by single `BASE_URL`, `LOGIN_ADAPTER`, and `ROOT_DATAVERSE` env vars. | ✅ Completed in commit `f89862c`. All specs now live in `tests/suite/`. Three Playwright projects: `preflight`, `setup`, `suite`. Tests tagged `@standard` / `@21cfr` for per-profile filtering. | June 2026 |

package/docs/combine_videos.md

@@ -0,0 +1,109 @@
+# Combining Test-Run Videos into a Single MP4
+
+Playwright records a separate `.webm` clip for every test it runs.  
+The [`scripts/combine_videos.py`](../scripts/combine_videos.py) utility stitches all of those clips into one continuous MP4 file suitable for sharing with leadership or stakeholders.
+
+---
+
+## Prerequisites
+
+| Requirement | Install |
+|-------------|---------|
+| Python 3.8+ | ships with macOS / available via `brew install python` |
+| ffmpeg | `brew install ffmpeg` (macOS) · `sudo apt install ffmpeg` (Ubuntu) |
+
+> The script uses only Python standard-library modules (`os`, `pathlib`, `subprocess`, `tempfile`, `argparse`) — no `pip install` required.
+
+---
+
+## Quick Start
+
+Run the Playwright suite first so that `test-results/` is populated, then:
+
+```bash
+# Unified suite  →  test-results/suite_combined.mp4
+python scripts/combine_videos.py --suite suite
+
+# Custom output filename
+python scripts/combine_videos.py --suite suite --output leadership_demo.mp4
+
+# Absolute path
+python scripts/combine_videos.py --suite suite --output ~/Desktop/demo.mp4
+```
+
+---
+
+## CLI Reference
+
+```
+python scripts/combine_videos.py [OPTIONS]
+
+Options:
+  --suite NAME       REQUIRED. Playwright project name to collect videos for.
+                     For the unified suite use 'suite'.
+                     Default output: test-results/<suite>_combined.mp4
+  --output FILE      Custom output filename.
+                     Relative paths resolve inside test-results/.
+                     Absolute paths save wherever you point.
+  --results-root DIR Override the test-results root directory.
+                     Default: <repo-root>/test-results
+  -h, --help         Show this help message and exit.
+```
+
+### Examples
+
+```bash
+# Default output
+python scripts/combine_videos.py --suite suite
+
+# Custom relative output (saved inside test-results/)
+python scripts/combine_videos.py --suite suite --output leadership_demo.mp4
+
+# Absolute output path
+python scripts/combine_videos.py --suite suite --output ~/Desktop/leadership_demo.mp4
+
+# Point at a CI artifact download
+python scripts/combine_videos.py --suite suite --results-root /tmp/downloaded-results
+```
+
+---
+
+## How It Works
+
+1. **Discovery** — `os.walk()` recursively scans `test-results/` and collects every `.webm` file whose parent folder **ends with** `-<suite>`. Playwright names result folders `<spec-slug>-<test-title>-<project>`, so the project name is always the suffix.
+2. **Ordering** — Files are sorted by their full path, which preserves the lexicographic spec order (`01-preflight`, `02-account-management`, `10-assign-…`, etc.).
+3. **Concat list** — A temporary [ffconcat](https://ffmpeg.org/ffmpeg-formats.html#concat-1) text file is written listing all clips in order. Using the concat *demuxer* (rather than the concat *filter*) keeps the command simple and handles clips with different durations gracefully.
+4. **Encode** — ffmpeg runs a single-pass re-encode:
+
+   | Setting | Value | Rationale |
+   |---------|-------|-----------|
+   | Video codec | `libx264` (H.264) | Universal compatibility |
+   | Quality | CRF 22 | Good balance of quality vs. file size |
+   | Preset | `fast` | Reasonable encode time on a laptop |
+   | Audio codec | `aac` | Standard AAC at 128 kbps |
+   | Container | MP4 with `+faststart` | MOOV atom moved to front for web streaming |
+
+5. **Cleanup** — The temporary concat list is deleted whether the encode succeeds or fails.
+
+---
+
+## Output Location
+
+By default the finished file is written to:
+
+```
+test-results/<suite>_combined.mp4
+```
+
+The `test-results/` directory is already listed in [`.gitignore`](../.gitignore), so the MP4 will not be committed accidentally.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `[ERROR] No .webm files found` | Run the Playwright suite first; make sure `test-results/` is populated with folders ending in `-suite`. |
+| `[ERROR] ffmpeg not found on PATH` | Install ffmpeg (see Prerequisites above). |
+| Clips appear out of order | The sort is lexicographic on the full path. The existing `01-`, `02-`, `10-` naming convention handles ordering correctly. |
+| Audio/video out of sync | Some `.webm` clips may have been recorded without audio. ffmpeg will insert silence for those segments automatically. |

package/docs/test_data.md

@@ -0,0 +1,34 @@
+Title: "Test Data"
+Author: "Snehashish Reddy Manda"
+Email: "msreddy@unc.edu"
+Date: "June 2026"
+```
+
+# What are these data files?
+
+There are three test data files in [`tests/suite/test-data/`](../tests/suite/test-data/) used by the `@21cfr` dataset action tests.
+
+The content inside these files is dummy data and does not matter for the purposes of testing as long as the files themselves are not empty.
+
+---
+
+## Why do these three files matter?
+
+They are used in the combined **Dataset Actions** test (`13-dataset-actions.spec.ts`) which covers tests #7 through #11 of the 21 CFR Part 11 compliance suite.
+
+### Test #7 — Create Dataset
+
+| File | Purpose |
+|---|---|
+| `sample-dataset-file.txt` | First file uploaded during dataset creation |
+| `sample-dataset-file-2.txt` | Second file uploaded during dataset creation |
+
+Two files are used rather than one for a specific reason: **zip downloads**. Downloading a zip file containing multiple `.txt` files is easier to automate than downloading a single file because Dataverse renders a distinct **Download** button when two or more files are selected. That button is straightforward to target as a Playwright selector and lets the download verification test (test #15) work reliably with minimal flakiness. The button is only enabled at a minimum of two files, so we use the bare minimum to verify the user flow.
+
+### Test #10 — Replace File
+
+| File | Purpose |
+|---|---|
+| `replaced-sample-dataset-file.txt` | Replacement for `sample-dataset-file.txt` in the existing dataset |
+
+After the replace operation the dataset should still contain two files: `replaced-sample-dataset-file.txt` and `sample-dataset-file-2.txt`. All other dataset behavior should remain unaffected.

package/lib/auth-file.ts

@@ -0,0 +1,22 @@
+/**
+ * Derives a per-endpoint, per-browser auth storage-state file path from
+ * BASE_URL and an optional browser name.
+ *
+ * Example:
+ *   BASE_URL=https://dataverse-staging.rdmc.unc.edu, browser="firefox"
+ *   → playwright/.auth/dataverse-staging-rdmc-unc-edu-firefox.json
+ *
+ * This ensures switching BASE_URL between instances, or running against
+ * multiple browsers, never overwrites a previously saved session — each
+ * endpoint + browser combination keeps its own cookie jar.
+ */
+export function authFilePath(browser?: string): string {
+  const url = (process.env.BASE_URL ?? "default").trim();
+  const slug = url
+    .replace(/^https?:\/\//, "") // strip scheme
+    .replace(/\/$/, "") // strip trailing slash
+    .replace(/[^a-z0-9]/gi, "-") // any non-alphanumeric → dash
+    .toLowerCase();
+  const suffix = browser ? `-${browser}` : "";
+  return `playwright/.auth/${slug}${suffix}.json`;
+}

package/lib/login-adapters/builtin.ts

@@ -0,0 +1,42 @@
+import type { Page } from "@playwright/test";
+import type { LoginAdapter, LoginCredentials } from "./types";
+
+/**
+ * BuiltinAdapter
+ *
+ * Logs in using Dataverse's **built-in** Username/Email form.
+ *
+ * Flow (on /loginpage.xhtml):
+ *   1. Click the "Username/Email" button to reveal the built-in credential form
+ *   2. Fill #loginForm:credentialsContainer:0:credValue  (username / email)
+ *   3. Fill #loginForm:credentialsContainer:1:sCredValue (password)
+ *   4. Click the "Log In" button
+ *   5. Wait until the login page URL is gone
+ *
+ * NOTE: credentials for this adapter are not currently verified against a
+ * live instance.  The selectors were provided directly from the Dataverse
+ * login page source.
+ */
+export class BuiltinAdapter implements LoginAdapter {
+  async login(page: Page, credentials: LoginCredentials): Promise<void> {
+    await page.waitForURL(/loginpage/);
+
+    // Reveal the built-in username/password form
+    await page.getByRole("button", { name: "Username/Email" }).click();
+
+    await page
+      .locator("#loginForm\\:credentialsContainer\\:0\\:credValue")
+      .fill(credentials.username);
+
+    await page
+      .locator("#loginForm\\:credentialsContainer\\:1\\:sCredValue")
+      .fill(credentials.password);
+
+    await page.getByRole("button", { name: "Log In" }).click();
+
+    // Wait until we have left the login page
+    await page.waitForURL((url) => !/loginpage/.test(url.href), {
+      timeout: 30_000,
+    });
+  }
+}

package/lib/login-adapters/duo-mfa.ts

@@ -0,0 +1,41 @@
+import type { Page } from "@playwright/test";
+
+/**
+ * Shared Duo MFA challenge handler.
+ *
+ * After a Shibboleth / InCommon login submits credentials, Duo may intercept
+ * with a push/device-trust challenge.  Call this helper from any adapter that
+ * goes through UNC SSO (or any Duo-backed IdP) to handle both branches:
+ *
+ *   (A) "Yes, trust this browser" button appears  → click it and wait
+ *   (B) Device is already trusted                 → Duo auto-redirects, nothing to do
+ */
+export async function handleDuoMfa(page: Page): Promise<void> {
+  // Wait until we have left sso.unc.edu
+  await page.waitForURL((url) => !/sso\.unc\.edu/.test(url.href), {
+    timeout: 30_000,
+  });
+
+  if (!/duosecurity/.test(page.url())) return;
+
+  const yesBtn = page.getByText("Yes");
+  const yesAppeared = await Promise.race([
+    yesBtn.waitFor({ state: "visible", timeout: 30_000 }).then(() => true),
+    page
+      .waitForURL(
+        (url) =>
+          !/duosecurity/.test(url.href) && !/sso\.unc\.edu/.test(url.href),
+        { timeout: 30_000 },
+      )
+      .then(() => false),
+  ]);
+
+  if (yesAppeared) {
+    await yesBtn.click();
+    await page.waitForURL(
+      (url) => !/duosecurity/.test(url.href) && !/sso\.unc\.edu/.test(url.href),
+      { timeout: 60_000 },
+    );
+  }
+  // If !yesAppeared, waitForURL already resolved — nothing to do
+}