@aerokit/test 0.0.0-stage → 15.0.0

package/src/flows/crud.js

@@ -0,0 +1,121 @@
+import { expect, test } from '../fixtures.js';
+import { makeApi } from '../api.js';
+import { fillField, fillForm, resolveRelationSamples } from '../form.js';
+import { freshUniqueKeys, freshUniques, handleField, sampleRecord } from '../sample-values.js';
+
+// Server-side row lookup via the toolbar "Search <Entity>..." box - present on every list
+// layout (manage-list, master-detail, document) and searching the string columns server-side.
+// The per-column filter row is NOT used: its first input can belong to an FK or date column
+// (hidden or non-text), which made a blind fill hang.
+async function filterBy(page, value) {
+  await page.getByPlaceholder(/^Search /).first().fill(value);
+}
+
+function dataRow(page, text) {
+  return page.locator('tbody tr', { hasText: text });
+}
+
+// Edit and Delete of a row live in its "Row actions" menu - the one place every list layout
+// (manage, document, master-detail) offers both; the manage list's record sheet puts Delete behind
+// an overflow menu and its primary button may be a process task rather than Edit (#7491).
+async function rowAction(page, text, action) {
+  await dataRow(page, text).getByRole('button', { name: 'Row actions' }).click();
+  await page.getByRole('menuitem', { name: action, exact: true }).click();
+}
+
+// A walk that fails halfway leaves its APPTEST- row behind, and the next run's REST flow then hits
+// a unique: column with it (409). Remove whatever the walk created - the edited name starts with
+// the created one - unless the UI delete already did.
+async function removeLeftovers(client, manifest, entity, handle, created) {
+  const idProperty = manifest.idProperty ?? 'Id';
+  const rows = await client.search(entity, [{ propertyName: handle.name, operator: 'LIKE', value: created + '%' }]);
+  for (const row of rows ?? []) await client.remove(entity, row[idProperty]);
+}
+
+export function crudFlow(manifest, entity, opts = {}) {
+  const cfg = opts.extend?.entities?.[entity.name] ?? {};
+  const skip = new Set(cfg.skip ?? []);
+  if (skip.has('crud')) return;
+  // no power page to walk: a composition child is reached through its parent (dirigible #7545)
+  if (!entity.route) return;
+  // A hierarchy entity lists as a tree, and a calendar/slots entity replaces the table page
+  // entirely - no filter row / data rows to drive the walk below; create/read/update/delete
+  // stays covered by the REST flow. Same for an entity without a string handle field (nothing
+  // searchable identifies the created row in the table).
+  if (entity.hierarchy || entity.layout === 'calendar' || entity.layout === 'slots') return;
+  if (!handleField(entity)) return;
+
+  test(`${entity.name}: create, edit and delete through the UI`, async ({ page, api }) => {
+    const record = await freshUniques(makeApi(api, manifest), entity, sampleRecord(entity));
+    const handle = handleField(entity);
+    const relationSamples = await resolveRelationSamples(api, manifest, entity);
+    const taken = await freshUniqueKeys(makeApi(api, manifest), entity, record, relationSamples);
+    test.skip(!!taken, `every ${entity.name} combination of the unique key [${taken}] tried already has a row`);
+
+    const created = record[handle.name];
+    const listRoute = entity.route.replace(/[#/]/g, '\\$&');
+    try {
+      // create
+      await page.goto(manifest.standaloneShell + entity.route);
+      // exact: the empty state adds a second "New <Entity>" button that a substring match also hits
+      await page.getByRole('button', { name: 'New', exact: true }).click();
+      await expect(page).toHaveURL(/\/create$/);
+      await cfg.beforeCreate?.(page, record);
+      await fillForm(page, manifest, entity, record, relationSamples, opts);
+      await page.getByRole('button', { name: 'Create', exact: true }).click();
+      // A create lands on the NEW record's page when there is more to do there - a document's
+      // line items, a manage record's detail collections - and on the list otherwise. Saving an
+      // edit returns to the list, except on a document, whose Save stays on it (#7359).
+      const recordPage = entity.layout === 'document' ? '/[^/]+/edit' : '(/[^/]+/edit)?';
+      await expect(page).toHaveURL(new RegExp(listRoute + recordPage + '$'));
+      if (page.url().endsWith('/edit')) await page.goto(manifest.standaloneShell + entity.route);
+      await filterBy(page, created);
+      await expect(dataRow(page, created)).toHaveCount(1);
+      await cfg.afterCreate?.(page, record);
+
+      // edit
+      if (!skip.has('edit')) {
+        const updated = created + '-UPD';
+        await rowAction(page, created, 'Edit');
+        await expect(page).toHaveURL(/\/edit$/);
+        // the record loads async after the form renders - filling before the fetch completes
+        // gets overwritten by the load and Save persists the OLD value
+        await expect(page.locator('#f_' + handle.name)).toHaveValue(created);
+        await fillField(page, handle, updated, opts);
+        if (entity.layout === 'document') {
+          // A document Save STAYS on the document and re-reads it (#7359): wait for the update to
+          // land, then leave for the list the way a user does (dirigible #7545).
+          const save = page.getByRole('button', { name: 'Save', exact: true });
+          const saved = page.waitForResponse((response) => response.request().method() === 'PUT' && response.ok());
+          await save.click();
+          await saved;
+          // Save is disabled again once the re-read header is the new pristine state - leaving before
+          // that would meet the unsaved-changes guard
+          await expect(save).toBeDisabled();
+          // A clean document's dismiss is Cancel (dirigible #7770).
+          await page.getByRole('button', { name: 'Cancel', exact: true }).click();
+        } else {
+          await page.getByRole('button', { name: 'Save', exact: true }).click();
+        }
+        await expect(page).toHaveURL(new RegExp(listRoute + '$'));
+        await filterBy(page, updated);
+        await expect(dataRow(page, updated)).toHaveCount(1);
+        record[handle.name] = updated;
+      }
+
+      // delete (row menu, then the confirm dialog). An entity whose process declares
+      // `whenDeleted: refuse` answers the delete with an error toast while its instance runs - the
+      // create above started it - so the walk stops here and the REST flow asserts that refusal.
+      if (!skip.has('delete') && !entity.deleteGuardedByProcess?.length) {
+        await rowAction(page, record[handle.name], 'Delete');
+        const dialog = page.locator('[x-h-dialog-overlay][data-open]');
+        await dialog.getByRole('button', { name: 'Delete', exact: true }).click();
+        await expect(dialog).toHaveCount(0);
+        await filterBy(page, record[handle.name]);
+        await expect(dataRow(page, record[handle.name])).toHaveCount(0);
+      }
+    } finally {
+      await removeLeftovers(makeApi(api, manifest), manifest, entity, handle, created);
+    }
+  });
+}

package/src/flows/list.js

@@ -0,0 +1,82 @@
+import { expect, test } from '../fixtures.js';
+import { labelOf } from '../sample-values.js';
+
+// The calendar / slot-picker view root. The slots page renders `x-h-slot-picker.responsive`, and an
+// attribute selector matches an attribute NAME exactly, so the modifier form is listed with its dot
+// escaped (dirigible #7545).
+export const CALENDAR_OR_SLOTS = '[x-h-calendar], [x-h-slot-picker], [x-h-slot-picker\\.responsive]';
+
+// The shell breadcrumb's current crumb - the one page element every list layout shares that names
+// the entity (the sidebar label, which the manifest's labelPlural mirrors).
+export function listCrumb(page, entity) {
+  return page.locator('[x-h-breadcrumb-page]', { hasText: entity.labelPlural }).first();
+}
+
+// The list page renders under the shell breadcrumb naming it by its plural label (the #7491
+// manage list carries no title of its own), then one of three bodies -
+// a tree (hierarchy entities render role=treeitem nodes, no table), the table with one
+// column header per major field, or (when the entity has no rows yet) the empty state.
+// When seed data is expected, rows/nodes must actually be there.
+export function listFlow(manifest, entity) {
+  // no power page: a composition child is reached through its parent (dirigible #7545)
+  if (!entity.route) return;
+  test(`${entity.name}: list page renders the declared columns`, async ({ page }) => {
+    await page.goto(manifest.standaloneShell + entity.route);
+    await expect(listCrumb(page, entity)).toBeVisible();
+    if (entity.hierarchy) {
+      if (entity.expectSeedData) {
+        await expect(page.getByRole('treeitem').first()).toBeVisible();
+      }
+      return;
+    }
+    if (entity.layout === 'calendar' || entity.layout === 'slots') {
+      // the view family renders a calendar / slot picker instead of the table
+      await expect(page.locator(CALENDAR_OR_SLOTS).first()).toBeVisible();
+      return;
+    }
+    // filter({ visible: true }): the empty-state markup stays in the DOM (x-show) above the
+    // table, so an unfiltered union's .first() would pick the hidden element and always fail
+    const firstHeader = page.getByRole('columnheader').filter({ visible: true }).first();
+    const emptyState = page.getByText('Get started by creating the first record').filter({ visible: true }).first();
+    await expect(firstHeader.or(emptyState).first()).toBeVisible();
+    if (entity.expectSeedData || (await firstHeader.isVisible())) {
+      for (const label of declaredColumns(entity)) {
+        await expect(page.getByRole('columnheader').filter({ hasText: label }).first()).toBeVisible();
+      }
+      for (const label of hiddenColumns(entity)) {
+        await expect(page.getByRole('columnheader').filter({ hasText: label })).toHaveCount(0);
+      }
+      await expect(page.locator('tbody tr:visible').first()).toBeVisible();
+    }
+  });
+}
+
+// The headers the list is expected to render, in order (dirigible #7664). `list:` curates the list
+// INDEPENDENTLY of each field's own `major`, so an entity that declares it renders exactly those
+// columns and the `major` rule says nothing about it - which is why asserting the rule against a
+// curated entity failed on the first instance that held a row, and passed on every empty one,
+// where the assertion never runs at all.
+function declaredColumns(entity) {
+  if (entity.list?.length) return entity.list.map((name) => columnLabel(entity, name));
+  return (entity.fields ?? []).filter((f) => f.major !== false && !f.primaryKey).map(labelOf);
+}
+
+// ...and the ones it must NOT render. A curated list is the whole statement, so a field left off it
+// is absent from the table however its own `major` reads - the half that catches a `list:` the page
+// ignored.
+function hiddenColumns(entity) {
+  if (!entity.list?.length) return [];
+  const listed = new Set(entity.list);
+  return (entity.fields ?? [])
+    .filter((f) => !f.primaryKey && !listed.has(f.name))
+    .map(labelOf);
+}
+
+// A `list:` entry names a property - a field, or a to-one relation - and the header carries that
+// property's own label, which is what the manifest's `label` on the field already is.
+function columnLabel(entity, name) {
+  const field = (entity.fields ?? []).find((f) => f.name === name);
+  if (field) return labelOf(field);
+  const relation = (entity.relations ?? []).find((r) => r.name === name);
+  return relation?.label ?? name;
+}

package/src/flows/multilingual.js

@@ -0,0 +1,68 @@
+import { expect, test } from '../fixtures.js';
+import { listCrumb } from './list.js';
+
+const LANGUAGE_KEY = 'codbex.harmonia.language';
+// A reload in another language is three round trips on a cold instance - the page, the list's
+// data GET and the translation overlay behind it - so the 5 s default flaked on slower runners.
+const OVERLAY_TIMEOUT = 15_000;
+
+// The read-time translation overlay: switch the shared language key (what the Region &
+// Language setting writes), reload, and a known seed row shows its translated name.
+// Needs a concrete sample in the manifest: { language, base, translated }.
+export function multilingualFlow(manifest, entity) {
+  const sample = entity.multilingualSample;
+  if (!entity.multilingual || !sample || !entity.route) return;
+
+  test(`${entity.name}: ${sample.language} translation overlays on read`, async ({ page }) => {
+    await page.goto(manifest.standaloneShell + entity.route);
+    await expect(listCrumb(page, entity)).toBeVisible();
+    const translatedRead = await reloadIn(page, manifest, entity, sample.language);
+    await expectRowShowing(page, sample.translated, translatedRead);
+    const baseRead = await reloadIn(page, manifest, entity, 'en');
+    await expectRowShowing(page, sample.base, baseRead);
+  });
+}
+
+// Set the language key and reload, waiting for the list's own data GET (the paged getAll on the
+// entity's controller) so the assertion starts once the rows are on their way, and answering what
+// that read asked for and got back - which is what tells a slow render from a missing translation.
+// The wait is registered only once the reload has committed: registered before it, it also matched
+// a list GET still in flight from the document the reload replaced, whose body is gone (#7584). The
+// new document issues its own GET only after its scripts have loaded, so it cannot slip past.
+async function reloadIn(page, manifest, entity, language) {
+  await page.evaluate(([key, lang]) => localStorage.setItem(key, lang), [LANGUAGE_KEY, language]);
+  const controllerPath = manifest.restBase + entity.api;
+  await page.reload({ waitUntil: 'commit' });
+  const response = await page.waitForResponse(
+    (candidate) => candidate.request().method() === 'GET' && new URL(candidate.url()).pathname === controllerPath,
+    { timeout: OVERLAY_TIMEOUT },
+  );
+  return {
+    language,
+    acceptLanguage: await response.request().headerValue('accept-language'),
+    status: response.status(),
+    // Only the diagnostic reads the body, so a body the browser no longer holds must not fail the flow.
+    body: await response.text().catch(() => null),
+  };
+}
+
+async function expectRowShowing(page, text, read) {
+  const rows = page.locator('tbody tr');
+  try {
+    await expect(rows.filter({ hasText: text }).first()).toBeVisible({ timeout: OVERLAY_TIMEOUT });
+  } catch (error) {
+    const firstRow = (await rows.allInnerTexts())[0]?.replace(/\s+/g, ' ').trim();
+    throw new Error(
+      `no list row shows '${text}' after reloading in '${read.language}': the list GET sent Accept-Language ` +
+        `${read.acceptLanguage ?? '(none)'} and answered ${read.status}, ` +
+        `${describeBody(read.body, text)}; the table's first row reads ` +
+        `${firstRow ? `'${firstRow}'` : '(no rows)'}`,
+      { cause: error },
+    );
+  }
+}
+
+function describeBody(body, text) {
+  if (body === null) return 'its body unavailable';
+  return `${body.includes(text) ? 'WITH' : 'WITHOUT'} '${text}' in its body`;
+}

package/src/flows/my.js

@@ -0,0 +1,156 @@
+import { makeApi } from '../api.js';
+import { expect, test } from '../fixtures.js';
+import { resolveRelationSamples } from '../form.js';
+import { freshUniques, sampleRecord } from '../sample-values.js';
+import { CALENDAR_OR_SLOTS } from './list.js';
+
+// Wave 2 (UI parity): the personal PAGE renders what the wire serves. Driven by the same
+// own-row lifecycle as the wire test (created through the scoped controller, removed in the
+// finally); skips without an identity mapping, exactly like the wire flow.
+// - layout 'list': every relation column of the own row shows its referenced LABEL - the
+//   raw-FK-id regression class the personal templates fixed;
+// - layout 'calendar'/'slots': the personal route renders the calendar / slot picker, never a
+//   plain form+list downgrade;
+// - layout 'document-chat': the composer accepts a message and the bubble renders (the my
+//   document chat parity class). A plain 'document' asserts the page serves.
+function myUiTest(manifest, entity, mine, buildContext, idProperty) {
+  test(`${entity.name}: the My page renders the own record with resolved labels (UI parity)`, async ({ api, page }) => {
+    const { payload, samples } = await buildContext(api);
+    const createdResponse = await api.post(manifest.restBase + mine.api, { data: payload });
+    test.skip(
+      !createdResponse.ok(),
+      `personal create returned ${createdResponse.status()} - the test user has no identity mapping; ` +
+        `seed the dev identity row (an owner-target record whose identity field equals the login user)`
+    );
+    const created = JSON.parse(await createdResponse.text());
+    const id = created?.[idProperty];
+    const client = makeApi(api, manifest);
+    try {
+      const layout = entity.personal.layout ?? 'list';
+      if (layout === 'calendar' || layout === 'slots') {
+        await page.goto(manifest.standaloneShell + entity.personal.route);
+        await expect(page.locator(CALENDAR_OR_SLOTS).first()).toBeVisible();
+        return;
+      }
+      if (layout === 'document-chat' || layout === 'document') {
+        await page.goto(manifest.standaloneShell + entity.personal.route + '/' + id + '/edit');
+        if (layout === 'document-chat') {
+          const message = `UI parity probe ${id}`;
+          const composer = page.getByRole('textbox', { name: /write a message/i }).first();
+          await composer.fill(message);
+          await page.getByRole('button', { name: /send/i }).first().click();
+          await expect(page.getByText(message).first(), 'the sent message must render as a bubble').toBeVisible();
+        } else {
+          // visible only: the document carries a second toolbar title (its items table's), which can
+          // be the first in DOM order while hidden (dirigible #7545)
+          await expect(page.locator('[x-h-toolbar-title]').filter({ visible: true }).first()).toBeVisible();
+        }
+        return;
+      }
+      // list: the own rows are the only rows - every asserted relation column of the created
+      // row must surface its referenced label somewhere in the table body
+      await page.goto(manifest.standaloneShell + entity.personal.route);
+      await expect(page.locator('tbody tr:visible').first()).toBeVisible();
+      const fkColumns = new Set(entity.personal.fkColumns ?? []);
+      for (const sample of samples) {
+        if (!fkColumns.has(sample.relation.name) || sample.label == null) continue;
+        await expect(
+          page.locator('tbody').getByText(String(sample.label)).first(),
+          `${sample.relation.name} must render its referenced label ("${sample.label}"), not the raw id ${sample.id}`
+        ).toBeVisible();
+      }
+    } finally {
+      await client.remove(mine, id);
+    }
+  });
+}
+
+// The personal (my) surface WIRE contract, driven when the manifest marks an entity `personal`:
+// the scoped <Entity>MyController filters reads to the identity-mapped user, forces the owner FK
+// server-side on create (whatever the client sends is ignored), strips every `sensitive` field
+// from its responses (the allow-list is the security boundary - UI hiding alone is cosmetic),
+// serves foreign rows as 404, and deletes only own rows.
+//
+// Prerequisite: the DEV IDENTITY mapping - a row of the owner relation's target whose identity
+// field equals the test user (e.g. an Employee with email 'admin'). Without it the personal
+// surface is EMPTY by design (never an error), so the flow SKIPS with a pointer instead of
+// failing. Wave 2 (myUiTest below) walks the personal PAGE over the same own-row lifecycle:
+// resolved relation labels on the list, calendar/slots rendering, the chat composer round-trip.
+export function myFlow(manifest, entity, opts = {}) {
+  const cfg = opts.extend?.entities?.[entity.name] ?? {};
+  if (!entity.personal || new Set(cfg.skip ?? []).has('my')) return;
+  const idProperty = manifest.idProperty ?? 'Id';
+  // the same entity through the scoped controller
+  const mine = { ...entity, api: entity.personal.api };
+
+  async function buildContext(api) {
+    const payload = sampleRecord(entity);
+    const samples = await resolveRelationSamples(api, manifest, entity);
+    for (const sample of samples) {
+      payload[sample.relation.name] = sample.id;
+    }
+    // the owner FK is server-forced on the personal surface; sending a value must be pointless
+    delete payload[entity.personal.owner];
+    await freshUniques(makeApi(api, manifest), entity, payload);
+    return { payload, samples };
+  }
+
+  async function buildPayload(api) {
+    return (await buildContext(api)).payload;
+  }
+
+  test(`${entity.name}: personal (my) surface scopes rows, forces the owner and strips sensitive fields`, async ({ api }) => {
+    const client = makeApi(api, manifest);
+
+    const createdResponse = await api.post(manifest.restBase + mine.api, { data: await buildPayload(api) });
+    test.skip(
+      !createdResponse.ok(),
+      `personal create returned ${createdResponse.status()} - the test user has no identity mapping; ` +
+        `seed the dev identity row (an owner-target record whose identity field equals the login user)`
+    );
+    const created = JSON.parse(await createdResponse.text());
+    const id = created?.[idProperty];
+    expect(id, 'personal create carries the generated id').toBeTruthy();
+    let foreignId;
+    let deleted;
+    try {
+      const own = await client.get(mine, id);
+      expect(own[entity.personal.owner], 'the owner FK is forced server-side on a personal create').toBeTruthy();
+      for (const field of entity.personal.sensitive ?? []) {
+        expect(own[field], `sensitive field ${field} must never reach the personal wire`).toBeFalsy();
+      }
+      const rows = await client.list(mine, 1000);
+      expect(rows.some((row) => row[idProperty] === id), 'the own row appears in the personal list').toBe(true);
+
+      // the power surface still serves the full record
+      const power = await client.get(entity, id);
+      expect(power[idProperty]).toBe(id);
+
+      // a row with no owner is foreign to everyone: the personal controller must 404 it and the
+      // personal list must not include it (only checkable when the owner relation is optional)
+      const ownerRelation = (entity.relations ?? []).find((relation) => relation.name === entity.personal.owner);
+      if (ownerRelation && !ownerRelation.required) {
+        const foreign = await client.create(entity, await buildPayload(api));
+        foreignId = foreign?.[idProperty];
+        const foreignThroughMine = await api.get(manifest.restBase + mine.api + '/' + foreignId);
+        expect(foreignThroughMine.status(), 'a foreign row must 404 through the personal controller').toBe(404);
+        const rowsAfter = await client.list(mine, 1000);
+        expect(rowsAfter.some((row) => row[idProperty] === foreignId), 'a foreign row must not appear in the personal list').toBe(false);
+      }
+    } finally {
+      deleted = await client.remove(mine, id); // deleting the OWN row through the personal controller works
+      if (foreignId) await client.remove(entity, foreignId);
+    }
+    // ... unless a `whenDeleted: refuse` process guards the record while its instance runs
+    if (deleted) {
+      const gone = await api.get(manifest.restBase + mine.api + '/' + id);
+      expect(gone.status()).toBe(404);
+    }
+  });
+
+  // wave 2: the UI-parity walk over the same personal surface (older manifests without the
+  // route/layout metadata regenerate to get it - skip quietly until then)
+  if (entity.personal.route) {
+    myUiTest(manifest, entity, mine, buildContext, idProperty);
+  }
+}

package/src/flows/rest.js

@@ -0,0 +1,57 @@
+import { makeApi } from '../api.js';
+import { expect, test } from '../fixtures.js';
+import { resolveRelationSamples } from '../form.js';
+import { freshUniqueKeys, freshUniques, handleField, sampleRecord } from '../sample-values.js';
+
+// The same contract over the generated REST controllers, no browser: isolates backend
+// failures from UI failures and verifies the manifest's field names bind.
+export function restFlow(manifest, entity, opts = {}) {
+  const cfg = opts.extend?.entities?.[entity.name] ?? {};
+  if (new Set(cfg.skip ?? []).has('rest')) return;
+  const idProperty = manifest.idProperty ?? 'Id';
+
+  test(`${entity.name}: REST create, read, update and delete`, async ({ api }) => {
+    const client = makeApi(api, manifest);
+    const payload = sampleRecord(entity);
+    const handle = handleField(entity);
+    // same resolution the UI flow uses: cross-model targets via apiAbsolute, entityStatus
+    // relations left to their init: DB default
+    const samples = await resolveRelationSamples(api, manifest, entity);
+    const taken = await freshUniqueKeys(client, entity, payload, samples);
+    test.skip(!!taken, `every ${entity.name} combination of the unique key [${taken}] tried already has a row`);
+    for (const sample of samples) {
+      payload[sample.relation.name] = sample.id;
+    }
+    await freshUniques(client, entity, payload);
+
+    const created = await client.create(entity, payload);
+    const id = created?.[idProperty];
+    expect(id, 'create response carries the generated id').toBeTruthy();
+    let deleted;
+    try {
+      const read = await client.get(entity, id);
+      expect(read[idProperty]).toBe(id);
+      // the update round-trip needs a writable string field to flip; skip it when there is none
+      if (handle) {
+        expect(read[handle.name]).toBe(payload[handle.name]);
+
+        const updatedValue = payload[handle.name] + '-UPD';
+        await client.update(entity, id, { ...read, [handle.name]: updatedValue });
+        const reread = await client.get(entity, id);
+        expect(reread[handle.name]).toBe(updatedValue);
+      }
+    } finally {
+      deleted = await client.remove(entity, id);
+    }
+    if (!deleted) {
+      // the record's process guard refused the delete (409) - assert the other half of that promise:
+      // the row is still served. A guarded entity can also delete cleanly, when its instance had
+      // already finished, so which outcome is expected is only knowable after the attempt.
+      const kept = await client.get(entity, id);
+      expect(kept[idProperty], `delete refused by ${entity.deleteGuardedByProcess.join(', ')} - the record must survive`).toBe(id);
+      return;
+    }
+    const gone = await client.getResponse(entity, id);
+    expect(gone.status()).toBe(404);
+  });
+}

package/src/flows/shell.js

@@ -0,0 +1,17 @@
+import { expect, test } from '../fixtures.js';
+
+// Shared application shell (/services/web/application/): the entity's menu item exists
+// under its nav group and opens the module SPA in the embedded iframe. Requires the
+// navigation module that defines the groups, so it is opt-in: APPTEST_SHELL=1.
+export function shellFlow(manifest, entity) {
+  if (!entity.route) return; // no power page, no menu item
+  test(`${entity.name}: shared shell menu item opens the module`, async ({ page }) => {
+    test.skip(!process.env.APPTEST_SHELL, 'APPTEST_SHELL=1 enables the shared shell flow');
+    await page.goto('/services/web/application/');
+    const item = page.getByText(entity.labelPlural, { exact: true }).first();
+    await expect(item).toBeVisible();
+    await item.click();
+    const app = page.frameLocator('iframe').first();
+    await expect(app.getByText(entity.labelPlural, { exact: true }).first()).toBeVisible();
+  });
+}