feat(webpage-observer): add workspace project

Author: patricktree

.prettierignore

@@ -7,3 +7,7 @@ pnpm-lock.yaml
 # coverage
 **/.nyc_output/**
 **/coverage/**
+
+# Playwright
+**/playwright-html-report/**
+**/test-results/**

packages/webpage-observer/.eslintrc.cjs

@@ -0,0 +1,7 @@
+module.exports = {
+  extends: ['@patricktree/eslint-config/eslint-ecma.cjs'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+  },
+  ignorePatterns: ['**/playwright-html-report/**'],
+};

packages/webpage-observer/.gitignore

@@ -0,0 +1,2 @@
+playwright-html-report
+test-results

packages/webpage-observer/AGENTS.md

@@ -0,0 +1,8 @@
+# Agent Guide for `@patricktree/webpage-observer`
+
+- Source lives in `src/` (TypeScript) and compiles to `dist/`; edit TS only and run `pnpm run build` (tsc via `tsconfig.project.json`) to refresh the JS Playwright uses.
+- Use `pnpm` (workspace root has the lockfile). Package scripts: `pnpm run build`, `pnpm run dev` (watch), `pnpm run lint` / `pnpm run lint:fix`, `pnpm run nuke`/`nuke:artifacts`.
+- Playwright tests run from compiled JS: `pnpm start` pulls `mcr.microsoft.com/playwright:v1.56.0-noble` and executes `playwright test --config ./dist/playwright.config.js`. Build first if `dist/` is stale. Run e.g. `pnpm start './src/sentry.spec.ts'` to run tests just for this file (seems like Playwright uses the source file names to filter by file name).
+- Playwright file filters are regexes against test file paths; use file-based patterns like `jsnation` instead of test titles or URLs like `jsnation.com`.
+- Default test browser runs inside a Docker “Playwright Server” container (host networking, X11 forwarded when not CI). Docker must be available; tests need outbound internet to reach the target sites.
+- Path alias `#pkg/*` maps to `./src/*`; keep snapshots under `snapshots/` (see `snapshotPathTemplate` in `src/playwright.config.ts`). Update screenshots intentionally (`--update-snapshots`) and expect EU/Vienna locale/timezone defaults.

packages/webpage-observer/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@patricktree/webpage-observer",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#pkg/*": "./dist/*"
+  },
+  "scripts": {
+    "build": "superturbo run turbo:build",
+    "dev": "pnpm run build --watch --preserveWatchOutput",
+    "internal:compile": "tsc --build ./tsconfig.json",
+    "lint": "superturbo run turbo:lint",
+    "lint:file": "eslint --max-warnings 0",
+    "lint:fix": "superturbo run turbo:lint:fix",
+    "nuke": "pnpm run nuke:artifacts && del-cli node_modules",
+    "nuke:artifacts": "del-cli dist \"*.tsbuildinfo\"",
+    "start": "docker pull mcr.microsoft.com/playwright:v1.57.0-noble && playwright test --config ./dist/playwright.config.js",
+    "turbo:build": "pnpm run internal:compile",
+    "turbo:lint": "pnpm run lint:file .",
+    "turbo:lint:fix": "pnpm run lint:file . --fix"
+  },
+  "dependencies": {
+    "@patricktree/commons-node": "workspace:^",
+    "@playwright/test": "1.57.0",
+    "type-fest": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20"
+  }
+}

packages/webpage-observer/snapshots/jsnation.spec.js/jsnation-com-tickets-1-chromium-docker.png

@@ -0,0 +1,14 @@
+/* eslint-disable n/no-process-env -- configs are the only place where reading from process.env is allowed */
+
+export const config = {
+  CI: process.env['CI'],
+
+  /**
+   * if `--inspect-publish-uid` is in env variable `NODE_OPTIONS` - which is a Node.js feature to
+   * allow easier debugging - it indicates that the current `playwright test` run is debugged by an
+   * engineer (e.g. via VS Code Debug Terminal)
+   */
+  isDebuggingSession: process.env['NODE_OPTIONS']?.includes('--inspect-publish-uid'),
+
+  isPlaywrightStartedWithDebug: process.env['PWDEBUG'] === '1',
+};

packages/webpage-observer/src/config.ts

