Oxicloud/tests/e2e/scenarios/helpers.ts

import { test as base, Page, expect } from '@playwright/test';
import { startStack, Stack } from '../fixtures/oxicloud-stack';

/**
 * When `OXICLOUD_E2E_CONTAINERS=1`, each Playwright worker boots its own
 * isolated DB + app stack via Testcontainers (see `playwright.containers.
 * config.ts`). Otherwise the legacy single-server webServer flow is used
 * and this fixture is an inert pass-through.
 */
const USE_CONTAINERS = process.env.OXICLOUD_E2E_CONTAINERS === '1';

type WorkerFixtures = {
  /** The per-worker isolated stack, or `null` in the legacy webServer flow. */
  stack: Stack | null;
};

/**
 * Extended `test` fixture with two responsibilities:
 *
 *  1. `stack` (worker-scoped) — in container mode, starts a dedicated
 *     DB + app stack per worker, seeds its admin, and tears it down at
 *     worker exit. The app instance is reused across every test the worker
 *     runs, so container startup is paid once per worker, not per test.
 *  2. `page` — fails any test that produces an unhandled browser-side JS
 *     error (SyntaxError, ReferenceError, uncaught rejection, etc.).
 *
 * Import `test` from this module instead of `@playwright/test` so every spec
 * gets both behaviours automatically without per-file boilerplate.
 */
export const test = base.extend<object, WorkerFixtures>({
    stack: [
        async ({}, use) => {
            if (!USE_CONTAINERS) {
                await use(null);
                return;
            }
            const stack = await startStack();
            try {
                await seedAdmin(stack.baseURL);
                await use(stack);
            } finally {
                await stack.stop();
            }
        },
        // Worker-scoped: booting Postgres + the app container (image build on
        // first run, migrations on boot) can take well over the default 30s
        // fixture timeout. Match the 180s container startup budget in startStack.
        { scope: 'worker', timeout: 200_000 },
    ],

    // Point relative `page.goto('/')` at the per-worker stack when present;
    // otherwise fall back to the baseURL configured in the project (the
    // legacy webServer at :8087).
    baseURL: async ({ stack }, use, testInfo) => {
        await use(stack ? stack.baseURL : testInfo.project.use.baseURL);
    },

    page: async ({ page }, use) => {
        const jsErrors: Error[] = [];
        page.on('pageerror', (err) => jsErrors.push(err));
        await use(page);
        if (jsErrors.length > 0) {
            throw new Error(
                `${jsErrors.length} unhandled JS error(s) on page:\n` +
                jsErrors.map((e) => `  • ${e.message}`).join('\n')
            );
        }
    },
});

export const TEST_ADMIN = {
  username: 'admin',
  email: 'testadmin@example.com',
  password: 'TestPassword1!',
};

/**
 * Create the first-admin account via the public `POST /api/setup` route.
 * Idempotent: a 409 (admin already exists) is treated as success so the
 * call is safe to retry and to run once per worker.
 *
 * Shared by `global-setup.ts` (legacy flow, single server) and the
 * worker-scoped `stack` fixture (container flow, one server per worker).
 */
export async function seedAdmin(baseURL: string, admin = TEST_ADMIN): Promise<void> {
  const res = await fetch(`${baseURL}/api/setup`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      username: admin.username,
      email: admin.email,
      password: admin.password,
    }),
  });
  if (!res.ok && res.status !== 409) {
    throw new Error(`Admin setup failed: ${res.status} ${await res.text()}`);
  }
}

/**
 * Authenticate the page's browser context via the API, so a subsequent
 * `page.goto()` loads already signed in — no UI clicks. Selector-independent,
 * which keeps it robust while the SPA login markup is still in flux.
 *
 * `POST /api/auth/login` is CSRF-exempt and sets the auth cookies on the
 * context's (shared) cookie jar, so `page.request` here authenticates the
 * page too. Use this at the top of any spec that needs an authenticated app
 * (and in the codegen recorder, so you record post-login flows).
 */
export async function apiLogin(page: Page, admin = TEST_ADMIN): Promise<void> {
  const res = await page.request.post('/api/auth/login', {
    data: { username: admin.username, password: admin.password },
  });
  if (!res.ok()) {
    throw new Error(`apiLogin failed: ${res.status()} ${await res.text()}`);
  }
}

/**
 * Build the `x-csrf-token` header for a cookie-authenticated, state-changing
 * request. The server uses a double-submit cookie: login sets a non-HttpOnly
 * `oxicloud_csrf` cookie, and POST/PUT/DELETE must echo its value in the
 * header (see `csrf_middleware`). Returns `{}` if no cookie is present (e.g.
 * not logged in), letting the caller's request fail with the real 4xx.
 */
async function csrfHeaders(page: Page): Promise<Record<string, string>> {
  const cookies = await page.context().cookies();
  const token = cookies.find((c) => c.name === 'oxicloud_csrf')?.value;
  return token ? { 'x-csrf-token': token } : {};
}

