Skip to content

Playwright Coverage ​

This document explains how the Playwright suite runs today and what user-facing cases it already covers.

How the suite is wired ​

Important runtime behavior:

  • Playwright does not boot the app for you; the app must already be running
  • ensureTestEnvLoaded() loads Next env files before the suite starts
  • E2E defaults semantic indexing to enabled with the fake provider when no Gemini key is present
  • E2E defaults Redis to redis://127.0.0.1:6379 unless PLAYWRIGHT_USE_LOCAL_REDIS=0

Commands ​

From secure-vault/:

powershell
npm run test:e2e

Opens Playwright UI mode against an already running app.

powershell
npm run test:e2e:managed

Runs the suite headlessly against an already running app.

Prerequisites ​

For meaningful E2E coverage you need:

  • the app running at the configured base URL
  • MariaDB available and initialized
  • Redis available unless you are intentionally testing with Redis disabled
  • valid R2_* credentials for real upload and download flows
  • a local env file that lets the app create users, sessions, files, and shares

CI note:

  • .github/workflows/test.yml currently runs lint plus Vitest only
  • Playwright is intentionally left out of CI for now

Coverage by area ​

AreaSpec filesCovered cases
Auth and account recoverypassword-reset.spec.ts, upload-user-bootstrap.spec.tssignup bootstrap, verified-on-signup behavior, forgot-password request privacy, session invalidation after reset, used or expired reset codes, locked reset codes
Upload flowupload-smoke.spec.tsmixed batch uploads, queue visibility, success states, oversize rejection, semantic indexing after upload, upload success even when indexing cannot start
Upload queue controlupload-queue-controls.spec.ts, upload-global-queue.spec.tssaturation, waiting for slots, cancel while queued, pause, resume, remove, resume from status endpoint, resume after reload, skip completed chunks
File and folder managementfile-actions.spec.ts, file-browser-controls.spec.tsfolder creation, file rename, file move, folder move, descendant-move prevention, deletes, bulk actions, grid and list modes, filename search, sorting, breadcrumb updates
File accessfile-access.spec.tsreal multi-chunk downloads with checksum verification, unauthorized preview and download returning 404
Sharing: owner flowsshare-owner-management.spec.ts, share-owner-validation.spec.ts, share-download-limits.spec.tscreate, edit, and revoke links, download-cap validation, duplicate email normalization, switch restricted links back to public, owner UI reflecting usage limits
Sharing: visitor flowsshare-public-file.spec.ts, share-preview-variants.spec.ts, share-folder.spec.ts, share-restricted-file.spec.ts, share-restricted-edge-cases.spec.ts, share-session-invalidation.spec.tsdirect public previews, shared PDF image preview, Redis cache hit/miss signaling for shared PDF pages, public downloads, folder navigation, restricted email allowlists, OTP unlock, wrong-code lockouts, expired OTPs, OTP replacement, visitor sign-out, revoked or expired sessions
Share auditingshare-access-logging.spec.tsrestricted unlock logs and successful download logging
Trashtrash.spec.tsdelete, restore, permanent delete, subtree trash behavior, mixed-item empty trash, restore conflict handling
Storage, filename search, and semantic searchstorage-search.spec.ts, semantic-indexing.spec.tszero states, storage card updates, filename search thresholds, semantic result rendering, page-range context, multi-page window matches, re-index and retry actions, soft-deleted files disappearing from semantic results
Activityactivity.spec.tsempty state, malformed cursors, upload completion, share create and revoke entries, share access entries, soft-deleted targets remaining readable in activity

Current suite shape ​

The suite mixes real end-to-end flows with a few controlled mocks where deterministic browser behavior matters more than backend setup cost.

Examples:

  • real uploads and downloads are exercised in the upload and file-access specs
  • queue-control specs mock some upload endpoints so pause, resume, and cancel behavior stays deterministic
  • helper utilities create and clean up test users so specs can own their own setup

Shared PDF Preview Cache Coverage ​

The shared PDF preview cache path is covered in the end-to-end suite through share-preview-variants.spec.ts.

What that spec validates today:

  • a public shared PDF loads through /api/share/:token/pdf-preview
  • the rendered page image loads through /api/share/:token/pdf-preview/pages/1
  • the response content-type is image/webp, not application/pdf
  • the first page-image response reports X-Preview-Cache: miss
  • a second fresh browser context opening the same shared PDF reports X-Preview-Cache: hit

Why the header exists:

  • Playwright can observe network traffic, but without a deterministic signal it cannot distinguish a Redis-served response from a service/R2-served response
  • X-Preview-Cache gives the suite a stable assertion surface for the hot-cache path without exposing any sensitive cache internals to end users

Important limit of this coverage:

  • the test proves the page route can warm Redis and then serve a later request from Redis
  • access checks still happen before the cache lookup, but that authorization ordering is primarily enforced by route-level tests and the architecture itself rather than by a browser-only assertion

What is not covered yet ​

  • cross-browser coverage beyond Chromium
  • visual regression testing
  • dedicated mobile viewport coverage
  • Playwright execution in CI
  • container-specific smoke tests for the Compose web and worker services

Built with VitePress and deployed through GitHub Pages.