@aerokit/test 0.0.0-stage → 15.4.1

package/LICENSE

@@ -0,0 +1,277 @@
+Eclipse Public License - v 2.0
+
+    THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE
+    PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION
+    OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.
+
+1. DEFINITIONS
+
+"Contribution" means:
+
+  a) in the case of the initial Contributor, the initial content
+     Distributed under this Agreement, and
+
+  b) in the case of each subsequent Contributor:
+     i) changes to the Program, and
+     ii) additions to the Program;
+  where such changes and/or additions to the Program originate from
+  and are Distributed by that particular Contributor. A Contribution
+  "originates" from a Contributor if it was added to the Program by
+  such Contributor itself or anyone acting on such Contributor's behalf.
+  Contributions do not include changes or additions to the Program that
+  are not Modified Works.
+
+"Contributor" means any person or entity that Distributes the Program.
+
+"Licensed Patents" mean patent claims licensable by a Contributor which
+are necessarily infringed by the use or sale of its Contribution alone
+or when combined with the Program.
+
+"Program" means the Contributions Distributed in accordance with this
+Agreement.
+
+"Recipient" means anyone who receives the Program under this Agreement
+or any Secondary License (as applicable), including Contributors.
+
+"Derivative Works" shall mean any work, whether in Source Code or other
+form, that is based on (or derived from) the Program and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship.
+
+"Modified Works" shall mean any work in Source Code or other form that
+results from an addition to, deletion from, or modification of the
+contents of the Program, including, for purposes of clarity any new file
+in Source Code form that contains any contents of the Program. Modified
+Works shall not include works that contain only declarations,
+interfaces, types, classes, structures, or files of the Program solely
+in each case in order to link to, bind by name, or subclass the Program
+or Modified Works thereof.
+
+"Distribute" means the acts of a) distributing or b) making available
+in any manner that enables the transfer of a copy.
+
+"Source Code" means the form of a Program preferred for making
+modifications, including but not limited to software source code,
+documentation source, and configuration files.
+
+"Secondary License" means either the GNU General Public License,
+Version 2.0, or any later versions of that license, including any
+exceptions or additional permissions as identified by the initial
+Contributor.
+
+2. GRANT OF RIGHTS
+
+  a) Subject to the terms of this Agreement, each Contributor hereby
+  grants Recipient a non-exclusive, worldwide, royalty-free copyright
+  license to reproduce, prepare Derivative Works of, publicly display,
+  publicly perform, Distribute and sublicense the Contribution of such
+  Contributor, if any, and such Derivative Works.
+
+  b) Subject to the terms of this Agreement, each Contributor hereby
+  grants Recipient a non-exclusive, worldwide, royalty-free patent
+  license under Licensed Patents to make, use, sell, offer to sell,
+  import and otherwise transfer the Contribution of such Contributor,
+  if any, in Source Code or other form. This patent license shall
+  apply to the combination of the Contribution and the Program if, at
+  the time the Contribution is added by the Contributor, such addition
+  of the Contribution causes such combination to be covered by the
+  Licensed Patents. The patent license shall not apply to any other
+  combinations which include the Contribution. No hardware per se is
+  licensed hereunder.
+
+  c) Recipient understands that although each Contributor grants the
+  licenses to its Contributions set forth herein, no assurances are
+  provided by any Contributor that the Program does not infringe the
+  patent or other intellectual property rights of any other entity.
+  Each Contributor disclaims any liability to Recipient for claims
+  brought by any other entity based on infringement of intellectual
+  property rights or otherwise. As a condition to exercising the
+  rights and licenses granted hereunder, each Recipient hereby
+  assumes sole responsibility to secure any other intellectual
+  property rights needed, if any. For example, if a third party
+  patent license is required to allow Recipient to Distribute the
+  Program, it is Recipient's responsibility to acquire that license
+  before distributing the Program.
+
+  d) Each Contributor represents that to its knowledge it has
+  sufficient copyright rights in its Contribution, if any, to grant
+  the copyright license set forth in this Agreement.
+
+  e) Notwithstanding the terms of any Secondary License, no
+  Contributor makes additional grants to any Recipient (other than
+  those set forth in this Agreement) as a result of such Recipient's
+  receipt of the Program under the terms of a Secondary License
+  (if permitted under the terms of Section 3).
+
+3. REQUIREMENTS
+
+3.1 If a Contributor Distributes the Program in any form, then:
+
+  a) the Program must also be made available as Source Code, in
+  accordance with section 3.2, and the Contributor must accompany
+  the Program with a statement that the Source Code for the Program
+  is available under this Agreement, and informs Recipients how to
+  obtain it in a reasonable manner on or through a medium customarily
+  used for software exchange; and
+
+  b) the Contributor may Distribute the Program under a license
+  different than this Agreement, provided that such license:
+     i) effectively disclaims on behalf of all other Contributors all
+     warranties and conditions, express and implied, including
+     warranties or conditions of title and non-infringement, and
+     implied warranties or conditions of merchantability and fitness
+     for a particular purpose;
+
+     ii) effectively excludes on behalf of all other Contributors all
+     liability for damages, including direct, indirect, special,
+     incidental and consequential damages, such as lost profits;
+
+     iii) does not attempt to limit or alter the recipients' rights
+     in the Source Code under section 3.2; and
+
+     iv) requires any subsequent distribution of the Program by any
+     party to be under a license that satisfies the requirements
+     of this section 3.
+
+3.2 When the Program is Distributed as Source Code:
+
+  a) it must be made available under this Agreement, or if the
+  Program (i) is combined with other material in a separate file or
+  files made available under a Secondary License, and (ii) the initial
+  Contributor attached to the Source Code the notice described in
+  Exhibit A of this Agreement, then the Program may be made available
+  under the terms of such Secondary Licenses, and
+
+  b) a copy of this Agreement must be included with each copy of
+  the Program.
+
+3.3 Contributors may not remove or alter any copyright, patent,
+trademark, attribution notices, disclaimers of warranty, or limitations
+of liability ("notices") contained within the Program from any copy of
+the Program which they Distribute, provided that Contributors may add
+their own appropriate notices.
+
+4. COMMERCIAL DISTRIBUTION
+
+Commercial distributors of software may accept certain responsibilities
+with respect to end users, business partners and the like. While this
+license is intended to facilitate the commercial use of the Program,
+the Contributor who includes the Program in a commercial product
+offering should do so in a manner which does not create potential
+liability for other Contributors. Therefore, if a Contributor includes
+the Program in a commercial product offering, such Contributor
+("Commercial Contributor") hereby agrees to defend and indemnify every
+other Contributor ("Indemnified Contributor") against any losses,
+damages and costs (collectively "Losses") arising from claims, lawsuits
+and other legal actions brought by a third party against the Indemnified
+Contributor to the extent caused by the acts or omissions of such
+Commercial Contributor in connection with its distribution of the Program
+in a commercial product offering. The obligations in this section do not
+apply to any claims or Losses relating to any actual or alleged
+intellectual property infringement. In order to qualify, an Indemnified
+Contributor must: a) promptly notify the Commercial Contributor in
+writing of such claim, and b) allow the Commercial Contributor to control,
+and cooperate with the Commercial Contributor in, the defense and any
+related settlement negotiations. The Indemnified Contributor may
+participate in any such claim at its own expense.
+
+For example, a Contributor might include the Program in a commercial
+product offering, Product X. That Contributor is then a Commercial
+Contributor. If that Commercial Contributor then makes performance
+claims, or offers warranties related to Product X, those performance
+claims and warranties are such Commercial Contributor's responsibility
+alone. Under this section, the Commercial Contributor would have to
+defend claims against the other Contributors related to those performance
+claims and warranties, and if a court requires any other Contributor to
+pay any damages as a result, the Commercial Contributor must pay
+those damages.
+
+5. NO WARRANTY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS"
+BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR
+IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF
+TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+PURPOSE. Each Recipient is solely responsible for determining the
+appropriateness of using and distributing the Program and assumes all
+risks associated with its exercise of rights under this Agreement,
+including but not limited to the risks and costs of program errors,
+compliance with applicable laws, damage to or loss of data, programs
+or equipment, and unavailability or interruption of operations.
+
+6. DISCLAIMER OF LIABILITY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS
+SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST
+PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE
+EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+7. GENERAL
+
+If any provision of this Agreement is invalid or unenforceable under
+applicable law, it shall not affect the validity or enforceability of
+the remainder of the terms of this Agreement, and without further
+action by the parties hereto, such provision shall be reformed to the
+minimum extent necessary to make such provision valid and enforceable.
+
+If Recipient institutes patent litigation against any entity
+(including a cross-claim or counterclaim in a lawsuit) alleging that the
+Program itself (excluding combinations of the Program with other software
+or hardware) infringes such Recipient's patent(s), then such Recipient's
+rights granted under Section 2(b) shall terminate as of the date such
+litigation is filed.
+
+All Recipient's rights under this Agreement shall terminate if it
+fails to comply with any of the material terms or conditions of this
+Agreement and does not cure such failure in a reasonable period of
+time after becoming aware of such noncompliance. If all Recipient's
+rights under this Agreement terminate, Recipient agrees to cease use
+and distribution of the Program as soon as reasonably practicable.
+However, Recipient's obligations under this Agreement and any licenses
+granted by Recipient relating to the Program shall continue and survive.
+
+Everyone is permitted to copy and distribute copies of this Agreement,
+but in order to avoid inconsistency the Agreement is copyrighted and
+may only be modified in the following manner. The Agreement Steward
+reserves the right to publish new versions (including revisions) of
+this Agreement from time to time. No one other than the Agreement
+Steward has the right to modify this Agreement. The Eclipse Foundation
+is the initial Agreement Steward. The Eclipse Foundation may assign the
+responsibility to serve as the Agreement Steward to a suitable separate
+entity. Each new version of the Agreement will be given a distinguishing
+version number. The Program (including Contributions) may always be
+Distributed subject to the version of the Agreement under which it was
+received. In addition, after a new version of the Agreement is published,
+Contributor may elect to Distribute the Program (including its
+Contributions) under the new version.
+
+Except as expressly stated in Sections 2(a) and 2(b) above, Recipient
+receives no rights or licenses to the intellectual property of any
+Contributor under this Agreement, whether expressly, by implication,
+estoppel or otherwise. All rights in the Program not expressly granted
+under this Agreement are reserved. Nothing in this Agreement is intended
+to be enforceable by any entity that is not a Contributor or Recipient.
+No third-party beneficiary rights are created under this Agreement.
+
+Exhibit A - Form of Secondary Licenses Notice
+
+"This Source Code may also be made available under the following
+Secondary Licenses when the conditions for such availability set forth
+in the Eclipse Public License, v. 2.0 are satisfied: {name license(s),
+version(s), and exceptions or additional permissions here}."
+
+  Simply including a copy of this Agreement, including this Exhibit A
+  is not sufficient to license the Source Code under Secondary Licenses.
+
+  If it is not possible or desirable to put the notice in a particular
+  file, then You may include the notice in a location (such as a LICENSE
+  file in a relevant directory) where a recipient would be likely to
+  look for such a notice.
+
+  You may add additional accurate notices of copyright ownership.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @aerokit/test
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Publishing note:** every release publishes this folder as `@aerokit/test`, versioned with the
+> platform. Consumers depend on `@aerokit/test` and import `@aerokit/test` /
+> `@aerokit/test/fixtures`. A harness written against the earlier `@aerokit/sdk/test` subpath keeps
+> resolving while `@aerokit/sdk` still ships it, but `@aerokit/sdk` is being deprecated: switch the
+> import and the dependency to `@aerokit/test`.
+
+Generic [Playwright](https://playwright.dev) runner that executes an intent module's generated
+`<name>.test` manifest against a running Eclipse Dirigible instance. The manifest (emitted by the
+`AppTestIntentGenerator` in `engine-intent`, alongside `.edm`/`.model`/`.bpmn`/...) says WHAT the
+app promises — entities, layouts, fields, seeds, languages; this package knows HOW to verify a
+promise against the generated Harmonia UI and the reused REST controllers. So one runner, versioned
+alongside the templates whose markup it drives, checks every generated app the same way.
+
+This is the app-integration-test surface (drives a browser + the REST layer from outside the
+instance). It is distinct from `@aerokit/sdk/junit`, the in-instance server-side unit-test facade.
+
+## Use from a module
+
+A module keeps a tiny `test/` harness at its **repo root** (outside the published project folder, so
+it never enters the registry or the npm package):
+
+```js
+// test/app.spec.js
+import { fileURLToPath } from 'node:url';
+import { runTest } from '@aerokit/test';
+
+runTest(fileURLToPath(new URL('../<project>/<name>.test', import.meta.url)));
+```
+
+```json
+// test/package.json
+{
+  "type": "module",
+  "scripts": { "test": "playwright test" },
+  "devDependencies": { "@aerokit/test": "*", "@playwright/test": "^1.45" }
+}
+```
+
+```
+BASE_URL=http://localhost:8080 npm test        # defaults: admin/admin, installed Chrome
+APPTEST_SHELL=1 npm test                       # also assert the shared-shell menu item
+APPTEST_A11Y=strict npm test                   # fail on serious/critical accessibility violations
+```
+
+Env: `BASE_URL` (default `http://localhost:8080`), `APPTEST_USERNAME`/`APPTEST_PASSWORD`
+(default `admin`/`admin`), `APPTEST_SHELL` (opt-in shared-shell flow), `APPTEST_A11Y` (`report`
+default, `strict`, `off` - the accessibility flow).
+
+## Flows per entity
+
+- **list** — the shell breadcrumb naming the list by its plural label, the declared columns, and
+  (when `expectSeedData`) a row. An entity whose manifest carries `list` renders exactly those
+  columns, in order, and a field left off it must have no header at all; without `list` the columns
+  are the fields whose `major` is not `false`.
+- **crud** — UI create → filter → row appears; edit via the row menu → save (a `document` saves in
+  place, so the walk leaves through Cancel); delete via the row menu → confirm → gone. A walk
+  that fails halfway still removes its test row over REST. An entity without a `route` (a composition
+  child with no page of its own) has no list, crud, multilingual or shell flow.
+- **rest** — the same CRUD over the generated Java controllers via `APIRequestContext` (isolates
+  backend vs UI failures), asserting the manifest's field names bind and delete yields 404 — or,
+  for an entity a `whenDeleted: refuse` process guards, that the refused record is still served.
+- **multilingual** — switch the shared language key, reload, a seeded row shows its translated name.
+  The assertion waits for the list's own data GET and allows 15 s; a failure names the
+  `Accept-Language` that GET sent, whether its body carried the expected word, and the table's first
+  row, so a slow render reads differently from a missing translation.
+- **my** — the personal (my) surface WIRE contract, when the manifest marks an entity `personal`:
+  create through the scoped `<Entity>MyController` (owner FK forced server-side), every `sensitive`
+  field null on the personal wire, the own row in the personal list, foreign rows 404 (when the
+  owner relation is optional), own-row delete. Skips with a pointer when the test user has no
+  identity mapping (seed the dev identity row). Personal *UI* parity (resolved labels, chat,
+  calendar on the Personal shell) is deliberately not asserted yet — it tracks the personal-template
+  parity fixes.
+- **shell** (opt-in) — the shared application shell's nav item opens the module SPA in its iframe.
+- **a11y** — axe-core scans the list page and the create form against WCAG 2.1 A/AA and attaches
+  each page's result (`axe-<Entity>-<page>.json`) to the test report. `APPTEST_A11Y=report`
+  (default) only reports - a module's first release; `strict` also fails on a `serious` or
+  `critical` violation; `off` skips it. Needs `@axe-core/playwright` in the harness
+  `devDependencies` (the flow skips itself without it). Contrast against Harmonia's own
+  `--primary` is not counted in strict mode: the default palette misses 4.5:1 there, which the
+  component library fixes; every other contrast failure is.
+
+Test records carry an `APPTEST-` prefix and are removed in teardown; seed data is never mutated.
+A field the app owns rather than the user — a `number:` series, a calculated or `readOnly:` value —
+is never written or flipped by a flow (the manifest marks it `readOnly`). A relation the form renders
+read-only — a `calculatedActionOnUpdate`, a platform-owned FK — carries the same flag and is never
+picked in the UI. A relation fixed after create (`fixedAfterCreate: true`) carries `readOnlyOnEdit`: it is
+picked on create and never changed by an edit, which the generated app answers with a 409. A field declaring a
+`pattern:` gets a value of that shape rather than the marker string. An optional `pattern:` field
+whose shape none of the sample candidates has (an IBAN, say) is left empty; a required one keeps the
+marker, so the controller's 400 names the field. Relations an `agree` check names are picked so
+their targets agree; a composite `uniqueKeys` entry is given a relation combination no live row
+carries, and the rest and crud flows skip with the key named when every combination tried is taken.
+A relation carrying `pickable` is sampled only from the rows its rule admits — the chooser offers no
+other, so a record built from one would never save — and one carrying `forbiddenTarget` only from
+rows the record's own `forbidWhen` does not refuse, which is what the REST flow needs, having no
+picker to read. When no row is left, a required relation fails naming the rule's own message rather
+than "no rows".
+
+## Custom UI hooks
+
+`runTest(manifest, { extend })` (`runAppTest` remains a deprecated alias):
+
+- `widgets: { '<widget>': async (page, field, value) => ... }` — custom widget fillers.
+- `entities: { <Entity>: { skip: ['delete'], beforeCreate, afterCreate } }` — per-entity hooks.
+
+Hand-written specs live in `test/custom/*.spec.js` and import `@aerokit/test/fixtures`
+(pre-logged-in `test`, an `api` client, `expect`) so login/baseURL/cleanup come free.

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@aerokit/test",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "15.4.1",
+  "description": "Generic Playwright runner that executes an intent module's generated <name>.test manifest against a running Eclipse Dirigible instance",
+  "license": "EPL-2.0",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./fixtures": "./src/fixtures.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "dirigible",
+    "playwright",
+    "integration-test",
+    "intent",
+    "low-code"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-dirigible/dirigible.git",
+    "directory": "npm/test"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.45",
+    "@axe-core/playwright": ">=4.10"
+  },
+  "peerDependenciesMeta": {
+    "@axe-core/playwright": {
+      "optional": true
+    }
+  }
+}