/** A folder as returned by the API (subset we use). */
export type ApiFolder = { id: string; parent_id: string | null };

/**
 * Create a folder via the API and return it. `parentId` omitted ⇒ the folder
 * is created in the caller's home (root) folder, and the returned `parent_id`
 * is that home folder's id (handy as the target for "root" file uploads, which
 * require an explicit folder id). Requires the page to already be
 * authenticated (see `apiLogin`).
 */
export async function apiCreateFolder(
  page: Page,
  name: string,
  parentId?: string,
): Promise<ApiFolder> {
  const res = await page.request.post('/api/folders', {
    headers: await csrfHeaders(page),
    data: parentId ? { name, parent_id: parentId } : { name },
  });
  if (!res.ok()) {
    throw new Error(`apiCreateFolder(${name}) failed: ${res.status()} ${await res.text()}`);
  }
  return (await res.json()) as ApiFolder;
}

/**
 * Create a regular user via the admin API. Requires the page to be authenticated
 * as an admin (see `apiLogin`). Returns the created username. Handy for tests
 * that need a second account (sharing, group membership, recipient search).
 */
export async function apiAdminCreateUser(page: Page, username: string): Promise<string> {
  const res = await page.request.post('/api/admin/users', {
    headers: await csrfHeaders(page),
    data: {
      username,
      password: 'TestPassword1!',
      email: `${username}@example.test`,
      role: 'user',
      quota_bytes: 1073741824,
    },
  });
  if (!res.ok()) {
    throw new Error(`apiAdminCreateUser(${username}) failed: ${res.status()} ${await res.text()}`);
  }
  return username;
}

/**
 * Create a group via the API (requires an authenticated admin/manager). Returns
 * the group name. Useful for sharing-with-group and group-membership tests.
 */
export async function apiCreateGroup(page: Page, name: string): Promise<string> {
  const res = await page.request.post('/api/groups', {
    headers: await csrfHeaders(page),
    data: { name, description: null },
  });
  if (!res.ok()) {
    throw new Error(`apiCreateGroup(${name}) failed: ${res.status()} ${await res.text()}`);
  }
  return name;
}

/** Move a folder to trash via the API (DELETE /api/folders/{id}). */
export async function apiTrashFolder(page: Page, folderId: string): Promise<void> {
  const res = await page.request.delete(`/api/folders/${folderId}`, {
    headers: await csrfHeaders(page),
  });
  if (!res.ok()) {
    throw new Error(`apiTrashFolder(${folderId}) failed: ${res.status()} ${await res.text()}`);
  }
}

/**
 * Record an access in the user's "recent" list (POST /api/recent/{type}/{id})
 * so the /recent route has deterministic content. Best-effort: a non-2xx is
 * tolerated so callers don't fail on a recents quirk.
 */
export async function apiRecordRecent(
  page: Page,
  itemType: 'file' | 'folder',
  id: string,
): Promise<void> {
  await page.request
    .post(`/api/recent/${itemType}/${id}`, { headers: await csrfHeaders(page) })
    .catch(() => {});
}

/** Empty the trash via the API (DELETE /api/trash/empty) for a clean slate. */
export async function apiEmptyTrash(page: Page): Promise<void> {
  const res = await page.request.delete('/api/trash/empty', { headers: await csrfHeaders(page) });
  if (!res.ok()) {
    throw new Error(`apiEmptyTrash failed: ${res.status()} ${await res.text()}`);
  }
}

/** A file to seed: its name, MIME type, and raw bytes. */
export type SeedFile = { name: string; mimeType: string; body: Buffer };

/**
 * Upload one file via the API into `folderId`. The target folder is
 * **required**: the server resolves the file's owner from its parent folder
 * and rejects an upload with no `folder_id` ("folder_id is required to
 * determine file owner"). For a "root" file, pass the home folder's id — the
 * `parent_id` returned by `apiCreateFolder(name)`.
 *
 * The `folder_id` field is sent before `file` because the upload handler
 * parses the multipart stream in order and permission-checks the target folder
 * before spooling the body.
 */
export async function apiUploadFile(
  page: Page,
  file: SeedFile,
  folderId: string,
): Promise<void> {
  const filePart = { name: file.name, mimeType: file.mimeType, buffer: file.body };
  const res = await page.request.post('/api/files/upload', {
    headers: await csrfHeaders(page),
    multipart: { folder_id: folderId, file: filePart },
  });
  if (!res.ok()) {
    throw new Error(`apiUploadFile(${file.name}) failed: ${res.status()} ${await res.text()}`);
  }
}

/**
 * A small library of files spanning common types (text, markdown, JSON, CSV,
 * PNG image, PDF), so a recording starts from a browser that exercises the
 * different icons / previews / row renderers. Bytes are tiny but valid.
 */