@@ -0,0 +1,9 @@
+import { config } from '#pkg/config.js';
+
+export const playwrightBrowserConfig =
+  /*
+   * `--debug` does not correctly work when Playwright is running browsers in the Playwright Server Docker container --> run Playwright browsers locally instead
+   */
+  config.isPlaywrightStartedWithDebug
+    ? ({ browser: 'local' } as const)
+    : ({ browser: 'docker', port: 36_719 } as const);

packages/webpage-observer/src/constants.ts

@@ -0,0 +1,11 @@
+import { expect, test } from '@playwright/test';
+
+test('jsnation.com tickets', async ({ page }) => {
+  const baseURL = new URL('https://jsnation.com/');
+  await page.goto(baseURL.href, { waitUntil: 'domcontentloaded' });
+  await page.pause();
+
+  const ticketsPrices = page.locator('#tickets > div > div.prices');
+  await expect(ticketsPrices).toBeVisible({ timeout: 60_000 });
+  await expect.soft(ticketsPrices).toHaveScreenshot();
+});

packages/webpage-observer/src/jsnation.spec.ts

@@ -0,0 +1,92 @@
+import '#pkg/set-env.js';
+
+import { devices, type PlaywrightTestConfig, type ReporterDescription } from '@playwright/test';
+import os from 'node:os';
+
+import { config } from '#pkg/config.js';
+import { playwrightBrowserConfig } from '#pkg/constants.js';
+
+const countOfCpus = os.cpus().length;
+const workers = countOfCpus !== 0 ? (countOfCpus <= 4 ? countOfCpus : 4) : undefined;
+
+const htmlReporter: ReporterDescription = [
+  'html',
+  { open: 'never', outputFolder: '../playwright-html-report' },
+];
+
+const playwrightConfig: PlaywrightTestConfig = {
+  fullyParallel: true,
+  reporter: config.CI ? [htmlReporter, ['github']] : [htmlReporter],
+  testMatch: ['*.spec.js'],
+  globalTimeout: 1000 * 8 * 60, // 8 minutes
+  projects: [
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+        // opt into "New Headless" chromium (https://playwright.dev/docs/browsers#chromium-new-headless-mode, https://developer.chrome.com/docs/chromium/headless)
+        channel: 'chromium',
+      },
+    },
+  ],
+
+  /**
+   * increase timeout to 30 minutes and set workers count to 1 if we are in a debugging session
+   */
+  timeout: config.isDebuggingSession ? 1000 * 60 * 30 : undefined,
+  workers: config.isDebuggingSession ? 1 : workers,
+
+  // fail a Playwright run in CI if some test.only is in the source code
+  forbidOnly: !!config.CI,
+
+  snapshotPathTemplate: `{testDir}/../snapshots/{testFilePath}/{arg}-{projectName}-${playwrightBrowserConfig.browser === 'docker' ? 'docker' : '{platform}'}{ext}`,
+
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.03,
+    },
+  },
+
+  use: {
+    /* have consistent timezone and locale */
+    timezoneId: 'Europe/Vienna',
+    locale: 'de-AT',
+
+    // always capture trace (seems to not have any performance impact)
+    trace: 'on',
+
+    // always capture video (seems to not have any performance impact)
+    video: 'on',
+  },
+
+  webServer:
+    playwrightBrowserConfig.browser === 'docker'
+      ? {
+          // start the Playwright server in a docker container
+          command: createDockerRunCommand(playwrightBrowserConfig.port),
+          url: `http://127.0.0.1:${playwrightBrowserConfig.port}/`,
+          stdout: 'pipe',
+          stderr: 'pipe',
+          timeout: 30_000,
+          gracefulShutdown: {
+            signal: 'SIGTERM',
+            timeout: 10_000,
+          },
+          reuseExistingServer: !config.CI,
+        }
+      : undefined,
+};
+
+// eslint-disable-next-line import/no-default-export -- needs to be default export for Playwright
+export default playwrightConfig;
+
+function createDockerRunCommand(port: number) {
+  let dockerRunCommand = `docker run --rm --init --workdir /home/pwuser --user pwuser --network host`;
+  if (!config.CI) {
+    // on development machines, we forward the X11 socket to the host system to allow GUI applications to run from within the container
+    dockerRunCommand += ` -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix`;
+  }
+  dockerRunCommand += ` mcr.microsoft.com/playwright:v1.57.0-noble /bin/sh -c "npx -y playwright@1.57.0 run-server --port ${port} --host 0.0.0.0"`;
+
+  return dockerRunCommand;
+}