@anzusystems/common-admin 2.0.0-rc.10 → 2.0.0-rc.11

package/package.json

@@ -40,7 +40,7 @@
     },
     "./package.json": "./package.json"
   },
-  "version": "2.0.0-rc.10",
+  "version": "2.0.0-rc.11",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -80,7 +80,7 @@
     "release:cleanup": "npx -y --allow-git=all github:anzusystems/release-tools#main cleanup"
   },
   "devDependencies": {
-    "@anzusystems/common-admin": "2.0.0-rc.10",
+    "@anzusystems/common-admin": "2.0.0-rc.11",
     "@intlify/unplugin-vue-i18n": "^11.2.8",
     "@mdi/font": "^7.4.47",
     "@sentry/vite-plugin": "11.11.0",
@@ -109,13 +109,13 @@
     "cropperjs": "2.3.1",
     "dayjs": "1.11.23",
     "eslint": "^10.14.0",
-    "eslint-plugin-oxlint": "1.90.0",
+    "eslint-plugin-oxlint": "1.92.0",
     "eslint-plugin-pinia": "^0.4.2",
     "eslint-plugin-vue": "10.12.0",
     "eslint-plugin-vuetify": "^2.7.3",
     "npm-run-all2": "^9.0.4",
-    "oxfmt": "^0.76.0",
-    "oxlint": "1.90.0",
+    "oxfmt": "^0.77.0",
+    "oxlint": "1.92.0",
     "pinia": "4.1.0",
     "playwright": "^1.65.0",
     "postcss": "^8.5.32",
@@ -156,11 +156,11 @@
     "axios": "^1.21.0",
     "dayjs": "^1.11.23",
     "eslint": "^10.14.0",
-    "eslint-plugin-oxlint": "^1.90.0",
+    "eslint-plugin-oxlint": "^1.92.0",
     "eslint-plugin-pinia": "^0.4.2",
     "eslint-plugin-vue": "^10.12.0",
     "eslint-plugin-vuetify": "^2.7.3",
-    "oxlint": "^1.90.0",
+    "oxlint": "^1.92.0",
     "pinia": "^4.1.0",
     "playwright": "^1.65.0",
     "socket.io-client": "^4.8.4",

package/src/e2e/env.d.mts

@@ -0,0 +1,46 @@
+/** The environments an admin's e2e suite runs against. */
+export type E2eEnv = 'local' | 'devel' | 'staging'
+
+export interface LoadE2eEnvOptions {
+  /** The e2e project's folder, holding `.env.<env>` (usually `__dirname` of `playwright.config.ts`). */
+  dir: string
+  /** The env when `E2E_ENV` is not set, e.g. `bin/test` without `-e`. */
+  defaultEnv: E2eEnv
+  /**
+   * A file read first, under `.env.<env>`, which overrides it, e.g. `.env.dist` when it holds the local stack's
+   * values. Without it, `.env.<env>` is the only file, and variables already set in the shell win.
+   */
+  base?: string
+}
+
+export type LoadE2eEnv = (options: LoadE2eEnvOptions) => E2eEnv
+export type E2eEnvOf = () => E2eEnv
+export type E2eEnvLabel = () => string
+export type IsLocalStack = () => boolean
+
+export declare const E2E_ENVS: readonly E2eEnv[]
+
+/**
+ * Sets `E2E_ENV` (to `defaultEnv` when unset) and loads `<dir>/.env.<env>` into `process.env`. Throws on an env
+ * other than `local`, `devel` and `staging`, and when the file of `devel` or `staging` is missing; for `local` a
+ * missing file is only a warning. Returns the env.
+ */
+export declare const loadE2eEnv: LoadE2eEnv
+
+/** The env `loadE2eEnv` set. Throws when it has not run. */
+export declare const e2eEnv: E2eEnvOf
+
+/** The env as the suites' titles show it: `LOCAL`, `DEV` or `STG`. */
+export declare const e2eEnvLabel: E2eEnvLabel
+
+/** Whether the suite runs against the local Docker stack. */
+export declare const isLocalStack: IsLocalStack
+
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      /** Set by `loadE2eEnv` in `playwright.config.ts`, so a comparison with another name fails the type check. */
+      E2E_ENV: E2eEnv
+    }
+  }
+}

package/src/e2e/env.mjs