package/src/api.js

@@ -0,0 +1,41 @@
+// Thin REST client over the generated Java controllers described by the manifest.
+export function makeApi(request, manifest) {
+  const url = (entity, suffix = '') => manifest.restBase + entity.api + suffix;
+
+  async function asJson(response) {
+    if (!response.ok()) {
+      // APIResponse has no request(); report url + status + body
+      throw new Error(`${response.url()} -> ${response.status()} ${await response.text()}`);
+    }
+    const text = await response.text();
+    return text ? JSON.parse(text) : undefined;
+  }
+
+  return {
+    list: (entity, limit = 20) => request.get(url(entity, `?$limit=${limit}`)).then(asJson),
+    // absolute controller path (a cross-model relation target owned by another module)
+    listPath: (path, limit = 20) => request.get(`${path}?$limit=${limit}`).then(asJson),
+    getPath: (path) => request.get(path).then(asJson),
+    count: (entity) => request.get(url(entity, '/count')).then(asJson).then((body) => (typeof body === 'number' ? body : body.count)),
+    get: (entity, id) => request.get(url(entity, '/' + id)).then(asJson),
+    getResponse: (entity, id) => request.get(url(entity, '/' + id)),
+    // the generated controller's filtered read (what the list's filters POST): [{ propertyName, operator, value }]
+    search: (entity, conditions) => request.post(url(entity, '/search'), { data: { conditions } }).then(asJson),
+    create: (entity, data) => request.post(url(entity), { data }).then(asJson),
+    update: (entity, id, data) => request.put(url(entity, '/' + id), { data }).then(asJson),
+    // Answers whether the row is gone. A record whose process declares `whenDeleted: refuse` is
+    // REFUSED with 409 while that instance runs (dirigible #7074) - the guard doing its job, not a
+    // failure, so the caller is told rather than thrown at and its cleanup completes either way.
+    // Every other failing status still throws.
+    remove: async (entity, id) => {
+      const response = await request.delete(url(entity, '/' + id));
+      if (response.status() === 409 && entity.deleteGuardedByProcess?.length) {
+        return false;
+      }
+      if (!response.ok()) {
+        throw new Error(`DELETE ${response.url()} -> ${response.status()} ${await response.text()}`);
+      }
+      return true;
+    },
+  };
+}