export const SAMPLE_FILES = {
  text: (): SeedFile => ({
    name: 'notes.txt',
    mimeType: 'text/plain',
    body: Buffer.from('Hello from the codegen seed.\nLine two.\n'),
  }),
  markdown: (): SeedFile => ({
    name: 'README.md',
    mimeType: 'text/markdown',
    body: Buffer.from('# Seeded\n\nA **markdown** file for the file browser.\n'),
  }),
  json: (): SeedFile => ({
    name: 'config.json',
    mimeType: 'application/json',
    body: Buffer.from(JSON.stringify({ seeded: true, items: [1, 2, 3] }, null, 2)),
  }),
  csv: (): SeedFile => ({
    name: 'data.csv',
    mimeType: 'text/csv',
    body: Buffer.from('id,name,size\n1,alpha,10\n2,beta,20\n'),
  }),
  png: (): SeedFile => ({
    name: 'pixel.png',
    mimeType: 'image/png',
    // 1×1 transparent PNG.
    body: Buffer.from(
      'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
      'base64',
    ),
  }),
  pdf: (): SeedFile => ({
    name: 'sample.pdf',
    mimeType: 'application/pdf',
    body: Buffer.from(
      '%PDF-1.1\n1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj\n' +
        '2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj\n' +
        '3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 100 100]>>endobj\n' +
        'trailer<</Root 1 0 R>>\n%%EOF\n',
    ),
  }),
};

/**
 * Seed a representative tree of folders and files of different types for the
 * authenticated user, so a codegen recording (or a test) starts from a
 * populated file browser. Idempotent enough for one run per worker; re-running
 * creates duplicate names (the backend allows them). Requires `apiLogin` first.
 *
 * Layout created in the user's home folder:
 *
 *   config.json                 (home/root)
 *   pixel.png                   (home/root)
 *   Documents/                  README.md, notes.txt
 *   Documents/Reports/          data.csv, sample.pdf
 *   Images/                     pixel.png
 *
 * Returns the created folder ids (plus the resolved `home` id) so callers can
 * deep-link or assert.
 */
export async function seedFilesAndFolders(
  page: Page,
): Promise<{ home: string; documents: string; reports: string; images: string }> {
  const documents = await apiCreateFolder(page, 'Documents');
  const reports = await apiCreateFolder(page, 'Reports', documents.id);
  const images = await apiCreateFolder(page, 'Images');

  // Created-at-root folders carry the home folder id as their parent — use it
  // as the target for the "root" files (uploads require an explicit folder).
  const home = documents.parent_id;
  if (!home) {
    throw new Error('seedFilesAndFolders: could not resolve home folder id from a root folder');
  }

  await apiUploadFile(page, SAMPLE_FILES.json(), home);
  await apiUploadFile(page, SAMPLE_FILES.png(), home);
  await apiUploadFile(page, SAMPLE_FILES.markdown(), documents.id);
  await apiUploadFile(page, SAMPLE_FILES.text(), documents.id);
  await apiUploadFile(page, SAMPLE_FILES.csv(), reports.id);
  await apiUploadFile(page, SAMPLE_FILES.pdf(), reports.id);
  await apiUploadFile(page, SAMPLE_FILES.png(), images.id);

  return { home, documents: documents.id, reports: reports.id, images: images.id };
}

/**
 * Log in as the test admin and wait until the main app is fully initialized.
 *
 * We wait for two things after the login redirect:
 *  1. `#sidebar` — confirms the main HTML has loaded.
 *  2. `#user-avatar-btn .user-vignette` — confirms that `setupUserMenu()` has
 *     run and mounted the avatar vignette.  This is the earliest reliable
 *     signal that the click-handler on the avatar button is attached, so any
 *     subsequent test that opens the user menu will not race against JS startup.
 *
 * Without (2), CI (Ubuntu + Xvfb) occasionally clicks the button before the
 * event listener is registered because the JS runtime is slower than on macOS.
 */
export async function loginAsAdmin(page: Page) {
  await goToLoginPage(page);
  await page.locator('#login-username').fill(TEST_ADMIN.username);
  await page.locator('#login-password').fill(TEST_ADMIN.password);
  await page.locator('#login-submit').click();
  await expect(page.locator('#sidebar')).toBeVisible({ timeout: 15_000 });
  // Wait for the JS app to initialise: avatar vignette present ⟹ click handler attached.
  await expect(page.locator('#user-avatar-btn .user-vignette')).toBeAttached({ timeout: 10_000 });
}

/**
 * Navigate to `/` and land on the login panel, handling the language selector
 * if it appears (fresh localStorage). The admin account is guaranteed to exist
 * because globalSetup created it before any test ran.
 */
export async function goToLoginPage(page: Page) {
  await page.goto('/');

  // Both panels start with .hidden — wait for JS to reveal one.
  // Use expect() (5 s default) rather than waitForSelector() (30 s) so a JS
  // crash fails fast instead of hanging for the full test timeout.
  await expect(
    page.locator('#language-panel:not(.hidden), #login-panel:not(.hidden)').first()
  ).toBeAttached();

  if (await page.locator('#language-panel').isVisible()) {
    await page.locator('#language-continue').click();
  }

  await expect(page.locator('#login-panel')).toBeVisible();
}