@@ -0,0 +1,78 @@
+// @ts-check
+import fs from 'node:fs'
+import path from 'node:path'
+import { parseEnv } from 'node:util'
+
+/**
+ * Which environment an admin's e2e suite runs against: one variable, `E2E_ENV`, with the same three names in
+ * every admin. `bin/test -e <env>` sets it; left unset, the admin's `playwright.config.ts` picks its default.
+ * The env file is read with Node's own parser (`util.parseEnv`), so the package needs no dotenv.
+ *
+ * @typedef {import('./env.mjs').E2eEnv} E2eEnv
+ */
+
+/** @type {readonly E2eEnv[]} */
+export const E2E_ENVS = Object.freeze(['local', 'devel', 'staging'])
+
+/** @type {Readonly<Record<E2eEnv, string>>} */
+const LABELS = Object.freeze({ local: 'LOCAL', devel: 'DEV', staging: 'STG' })
+
+/**
+ * @param {unknown} value
+ * @returns {value is E2eEnv}
+ */
+const isE2eEnv = (value) => typeof value === 'string' && /** @type {readonly string[]} */ (E2E_ENVS).includes(value)
+
+/** @param {unknown} value @param {string} source */
+const invalid = (value, source) => new Error(`${source} must be one of ${E2E_ENVS.join(', ')}; got "${String(value)}".`)
+
+/**
+ * Sets what the file holds in `process.env`. Without `override`, a variable already set (by the shell or an
+ * earlier file) is kept, as dotenv does.
+ *
+ * @param {string} file
+ * @param {boolean} override
+ */
+const applyEnvFile = (file, override) => {
+  const values = parseEnv(fs.readFileSync(file, 'utf8'))
+  for (const [key, value] of Object.entries(values)) {
+    if (override || process.env[key] === undefined) process.env[key] = value
+  }
+}
+
+/** @type {import('./env.mjs').LoadE2eEnv} */
+export function loadE2eEnv({ dir, defaultEnv, base }) {
+  if (!isE2eEnv(defaultEnv)) throw invalid(defaultEnv, 'The default env')
+  const env = process.env.E2E_ENV || defaultEnv
+  if (!isE2eEnv(env)) throw invalid(env, 'E2E_ENV')
+
+  const envFile = path.resolve(dir, `.env.${env}`)
+  const exists = fs.existsSync(envFile)
+  // A deployed environment run with the wrong (or no) credentials and URLs would report another environment's
+  // results under its name. The local stack runs with the defaults of `.env.dist` or the app's own.
+  if (!exists && env !== 'local') {
+    throw new Error(`Environment file not found: ${envFile}. Copy .env.dist to .env.${env} and fill it in.`)
+  }
+  process.env.E2E_ENV = env
+  if (base) applyEnvFile(path.resolve(dir, base), false)
+  if (exists) applyEnvFile(envFile, Boolean(base))
+  else if (!base) console.warn(`Environment file not found: ${envFile}. Copy .env.dist to .env.${env} and fill it in.`)
+  return env
+}
+
+/** @type {import('./env.mjs').E2eEnvOf} */
+export function e2eEnv() {
+  const env = process.env.E2E_ENV
+  if (!isE2eEnv(env)) {
+    throw env
+      ? invalid(env, 'E2E_ENV')
+      : new Error('E2E_ENV is not set: playwright.config.ts loads it (loadE2eEnv) before any test file.')
+  }
+  return env
+}
+
+/** @type {import('./env.mjs').E2eEnvLabel} */
+export const e2eEnvLabel = () => LABELS[e2eEnv()]
+
+/** @type {import('./env.mjs').IsLocalStack} */
+export const isLocalStack = () => e2eEnv() === 'local'

package/src/e2e/index.d.mts