package/src/env.js

@@ -0,0 +1,3 @@
+export const BASE_URL = process.env.BASE_URL ?? 'http://localhost:8080';
+export const USERNAME = process.env.APPTEST_USERNAME ?? 'admin';
+export const PASSWORD = process.env.APPTEST_PASSWORD ?? 'admin';

package/src/fixtures.js

@@ -0,0 +1,29 @@
+import { expect, test as base } from '@playwright/test';
+import { BASE_URL } from './env.js';
+import { login } from './session.js';
+
+// Pre-authenticated Playwright test:
+// - authState: worker-scoped form login, one session per worker
+// - storageState: every page starts logged in
+// - api: an APIRequestContext carrying the same session, for REST-level checks
+export const test = base.extend({
+  authState: [
+    async ({ browser }, use) => {
+      await use(await login(browser));
+    },
+    { scope: 'worker' },
+  ],
+  storageState: async ({ authState }, use) => {
+    await use(authState);
+  },
+  api: async ({ playwright, authState }, use) => {
+    const request = await playwright.request.newContext({
+      baseURL: BASE_URL,
+      storageState: authState,
+    });
+    await use(request);
+    await request.dispose();
+  },
+});
+
+export { expect };

package/src/flows/a11y.js

@@ -0,0 +1,86 @@
+import { expect, test } from '../fixtures.js';
+import { CALENDAR_OR_SLOTS, listCrumb } from './list.js';
+
+// The WCAG 2.1 level AA conformance rules, and the level A ones it includes (dirigible #7645).
+const WCAG_21_AA = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'];
+const ENFORCED_IMPACTS = new Set(['serious', 'critical']);
+
+// report (default): attach every page's axe result to the test report and pass - the first
+// release of a module. strict: also fail on a serious or critical violation. off: no scan.
+const MODE = process.env.APPTEST_A11Y ?? 'report';
+
+// Harmonia's default palette fails contrast against its own --primary (white on it, and it as link
+// text in dark mode); that is fixed in the component library, so strict mode does not fail an app
+// for it. Any other contrast failure still counts.
+const PRIMARY_COLOR = () => {
+  const probe = document.createElement('div');
+  probe.style.color = 'var(--primary)';
+  document.body.appendChild(probe);
+  const color = getComputedStyle(probe).color;
+  probe.remove();
+  const context = document.createElement('canvas').getContext('2d');
+  context.fillStyle = color;
+  context.fillRect(0, 0, 1, 1);
+  const [r, g, b] = context.getImageData(0, 0, 1, 1).data;
+  return '#' + [r, g, b].map((v) => v.toString(16).padStart(2, '0')).join('');
+};
+
+function sameColor(measured, expected) {
+  if (typeof measured !== 'string' || measured.length !== 7 || !expected) return false;
+  for (let channel = 1; channel < 7; channel += 2) {
+    const a = parseInt(measured.slice(channel, channel + 2), 16);
+    const b = parseInt(expected.slice(channel, channel + 2), 16);
+    if (Math.abs(a - b) > 2) return false;
+  }
+  return true;
+}
+
+function onPrimary(node, primary) {
+  return (node.any ?? []).some((check) => sameColor(check.data?.fgColor, primary) || sameColor(check.data?.bgColor, primary));
+}
+
+async function axeBuilder() {
+  try {
+    return (await import('@axe-core/playwright')).default;
+  } catch {
+    return null;
+  }
+}
+
+// The list page and the create form of every entity with a page of its own, scanned by axe-core.
+export function a11yFlow(manifest, entity) {
+  if (MODE === 'off' || !entity.route) return;
+  test(`${entity.name}: list and form pages pass axe-core (WCAG 2.1 AA)`, async ({ page }, testInfo) => {
+    const AxeBuilder = await axeBuilder();
+    test.skip(!AxeBuilder, 'add @axe-core/playwright to the harness devDependencies to run the accessibility flow');
+
+    const calendar = entity.layout === 'calendar' || entity.layout === 'slots';
+    const pages = [['list', entity.route, () => (calendar ? page.locator(CALENDAR_OR_SLOTS).first() : listCrumb(page, entity))]];
+    if (!calendar && !entity.hierarchy) {
+      pages.push(['form', entity.route + '/create', () => page.locator('input, select, textarea').filter({ visible: true }).first()]);
+    }
+
+    const findings = [];
+    for (const [name, route, ready] of pages) {
+      await page.goto(manifest.standaloneShell + route);
+      await expect(ready()).toBeVisible();
+      const results = await new AxeBuilder({ page }).withTags(WCAG_21_AA).analyze();
+      await testInfo.attach(`axe-${entity.name}-${name}.json`, {
+        body: JSON.stringify(results, null, 2),
+        contentType: 'application/json',
+      });
+      const primary = await page.evaluate(PRIMARY_COLOR);
+      for (const violation of results.violations) {
+        if (!ENFORCED_IMPACTS.has(violation.impact)) continue;
+        const nodes = violation.nodes.filter((node) => !(violation.id === 'color-contrast' && onPrimary(node, primary)));
+        if (nodes.length) {
+          const targets = nodes.slice(0, 5).map((node) => node.target.join(' ')).join(', ');
+          findings.push(`${name}: [${violation.impact}] ${violation.id} - ${violation.help} (${nodes.length} elements: ${targets})`);
+        }
+      }
+    }
+    if (MODE === 'strict') {
+      expect(findings, 'serious or critical WCAG 2.1 AA violations:\n' + findings.join('\n')).toEqual([]);
+    }
+  });
+}