@@ -1,3 +1,5 @@
+export type { E2eEnv, LoadE2eEnvOptions } from './env.mjs'
+export { E2E_ENVS, e2eEnv, e2eEnvLabel, isLocalStack, loadE2eEnv } from './env.mjs'
 export type {
   RouteWalkIgnore,
   RouteWalkOptions,
@@ -6,3 +8,4 @@ export type {
   RouteWalkTimings,
 } from './types.mjs'
 export { DEFAULT_TIMINGS, defineRouteWalk, defineRouteWalkBoot, readDeclaredRoutes } from './routeWalk.mjs'
+export { defineRouteWalkConfig } from './routeWalkConfig.mjs'

package/src/e2e/index.mjs

@@ -1 +1,3 @@
+export { E2E_ENVS, e2eEnv, e2eEnvLabel, isLocalStack, loadE2eEnv } from './env.mjs'
 export { DEFAULT_TIMINGS, defineRouteWalk, defineRouteWalkBoot, readDeclaredRoutes } from './routeWalk.mjs'
+export { defineRouteWalkConfig } from './routeWalkConfig.mjs'

package/src/e2e/routeWalk.mjs

@@ -503,7 +503,8 @@ export function defineRouteWalk({ test: base, expect }, options) {
   const skip = options.skip ?? {}
   const noRecord = options.noRecord ?? {}
   const resolve = options.resolve ?? {}
-  const ignore = options.ignore ?? []
+  // `E2E_ENV` as loadE2eEnv set it; the walk runs without it too (its own tests), as on a deployed environment.
+  const ignore = [...(options.ignore ?? []), ...(process.env.E2E_ENV === 'local' ? (options.localIgnore ?? []) : [])]
   const timings = withDefaults(options.timings)
 
   // One logged-in page per worker: logging in for each of hundreds of routes would double the run.

package/src/e2e/routeWalkConfig.d.mts

@@ -0,0 +1,16 @@
+import type { PlaywrightTestConfig } from 'playwright/test'
+
+export type DefineRouteWalkConfig = (
+  base: PlaywrightTestConfig,
+  overrides?: PlaywrightTestConfig
+) => PlaywrightTestConfig
+
+/**
+ * The route walk's Playwright config over the admin's `playwright.config.ts`: `tests/routes`, 4 workers, no
+ * retries, reports in `.report-routes` and `.results-routes` (the suite's `.report` and `.results` are left
+ * alone), the boot check before the routes, and, for an http `BASE_URL`, Chromium told to treat that origin as
+ * secure. `overrides` go over all of it but the projects, e.g. a `globalSetup` or `globalTimeout` of its own.
+ *
+ * `export default defineRouteWalkConfig(base)` in `playwright.routes.config.ts`, next to `playwright.config.ts`.
+ */
+export declare const defineRouteWalkConfig: DefineRouteWalkConfig

package/src/e2e/routeWalkConfig.mjs

@@ -0,0 +1,52 @@
+// @ts-check
+
+/**
+ * The Playwright config of the route walk (`tests/routes`, run by `bin/test --routes`), made from the admin's own
+ * `playwright.config.ts`: the same env, URL and browser, with what the walk needs over it.
+ */
+
+/** @type {import('./routeWalkConfig.mjs').DefineRouteWalkConfig} */
+export function defineRouteWalkConfig(base, overrides = {}) {
+  const { use: ownUse, ...own } = overrides
+  // A local stack serves the app over plain http, where the browser withholds what needs a secure context
+  // (`crypto.randomUUID` and the like). Deployed, the app is served over https.
+  const baseURL = ownUse?.baseURL ?? base.use?.baseURL ?? process.env.BASE_URL
+  const origin = baseURL ? new URL(baseURL).origin : ''
+  const use = { ...base.use, ...ownUse }
+  // A config that already passes the flag (admin-dam's names admin-cms's origin too) keeps its own: Chromium reads
+  // only one of them.
+  const hasOwnFlag = (use.launchOptions?.args ?? []).some((arg) =>
+    arg.startsWith('--unsafely-treat-insecure-origin-as-secure=')
+  )
+  const secureContextArgs =
+    origin.startsWith('http:') && !hasOwnFlag ? [`--unsafely-treat-insecure-origin-as-secure=${origin}`] : []
+
+  return {
+    ...base,
+    // Relative paths are resolved against the config file's folder.
+    testDir: 'tests/routes',
+    // The default run leaves the walk out (`testIgnore`, or projects with folders of their own).
+    testIgnore: [],
+    // A route is only opened, nothing is clicked or typed, so the routes are spread over workers.
+    workers: 4,
+    retries: 0,
+    // Folders of its own: a run empties its outputDir, and the walk would wipe the last suite run's traces.
+    reporter: [['list'], ['html', { outputFolder: '.report-routes', open: 'never' }]],
+    outputDir: '.results-routes',
+    ...own,
+    use: {
+      ...use,
+      // The headless shell Playwright uses by default ignores the flag; full Chromium in headless mode honours it.
+      ...(secureContextArgs.length ? { channel: 'chromium' } : {}),
+      launchOptions: {
+        ...use.launchOptions,
+        args: [...(use.launchOptions?.args ?? []), ...secureContextArgs],
+      },
+    },
+    projects: [
+      { name: 'boot', testMatch: /boot\.spec\.ts$/ },
+      // An app that does not boot stops the walk here instead of failing each route after its timeout.
+      { name: 'routes', testMatch: /routes\.spec\.ts$/, dependencies: ['boot'] },
+    ],
+  }
+}

package/src/e2e/types.d.mts

@@ -83,6 +83,11 @@ export interface RouteWalkOptions {
   redirects?: Record<string, RegExp>
   /** Problems that do not fail a route. */
   ignore?: RouteWalkIgnore[]
+  /**
+   * Problems that do not fail a route on the local Docker stack only (`E2E_ENV=local`): what the stack does not
+   * run, e.g. a mailer or an analytics service. On devel and staging they are failures.
+   */
+  localIgnore?: RouteWalkIgnore[]
   /** The rows of a listing, clicked to find a record when no link to one is found. Default: Vuetify's data table. */
   rowSelector?: string
   /**