From 14f83eec6784313799ec6be5b702845bd9d9fb5b Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 08:26:03 +0000 Subject: [PATCH 01/12] test: add an HTTP call helper for the integration journeys --- src/test/helpers/http.ts | 46 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 src/test/helpers/http.ts diff --git a/src/test/helpers/http.ts b/src/test/helpers/http.ts new file mode 100644 index 0000000..c92f878 --- /dev/null +++ b/src/test/helpers/http.ts @@ -0,0 +1,46 @@ +import { isJsonValue, type JsonValue } from "../../types/json"; +import type { OwnerSession } from "../ownerSession"; + +/** The test DMS's API root, served by the harness's `api` module. */ +export const API_ROOT = "http://127.0.0.1:5023/api"; + +/** What the backend answered: its status, its body as JSON (`null` when it is not JSON), and its raw text. */ +export interface HttpAnswer { + readonly status: number; + readonly body: JsonValue; + readonly text: string; +} + +function parsed(text: string): JsonValue { + try { + const value: unknown = JSON.parse(text); + return isJsonValue(value) ? value : null; + } catch { + return null; + } +} + +/** + * Calls `path` under {@link API_ROOT} as `session`, or with no session when it is `null`, the way the dashboard + * does: a bearer token and the default namespace. Never throws on a status. + */ +export async function call( + session: OwnerSession | null, + method: string, + path: string, + body?: JsonValue, +): Promise { + const headers = new Headers({ + accept: "application/json", + "x-antelopejs-namespace": "default", + }); + if (body !== undefined) headers.set("content-type", "application/json"); + if (session !== null) headers.set("authorization", `Bearer ${session.token}`); + const response = await fetch(`${API_ROOT}${path}`, { + method, + headers, + body: body === undefined ? undefined : JSON.stringify(body), + }); + const text = await response.text(); + return { status: response.status, body: parsed(text), text }; +} From 22548d3448efca82c9491e766fc56ef6fcd3520b Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 08:44:10 +0000 Subject: [PATCH 02/12] test(diagram): port the HTTP journeys to integration tests The layout, notes, note refusals and owner-only journeys of the Diagram feature run in src/test/diagram.journeys.test.ts through HTTP, and leave the Playwright suite. --- .../verify-dms-database/features/README.md | 2 +- .../verify-dms-database/features/diagram.md | 13 +- e2e/journeys/diagram.mjs | 3 +- e2e/journeys/parts/diagram-api.mjs | 130 --------- src/test/diagram.journeys.test.ts | 273 ++++++++++++++++++ src/test/helpers/jsonAt.ts | 30 ++ 6 files changed, 314 insertions(+), 137 deletions(-) delete mode 100644 e2e/journeys/parts/diagram-api.mjs create mode 100644 src/test/diagram.journeys.test.ts create mode 100644 src/test/helpers/jsonAt.ts diff --git a/.agents/skills/verify-dms-database/features/README.md b/.agents/skills/verify-dms-database/features/README.md index 249e6c9..6d3ca3d 100644 --- a/.agents/skills/verify-dms-database/features/README.md +++ b/.agents/skills/verify-dms-database/features/README.md @@ -9,7 +9,7 @@ One file per feature. `covers:` lists the source globs it owns, `docs:` the page | [config](config.md) | # Config | built-in-patterns-label-schemas-by-the-start-of-their-id, an-exact-key-beats-a-pattern-which-beats-a-built-in-label, a-glob-key-matches-the-whole-schema-id, a-label-takes-each-of-the-seven-tones | | [access](access.md) | # Access | every-route-needs-a-signed-in-session, a-member-gets-403-from-every-route-and-writes-nothing, a-member-sees-neither-the-pages-nor-the-catalog-tile, the-catalog-tile-reads-the-database, the-owner-only-gate-is-logged-at-start | | [schemas](schemas.md) | # Schemas | the-source-counts-rows-columns-indexes-relations-and-modifiers-of-each-table, schema-instance-search-and-structure-filters-narrow-the-source-and-combine, rows-are-counted-in-the-picked-instance-default-named-or-all, the-instances-route-searches-sorts-and-limits-the-named-instances-of-a-schema, a-table-is-read-by-its-schema-and-name-id, columns-are-declared-in-code-and-inferred-from-sampled-rows, the-tables-and-schemas-routes-answer-the-platform-owner-only, each-filter-of-the-bar-narrows-the-list-and-sets-its-own-url-key, the-url-restores-every-filter-after-a-reload-and-clear-removes-them, slash-focuses-the-search-field-but-not-while-typing-or-with-a-modifier, a-filter-that-matches-nothing-says-no-result-and-clear-filters-restores-the-list, each-of-the-five-sortable-columns-sorts-both-ways-and-the-third-click-restores-the-default-order, the-relations-and-modifiers-columns-name-the-tables-and-the-flags, a-row-click-opens-the-inspector-and-previous-next-j-and-k-step-through-the-list, dragging-the-drawer-edge-resizes-it-and-it-opens-at-the-width-you-left-it, the-inspector-states-the-counts-and-lists-each-column-with-its-type-null-and-notes, a-column-named-constructor-is-listed-like-any-other-column, the-indexes-and-relations-tabs-list-what-the-table-declares-and-a-relation-opens-the-other-table, the-sample-row-tab-shows-one-row-and-another-row-pages-through-the-table, browse-query-and-diagram-actions-open-the-other-pages-on-the-same-table | -| [diagram](diagram.md) | # Diagram | the-layout-api-stores-one-layout-per-schema-and-refuses-bad-positions, the-notes-api-creates-lists-updates-and-deletes-notes-per-schema, the-notes-api-refuses-missing-numbers-with-400-and-unknown-notes-with-404, every-diagram-route-answers-the-platform-owner-only, tables-list-their-columns-with-types-and-icons-and-relations-are-arrows, an-encrypted-column-carries-the-lock-icon-of-the-legend, a-table-of-more-than-twelve-columns-comes-folded-and-folding-is-not-saved, folding-is-a-setting-of-your-own-view-and-is-not-saved-with-the-team-layout, finding-a-column-a-folded-table-hides-unfolds-that-table, the-fold-keeps-the-twelve-column-boundary-and-every-column-an-arrow-ends-on, a-large-schema-opens-at-forty-percent-on-its-top-left-and-fit-view-shows-it-whole, a-relation-to-a-table-not-drawn-ends-on-a-dashed-chip-that-opens-that-table, a-relation-to-another-schema-ends-on-a-chip-that-opens-that-table, the-url-picks-the-schema-and-the-table-and-names-what-it-cannot-find, a-schema-without-a-table-says-so-and-offers-no-note-or-auto-layout, dragging-a-table-saves-the-layout-and-everyone-reads-it, a-table-not-placed-yet-takes-its-automatic-place-and-placed-tables-stay, auto-layout-previews-the-arrangement-and-keep-or-discard-decides, auto-layout-keeps-groups-together-and-clear-of-notes-that-never-move, n-and-the-note-button-drop-a-note-ready-to-write-and-it-is-saved-with-the-schema, a-double-click-edits-a-note-and-the-trash-button-and-delete-remove-it, notes-belong-to-their-schema-and-everyone-reads-them, undo-and-redo-cover-every-move-and-note-and-are-saved, escape-leaves-the-find-field-then-lifts-the-focus-then-clears-the-selection | +| [diagram](diagram.md) | # Diagram | tables-list-their-columns-with-types-and-icons-and-relations-are-arrows, an-encrypted-column-carries-the-lock-icon-of-the-legend, a-table-of-more-than-twelve-columns-comes-folded-and-folding-is-not-saved, folding-is-a-setting-of-your-own-view-and-is-not-saved-with-the-team-layout, finding-a-column-a-folded-table-hides-unfolds-that-table, the-fold-keeps-the-twelve-column-boundary-and-every-column-an-arrow-ends-on, a-large-schema-opens-at-forty-percent-on-its-top-left-and-fit-view-shows-it-whole, a-relation-to-a-table-not-drawn-ends-on-a-dashed-chip-that-opens-that-table, a-relation-to-another-schema-ends-on-a-chip-that-opens-that-table, the-url-picks-the-schema-and-the-table-and-names-what-it-cannot-find, a-schema-without-a-table-says-so-and-offers-no-note-or-auto-layout, dragging-a-table-saves-the-layout-and-everyone-reads-it, a-table-not-placed-yet-takes-its-automatic-place-and-placed-tables-stay, auto-layout-previews-the-arrangement-and-keep-or-discard-decides, auto-layout-keeps-groups-together-and-clear-of-notes-that-never-move, n-and-the-note-button-drop-a-note-ready-to-write-and-it-is-saved-with-the-schema, a-double-click-edits-a-note-and-the-trash-button-and-delete-remove-it, notes-belong-to-their-schema-and-everyone-reads-them, undo-and-redo-cover-every-move-and-note-and-are-saved, escape-leaves-the-find-field-then-lifts-the-focus-then-clears-the-selection | | [data](data.md) | # Data | the-instance-picker-lists-named-instances-with-a-search-and-a-limit, list-clamps-the-page-and-orders-the-rows, list-filters-search-and-counts-follow-the-wire-tokens, the-selection-decodes-schema-table-and-instance, columns-get-and-tables-answer-what-the-grid-needs, references-count-the-rows-pointing-at-a-row, the-browse-api-answers-the-platform-owner-only, the-sidebar-counts-each-table-in-the-picked-instance, tables-open-as-preview-tabs-and-are-kept-on-demand, links-open-the-table-in-the-instance-they-name, search-filters-and-sort-narrow-and-order-the-rows, the-footer-pages-1250-rows-with-exact-ranges-at-every-size, r-refreshes-the-rows-and-the-search-shortcut-works-from-the-grid, the-row-drawer-steps-through-the-page-with-j-and-k, the-row-drawer-shows-fields-json-and-the-rows-pointing-at-it, the-fields-tab-widens-long-values-and-sets-null-with-the-dashed-circle, all-instances-is-a-read-only-view-with-the-instance-column, recently-opened-tables-are-offered-when-no-tab-is-open, no-match-and-empty-tables-say-so, a-refused-read-shows-the-error-and-try-again-reads-it-again | | [editing](editing.md) | # Editing | edits-are-staged-then-reviewed-then-written-one-put-per-row, invalid-drafts-are-refused-esc-cancels-and-a-click-away-decides, null-empties-a-cell-and-backslash-null-is-the-text-null, object-and-array-cells-open-the-json-editor-in-a-side-drawer, the-json-editor-is-as-tall-as-the-drawer, discard-and-closing-a-tab-with-staged-changes-ask-first, undo-writes-the-previous-values-back-within-the-window, undo-is-offered-for-ten-seconds-then-the-values-stay, a-row-deleted-meanwhile-drops-its-changes-and-the-rest-is-saved, a-failed-write-stops-the-save-and-the-rows-left-stay-staged, a-saved-row-shows-in-place-unless-the-save-may-move-rows, a-save-under-a-search-or-a-filter-reads-the-page-again, an-edit-and-its-undo-land-in-the-instance-of-the-tab-only, saved-cells-keep-their-type-numbers-booleans-dates-and-objects, the-edit-route-writes-typed-values-and-refuses-the-rest, hashed-encrypted-and-localized-columns-are-written-as-typed, the-row-drawer-stages-edits-like-the-cells-do, an-undo-whose-write-fails-keeps-the-saved-values-and-offers-undo-again | | [query](query.md) | # Query | a-query-returns-its-rows-in-the-order-it-asks, an-instance-and-every-instance-are-targeted, a-failed-query-says-what-failed-and-offers-the-nearest-name, the-insert-chips-add-their-operation, ctrl-space-completes-schemas-and-tables-from-the-workspace, an-empty-console-offers-examples-built-on-your-own-tables, results-over-1000-rows-are-cut-at-1000, the-table-view-shows-every-returned-row, an-export-of-uneven-rows-keeps-every-key-in-csv-and-json, csv-quotes-a-comma-a-quote-and-a-line-break-so-the-cell-reads-back, format-strips-trailing-spaces-and-blank-lines, ctrl-space-inside-a-filter-completes-the-columns-of-the-table, the-chart-plots-the-first-numeric-column-with-pickers-for-both-axes, open-in-data-browser-opens-the-target-table-or-the-row, copy-as-json-puts-the-returned-rows-on-the-clipboard, a-link-opens-the-console-on-the-table-in-the-instance-it-names | diff --git a/.agents/skills/verify-dms-database/features/diagram.md b/.agents/skills/verify-dms-database/features/diagram.md index 837cbce..85c2fd2 100644 --- a/.agents/skills/verify-dms-database/features/diagram.md +++ b/.agents/skills/verify-dms-database/features/diagram.md @@ -25,10 +25,6 @@ The Diagram page draws the tables of one schema and the relations between them, ## Sub-features -- `the-layout-api-stores-one-layout-per-schema-and-refuses-bad-positions`: PUT and GET of the layout, replacement, isolation per schema, 400 refusals. -- `the-notes-api-creates-lists-updates-and-deletes-notes-per-schema`: note CRUD and its fields. -- `the-notes-api-refuses-missing-numbers-with-400-and-unknown-notes-with-404`: note refusals. -- `every-diagram-route-answers-the-platform-owner-only`: 401 and 403 on all six routes. - `tables-list-their-columns-with-types-and-icons-and-relations-are-arrows`: columns, types, icons against the legend, arrows, labels. - `an-encrypted-column-carries-the-lock-icon-of-the-legend`: modifier icons. - `a-table-of-more-than-twelve-columns-comes-folded-and-folding-is-not-saved`: the fold, `+ 5 columns`, click, Enter, Fold columns. @@ -59,6 +55,15 @@ The Diagram page draws the tables of one schema and the relations between them, - `the-layout-and-the-notes-survive-a-backend-restart`: a dragged table and a note are kept over a restart. - `each-relation-arrow-starts-at-its-own-column`: arrow origins for three relations. +## Integration tests + +`pnpm test` runs these in `src/test/diagram.journeys.test.ts`, one `it` per id, so `-g ` selects one. + +- `the-layout-api-stores-one-layout-per-schema-and-refuses-bad-positions`: PUT and GET of the layout, replacement, isolation per schema, 400 refusals. +- `the-notes-api-creates-lists-updates-and-deletes-notes-per-schema`: note CRUD and its fields. +- `the-notes-api-refuses-missing-numbers-with-400-and-unknown-notes-with-404`: note refusals. +- `every-diagram-route-answers-the-platform-owner-only`: 401 and 403 on all six routes. + ## How to get to it (user POV) - Modules › Database › Diagram, or Show in diagram from a table (`?schema=&table=`). diff --git a/e2e/journeys/diagram.mjs b/e2e/journeys/diagram.mjs index d5571dc..2275c1c 100644 --- a/e2e/journeys/diagram.mjs +++ b/e2e/journeys/diagram.mjs @@ -5,7 +5,6 @@ import { arrangement, preview, whileLoading } from "./parts/diagram-auto.mjs"; import { dragging, placement } from "./parts/diagram-layout.mjs"; import { keyJourneys } from "./parts/diagram-keys.mjs"; import { escapeJourneys } from "./parts/diagram-escape.mjs"; -import { layoutApi, notesApi, notesRefusals, ownerOnly } from "./parts/diagram-api.mjs"; /** The Diagram page: its tables, folds, layout, notes, shortcuts and the routes behind them. */ -export const journeys = [layoutApi, notesApi, notesRefusals, ownerOnly, reading, modifierIcons, folding, foldRule, notSaved, finding, startView, stubs, crossSchema, deepLinks, emptySchema, dragging, placement, preview, whileLoading, arrangement, notes, editing, sharedNotes, undoing, ...keyJourneys, ...escapeJourneys]; +export const journeys = [reading, modifierIcons, folding, foldRule, notSaved, finding, startView, stubs, crossSchema, deepLinks, emptySchema, dragging, placement, preview, whileLoading, arrangement, notes, editing, sharedNotes, undoing, ...keyJourneys, ...escapeJourneys]; diff --git a/e2e/journeys/parts/diagram-api.mjs b/e2e/journeys/parts/diagram-api.mjs deleted file mode 100644 index 91b6f83..0000000 --- a/e2e/journeys/parts/diagram-api.mjs +++ /dev/null @@ -1,130 +0,0 @@ -import { check, db, member, pick, text } from "../../database.mjs"; -import { savedLayout, savedNotes } from "./diagram-page.mjs"; - -/** @typedef {import("../../database.mjs").Ctx} Ctx */ -/** @typedef {{ id: string, title: string, entryPoint: string, run: (ctx: Ctx) => Promise }} JourneyDef */ - -const NOTE = { schemaName: "shop", text: "reorder", x: 12.5, y: -40, width: 220, height: 140 }; - -/** @type {JourneyDef} */ -export const layoutApi = { - id: "the-layout-api-stores-one-layout-per-schema-and-refuses-bad-positions", - title: "a schema's layout is stored with PUT and read back with GET exactly, an unknown schema reads empty, a second PUT replaces the first, layouts of two schemas stay apart, and positions that are not finite numbers are refused 400", - entryPoint: "GET/PUT /api/database/diagram/layout/:schema", - async run(ctx) { - const empty = await savedLayout(ctx, "shop", "read the layout before any save"); - const put = await db(ctx, "save the shop layout", "PUT", "/diagram/layout/shop?connection=own", { body: { positions: { orders: { x: 10.5, y: -3 }, customers: { x: 400, y: 20 } } } }); - const first = await savedLayout(ctx, "shop"); - const replaced = await db(ctx, "save another shop layout", "PUT", "/diagram/layout/shop?connection=own", { body: { positions: { products: { x: 1, y: 2 } } } }); - const second = await savedLayout(ctx, "shop"); - await db(ctx, "save the vault layout", "PUT", "/diagram/layout/vault?connection=own", { body: { positions: { accounts: { x: 7, y: 8 } } } }); - const vault = await savedLayout(ctx, "vault"); - const shopAgain = await savedLayout(ctx, "shop"); - const unknown = await savedLayout(ctx, "no-such-schema", "read the layout of an unknown schema"); - const missing = await db(ctx, "save without positions", "PUT", "/diagram/layout/shop?connection=own", { body: {} }); - const text1 = await db(ctx, "save a text position", "PUT", "/diagram/layout/shop?connection=own", { body: { positions: { orders: { x: "a", y: 1 } } } }); - const missingY = await db(ctx, "save a position without y", "PUT", "/diagram/layout/shop?connection=own", { body: { positions: { orders: { x: 1 } } } }); - const afterRefusals = await savedLayout(ctx, "shop", "read the layout after the refusals"); - const cleared = await db(ctx, "save an empty layout", "PUT", "/diagram/layout/shop?connection=own", { body: { positions: {} } }); - const none = await savedLayout(ctx, "shop", "read the emptied layout"); - await ctx.verify("the layout routes", [ - check("a schema without a save reads no position", Object.keys(empty).length === 0, empty), - check("a save answers success", pick(put.body, "success") === true && put.status === 200, put), - check("the layout reads back exactly", JSON.stringify(first) === JSON.stringify({ orders: { x: 10.5, y: -3 }, customers: { x: 400, y: 20 } }), first), - check("a second save replaces the first", pick(replaced.body, "success") === true && JSON.stringify(second) === JSON.stringify({ products: { x: 1, y: 2 } }), second), - check("each schema keeps its own layout", JSON.stringify(vault) === JSON.stringify({ accounts: { x: 7, y: 8 } }) && JSON.stringify(shopAgain) === JSON.stringify(second), [vault, shopAgain]), - check("an unknown schema reads empty", Object.keys(unknown).length === 0, unknown), - check("a body without positions is refused 400", missing.status === 400, missing), - check("a text coordinate is refused 400", text1.status === 400 && text(text1.body).includes("finite"), text1), - check("a position without y is refused 400", missingY.status === 400, missingY), - check("a refused save changes nothing", JSON.stringify(afterRefusals) === JSON.stringify(second), afterRefusals), - check("an empty layout is a valid save", cleared.status === 200 && Object.keys(none).length === 0, none), - ]); - }, -}; - -/** @type {JourneyDef} */ -export const notesApi = { - id: "the-notes-api-creates-lists-updates-and-deletes-notes-per-schema", - title: "notes are created with a position and size, listed by schema, updated in part and deleted, each schema keeping its own", - entryPoint: "GET/POST /api/database/diagram/notes, PUT/DELETE /notes/:id", - async run(ctx) { - const created = await db(ctx, "create a note", "POST", "/diagram/notes?connection=own", { body: NOTE }); - const id = text(created.body, "id"); - const other = await db(ctx, "create a vault note", "POST", "/diagram/notes?connection=own", { body: { schemaName: "vault", x: 1, y: 2, width: 3, height: 4 } }); - const shopNotes = await savedNotes(ctx, "shop"); - const vaultNotes = await savedNotes(ctx, "vault"); - const updated = await db(ctx, "move and write the note", "PUT", `/diagram/notes/${id}?connection=own`, { body: { text: "done", x: 99 } }); - const colored = await db(ctx, "color the note", "PUT", `/diagram/notes/${id}?connection=own`, { body: { color: "warning" } }); - const reread = await savedNotes(ctx, "shop"); - const removed = await db(ctx, "delete the note", "DELETE", `/diagram/notes/${id}?connection=own`); - const afterDelete = await savedNotes(ctx, "shop"); - const vaultStill = await savedNotes(ctx, "vault"); - const note = shopNotes[0]; - await ctx.verify("the notes routes", [ - check("a note comes back with its fields", pick(created.body, "schemaName") === "shop" && pick(created.body, "text") === "reorder" && pick(created.body, "x") === 12.5 && pick(created.body, "y") === -40 && pick(created.body, "width") === 220 && pick(created.body, "height") === 140 && pick(created.body, "color") === null, created.body), - check("it has an id and ISO dates", id.length > 5 && !Number.isNaN(Date.parse(text(created.body, "createdAt"))) && text(created.body, "createdAt") === text(created.body, "updatedAt"), created.body), - check("a schema lists its own notes only", shopNotes.length === 1 && text(note, "id") === id && vaultNotes.length === 1 && text(vaultNotes[0], "id") === text(other.body, "id"), [shopNotes, vaultNotes]), - check("an update changes the sent fields only", pick(updated.body, "text") === "done" && pick(updated.body, "x") === 99 && pick(updated.body, "y") === -40 && pick(updated.body, "width") === 220, updated.body), - check("a color is kept", pick(colored.body, "color") === "warning" && pick(colored.body, "text") === "done", colored.body), - check("an update moves updatedAt forward", Date.parse(text(updated.body, "updatedAt")) >= Date.parse(text(created.body, "updatedAt")), updated.body), - check("the list reads the update back", text(reread[0], "text") === "done" && pick(reread[0], "x") === 99 && pick(reread[0], "color") === "warning", reread), - check("a delete answers success and removes only that note", pick(removed.body, "success") === true && afterDelete.length === 0 && vaultStill.length === 1, [afterDelete, vaultStill]), - check("a deleted note cannot be deleted again", (await db(ctx, "delete it again", "DELETE", `/diagram/notes/${id}?connection=own`)).status === 404, id), - ]); - }, -}; - -/** @type {JourneyDef} */ -export const ownerOnly = { - id: "every-diagram-route-answers-the-platform-owner-only", - title: "the layout and notes routes refuse a request without a session 401 and a member who is not the platform owner 403, for reading and writing", - entryPoint: "/api/database/diagram/**", - async run(ctx) { - await member(ctx, "reader", []); - /** @type {{ method: string, path: string, body?: unknown }[]} */ - const calls = [ - { method: "GET", path: "/diagram/layout/shop" }, - { method: "PUT", path: "/diagram/layout/shop", body: { positions: {} } }, - { method: "GET", path: "/diagram/notes?schema=shop" }, - { method: "POST", path: "/diagram/notes", body: NOTE }, - { method: "PUT", path: "/diagram/notes/x", body: { text: "y" } }, - { method: "DELETE", path: "/diagram/notes/x" }, - ]; - const checks = []; - for (const { method, path, body } of calls) { - const anon = await db(ctx, `${method} ${path} without a session`, method, path, { as: "anon", body }); - const reader = await db(ctx, `${method} ${path} as a member`, method, path, { as: "reader", body }); - checks.push(check(`${method} ${path} refuses nobody 401`, anon.status === 401, anon.status), check(`${method} ${path} refuses a member 403`, reader.status === 403, reader.status)); - } - const stored = await savedNotes(ctx, "shop"); - checks.push(check("the refused calls stored nothing", stored.length === 0, stored)); - await ctx.verify("who may use the diagram routes", checks); - }, -}; - -/** @type {JourneyDef} */ -export const notesRefusals = { - id: "the-notes-api-refuses-missing-numbers-with-400-and-unknown-notes-with-404", - title: "a note without a schema, width or height, or with a coordinate that is not a number, is refused 400, listing needs a schema, and updating or deleting an unknown note is refused 404 and stores nothing", - entryPoint: "POST/PUT/DELETE /api/database/diagram/notes", - async run(ctx) { - const created = await db(ctx, "create a note", "POST", "/diagram/notes?connection=own", { body: NOTE }); - const id = text(created.body, "id"); - const noHeight = await db(ctx, "create a note without height", "POST", "/diagram/notes?connection=own", { body: { schemaName: "shop", x: 1, y: 2, width: 3 } }); - const noSchema = await db(ctx, "create a note without schema", "POST", "/diagram/notes?connection=own", { body: { x: 1, y: 2, width: 3, height: 4 } }); - const nanX = await db(ctx, "update with a text coordinate", "PUT", `/diagram/notes/${id}?connection=own`, { body: { x: "far" } }); - const unknownPut = await db(ctx, "update an unknown note", "PUT", "/diagram/notes/nope?connection=own", { body: { text: "x" } }); - const unknownDelete = await db(ctx, "delete an unknown note", "DELETE", "/diagram/notes/nope?connection=own"); - const withoutSchema = await db(ctx, "list without a schema", "GET", "/diagram/notes"); - const kept = await savedNotes(ctx, "shop"); - await ctx.verify("the notes refusals", [ - check("a note without a height is refused 400", noHeight.status === 400, noHeight), - check("a note without a schema is refused 400", noSchema.status === 400, noSchema), - check("a text coordinate is refused 400 and changes nothing", nanX.status === 400 && pick(kept[0], "x") === 12.5, [nanX, kept]), - check("an unknown note cannot be updated or deleted", unknownPut.status === 404 && unknownDelete.status === 404, [unknownPut.status, unknownDelete.status]), - check("listing needs a schema", withoutSchema.status === 400, withoutSchema), - check("only the one valid note is stored", kept.length === 1, kept), - ]); - }, -}; diff --git a/src/test/diagram.journeys.test.ts b/src/test/diagram.journeys.test.ts new file mode 100644 index 0000000..0ee038e --- /dev/null +++ b/src/test/diagram.journeys.test.ts @@ -0,0 +1,273 @@ +import { strict as assert } from "node:assert"; +import { GetModel } from "@antelopejs/interface-database-decorators"; +import { DiagramLayoutModel, DiagramNoteModel } from "../db"; +import { OWN_CONNECTION } from "../types/constants"; +import type { JsonObject, JsonValue } from "../types/json"; +import { call } from "./helpers/http"; +import { at, itemsAt, textAt } from "./helpers/jsonAt"; +import { + createMemberSession, + createOwnerSession, + type OwnerSession, +} from "./ownerSession"; + +const SHOP = "diagram-journeys-shop"; +const VAULT = "diagram-journeys-vault"; +const UNKNOWN = "diagram-journeys-none"; +const NOTES = "/database/diagram/notes"; +const NOTE: JsonObject = { + schemaName: SHOP, + text: "reorder", + x: 12.5, + y: -40, + width: 220, + height: 140, +}; + +let owner: OwnerSession; +let member: OwnerSession; + +async function clearAll(): Promise { + const notes = GetModel(DiagramNoteModel); + const layouts = GetModel(DiagramLayoutModel); + for (const schemaName of [SHOP, VAULT, UNKNOWN]) { + for (const note of await notes.listFor(OWN_CONNECTION, schemaName)) + await notes.delete(note._id); + for (const row of await layouts.getBy("schemaName", schemaName)) + await layouts.delete(row._id); + } +} + +async function layoutOf(schema: string): Promise { + const answer = await call(owner, "GET", `/database/diagram/layout/${schema}`); + return at(answer.body, "positions"); +} + +function saveLayout(schema: string, body: JsonObject) { + return call( + owner, + "PUT", + `/database/diagram/layout/${schema}?connection=own`, + body, + ); +} + +async function notesOf(schema: string): Promise { + const answer = await call(owner, "GET", `${NOTES}?schema=${schema}`); + return itemsAt(answer.body, "items"); +} + +function writeNote(method: string, path: string, body?: JsonObject) { + return call(owner, method, `${NOTES}${path}?connection=own`, body); +} + +function fields(note: JsonValue, names: string[]): JsonValue[] { + return names.map((name) => at(note, name)); +} + +async function layoutApi(): Promise { + assert.deepEqual(await layoutOf(SHOP), {}, "no save reads no position"); + const first = { orders: { x: 10.5, y: -3 }, customers: { x: 400, y: 20 } }; + const put = await saveLayout(SHOP, { positions: first }); + assert.equal(put.status, 200); + assert.deepEqual(put.body, { success: true }, "a save answers success"); + assert.deepEqual( + await layoutOf(SHOP), + first, + "a layout stored rounded would not read back exactly", + ); + const second = { products: { x: 1, y: 2 } }; + const replaced = await saveLayout(SHOP, { positions: second }); + assert.deepEqual(replaced.body, { success: true }); + assert.deepEqual( + await layoutOf(SHOP), + second, + "a save merged into the first would keep orders", + ); + await saveLayout(VAULT, { positions: { accounts: { x: 7, y: 8 } } }); + assert.deepEqual(await layoutOf(VAULT), { accounts: { x: 7, y: 8 } }); + assert.deepEqual( + await layoutOf(SHOP), + second, + "one layout for every schema would read vault's", + ); + assert.deepEqual(await layoutOf(UNKNOWN), {}, "an unknown schema is empty"); + + const missing = await saveLayout(SHOP, {}); + assert.equal(missing.status, 400, "a body without positions is refused"); + const text = await saveLayout(SHOP, { + positions: { orders: { x: "a", y: 1 } }, + }); + assert.equal(text.status, 400, "a text coordinate is refused 400"); + assert.ok(text.text.includes("finite"), text.text); + const missingY = await saveLayout(SHOP, { positions: { orders: { x: 1 } } }); + assert.equal(missingY.status, 400, "a position without y is refused 400"); + assert.deepEqual( + await layoutOf(SHOP), + second, + "a refused save that stored part of its body would change the layout", + ); + + const cleared = await saveLayout(SHOP, { positions: {} }); + assert.equal(cleared.status, 200, "an empty layout is a valid save"); + assert.deepEqual(await layoutOf(SHOP), {}); +} + +async function notesApi(): Promise { + const created = await writeNote("POST", "", NOTE); + const id = textAt(created.body, "id"); + const other = await writeNote("POST", "", { + schemaName: VAULT, + x: 1, + y: 2, + width: 3, + height: 4, + }); + assert.deepEqual( + fields(created.body, [ + "schemaName", + "text", + "x", + "y", + "width", + "height", + "color", + ]), + [SHOP, "reorder", 12.5, -40, 220, 140, null], + "a note comes back with its fields", + ); + const createdAt = textAt(created.body, "createdAt"); + assert.ok(id.length > 5, "it has an id"); + assert.ok(!Number.isNaN(Date.parse(createdAt)), "createdAt is a date"); + assert.equal(createdAt, textAt(created.body, "updatedAt")); + const ids = async (schema: string) => + (await notesOf(schema)).map((note) => textAt(note, "id")); + assert.deepEqual( + [await ids(SHOP), await ids(VAULT)], + [[id], [textAt(other.body, "id")]], + "a list that ignored the schema would hold both notes", + ); + + const updated = await writeNote("PUT", `/${id}`, { text: "done", x: 99 }); + assert.deepEqual( + fields(updated.body, ["text", "x", "y", "width"]), + ["done", 99, -40, 220], + "an update that replaced the note would lose y and width", + ); + const colored = await writeNote("PUT", `/${id}`, { color: "warning" }); + assert.deepEqual( + fields(colored.body, ["color", "text"]), + ["warning", "done"], + "a color is kept", + ); + assert.ok( + Date.parse(textAt(updated.body, "updatedAt")) >= Date.parse(createdAt), + "an update moves updatedAt forward", + ); + assert.deepEqual( + fields((await notesOf(SHOP))[0] ?? null, ["text", "x", "color"]), + ["done", 99, "warning"], + "the list reads the update back", + ); + + const removed = await writeNote("DELETE", `/${id}`); + assert.deepEqual(removed.body, { success: true }); + assert.deepEqual(await ids(SHOP), [], "the deleted note is gone"); + assert.equal( + (await ids(VAULT)).length, + 1, + "a delete by schema would remove vault's note", + ); + const again = await writeNote("DELETE", `/${id}`); + assert.equal(again.status, 404, "a deleted note cannot be deleted again"); +} + +async function notesRefusals(): Promise { + const created = await writeNote("POST", "", NOTE); + const id = textAt(created.body, "id"); + const noHeight = await writeNote("POST", "", { + schemaName: SHOP, + x: 1, + y: 2, + width: 3, + }); + const noSchema = await writeNote("POST", "", { + x: 1, + y: 2, + width: 3, + height: 4, + }); + const nanX = await writeNote("PUT", `/${id}`, { x: "far" }); + const unknownPut = await writeNote("PUT", "/nope", { text: "x" }); + const unknownDelete = await writeNote("DELETE", "/nope"); + const withoutSchema = await call(owner, "GET", NOTES); + const kept = await notesOf(SHOP); + assert.equal(noHeight.status, 400, "a note without a height is refused"); + assert.equal(noSchema.status, 400, "a note without a schema is refused"); + assert.equal(nanX.status, 400, "a text coordinate is refused 400"); + assert.equal( + at(kept[0] ?? null, "x"), + 12.5, + "a refused update that wrote the coordinate would move the note", + ); + assert.deepEqual( + [unknownPut.status, unknownDelete.status], + [404, 404], + "an unknown note cannot be updated or deleted", + ); + assert.equal(withoutSchema.status, 400, "listing needs a schema"); + assert.equal(kept.length, 1, "only the one valid note is stored"); +} + +async function ownerOnly(): Promise { + const calls: { method: string; path: string; body?: JsonObject }[] = [ + { method: "GET", path: `/database/diagram/layout/${SHOP}` }, + { + method: "PUT", + path: `/database/diagram/layout/${SHOP}`, + body: { positions: {} }, + }, + { method: "GET", path: `${NOTES}?schema=${SHOP}` }, + { method: "POST", path: NOTES, body: NOTE }, + { method: "PUT", path: `${NOTES}/x`, body: { text: "y" } }, + { method: "DELETE", path: `${NOTES}/x` }, + ]; + for (const { method, path, body } of calls) { + const anonymous = await call(null, method, path, body); + const reader = await call(member, method, path, body); + assert.equal(anonymous.status, 401, `${method} ${path} refuses nobody`); + assert.equal(reader.status, 403, `${method} ${path} refuses a member`); + } + assert.deepEqual( + await notesOf(SHOP), + [], + "a refused call that still ran its handler would store a note", + ); +} + +describe("[integration] diagram journeys", () => { + before(async () => { + owner = await createOwnerSession("diagram-journeys-owner@test.local"); + member = await createMemberSession("diagram-journeys-member@test.local"); + }); + beforeEach(clearAll); + after(async () => { + await clearAll(); + await owner.remove(); + await member.remove(); + }); + + it( + "the-layout-api-stores-one-layout-per-schema-and-refuses-bad-positions", + layoutApi, + ); + it( + "the-notes-api-creates-lists-updates-and-deletes-notes-per-schema", + notesApi, + ); + it( + "the-notes-api-refuses-missing-numbers-with-400-and-unknown-notes-with-404", + notesRefusals, + ); + it("every-diagram-route-answers-the-platform-owner-only", ownerOnly); +}); diff --git a/src/test/helpers/jsonAt.ts b/src/test/helpers/jsonAt.ts new file mode 100644 index 0000000..ff6e3e2 --- /dev/null +++ b/src/test/helpers/jsonAt.ts @@ -0,0 +1,30 @@ +import { isJsonObjectValue, type JsonValue } from "../../types/json"; +import { isString } from "../../utils/guards"; + +/** The value at `path` inside `value`, or `null` when a step is not an object or lacks the key. */ +export function at(value: JsonValue, ...path: string[]): JsonValue { + let current = value; + for (const key of path) { + if (!isJsonObjectValue(current)) return null; + current = current[key] ?? null; + } + return current; +} + +/** The array at `path` inside `value`, or an empty one when it is not an array. */ +export function itemsAt(value: JsonValue, ...path: string[]): JsonValue[] { + const found = at(value, ...path); + return Array.isArray(found) ? found : []; +} + +/** The string at `path` inside `value`, or `""` when it is not a string. */ +export function textAt(value: JsonValue, ...path: string[]): string { + const found = at(value, ...path); + return isString(found) ? found : ""; +} + +/** The member names of the object at `path` inside `value`, in order, or none when it is not an object. */ +export function keysAt(value: JsonValue, ...path: string[]): string[] { + const found = at(value, ...path); + return isJsonObjectValue(found) ? Object.keys(found) : []; +} From 00d3281b30c0c03975e7e01c6589bd65ed61b061 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 08:44:17 +0000 Subject: [PATCH 03/12] test(schemas): port the HTTP journeys to integration tests The source, filters, instance counts, instances, single table, column inference and owner-only journeys run in src/test/schemas.journeys.test.ts on schemas the test registers, and leave the Playwright suite. --- .../verify-dms-database/features/README.md | 2 +- .../verify-dms-database/features/schemas.md | 19 +- e2e/journeys/parts/schema-api.mjs | 32 -- e2e/journeys/parts/schema-source-rows.mjs | 111 ---- e2e/journeys/parts/schema-source.mjs | 131 ----- e2e/journeys/schemas.mjs | 4 +- src/test/helpers/schemasPlayground.ts | 387 ++++++++++++++ src/test/schemas.journeys.test.ts | 505 ++++++++++++++++++ 8 files changed, 906 insertions(+), 285 deletions(-) delete mode 100644 e2e/journeys/parts/schema-source-rows.mjs delete mode 100644 e2e/journeys/parts/schema-source.mjs create mode 100644 src/test/helpers/schemasPlayground.ts create mode 100644 src/test/schemas.journeys.test.ts diff --git a/.agents/skills/verify-dms-database/features/README.md b/.agents/skills/verify-dms-database/features/README.md index 6d3ca3d..7a123a9 100644 --- a/.agents/skills/verify-dms-database/features/README.md +++ b/.agents/skills/verify-dms-database/features/README.md @@ -8,7 +8,7 @@ One file per feature. `covers:` lists the source globs it owns, `docs:` the page | [overview](overview.md) | # Overview | the-connection-card-reads-the-probe, a-configured-driver-label-shows-beside-the-age, without-a-driver-label-the-card-shows-a-dash, the-card-age-counts-up-and-the-probe-repeats-every-thirty-seconds, schema-cards-list-every-schema-largest-first, largest-tables-rank-the-default-instances-by-rows, recent-queries-list-your-last-five-runs, the-header-buttons-lead-to-the-working-pages, an-unreachable-database-shows-unavailable-and-check-again-recovers | | [config](config.md) | # Config | built-in-patterns-label-schemas-by-the-start-of-their-id, an-exact-key-beats-a-pattern-which-beats-a-built-in-label, a-glob-key-matches-the-whole-schema-id, a-label-takes-each-of-the-seven-tones | | [access](access.md) | # Access | every-route-needs-a-signed-in-session, a-member-gets-403-from-every-route-and-writes-nothing, a-member-sees-neither-the-pages-nor-the-catalog-tile, the-catalog-tile-reads-the-database, the-owner-only-gate-is-logged-at-start | -| [schemas](schemas.md) | # Schemas | the-source-counts-rows-columns-indexes-relations-and-modifiers-of-each-table, schema-instance-search-and-structure-filters-narrow-the-source-and-combine, rows-are-counted-in-the-picked-instance-default-named-or-all, the-instances-route-searches-sorts-and-limits-the-named-instances-of-a-schema, a-table-is-read-by-its-schema-and-name-id, columns-are-declared-in-code-and-inferred-from-sampled-rows, the-tables-and-schemas-routes-answer-the-platform-owner-only, each-filter-of-the-bar-narrows-the-list-and-sets-its-own-url-key, the-url-restores-every-filter-after-a-reload-and-clear-removes-them, slash-focuses-the-search-field-but-not-while-typing-or-with-a-modifier, a-filter-that-matches-nothing-says-no-result-and-clear-filters-restores-the-list, each-of-the-five-sortable-columns-sorts-both-ways-and-the-third-click-restores-the-default-order, the-relations-and-modifiers-columns-name-the-tables-and-the-flags, a-row-click-opens-the-inspector-and-previous-next-j-and-k-step-through-the-list, dragging-the-drawer-edge-resizes-it-and-it-opens-at-the-width-you-left-it, the-inspector-states-the-counts-and-lists-each-column-with-its-type-null-and-notes, a-column-named-constructor-is-listed-like-any-other-column, the-indexes-and-relations-tabs-list-what-the-table-declares-and-a-relation-opens-the-other-table, the-sample-row-tab-shows-one-row-and-another-row-pages-through-the-table, browse-query-and-diagram-actions-open-the-other-pages-on-the-same-table | +| [schemas](schemas.md) | # Schemas | each-filter-of-the-bar-narrows-the-list-and-sets-its-own-url-key, the-url-restores-every-filter-after-a-reload-and-clear-removes-them, slash-focuses-the-search-field-but-not-while-typing-or-with-a-modifier, a-filter-that-matches-nothing-says-no-result-and-clear-filters-restores-the-list, each-of-the-five-sortable-columns-sorts-both-ways-and-the-third-click-restores-the-default-order, the-relations-and-modifiers-columns-name-the-tables-and-the-flags, a-row-click-opens-the-inspector-and-previous-next-j-and-k-step-through-the-list, dragging-the-drawer-edge-resizes-it-and-it-opens-at-the-width-you-left-it, the-inspector-states-the-counts-and-lists-each-column-with-its-type-null-and-notes, a-column-named-constructor-is-listed-like-any-other-column, the-indexes-and-relations-tabs-list-what-the-table-declares-and-a-relation-opens-the-other-table, the-sample-row-tab-shows-one-row-and-another-row-pages-through-the-table, browse-query-and-diagram-actions-open-the-other-pages-on-the-same-table | | [diagram](diagram.md) | # Diagram | tables-list-their-columns-with-types-and-icons-and-relations-are-arrows, an-encrypted-column-carries-the-lock-icon-of-the-legend, a-table-of-more-than-twelve-columns-comes-folded-and-folding-is-not-saved, folding-is-a-setting-of-your-own-view-and-is-not-saved-with-the-team-layout, finding-a-column-a-folded-table-hides-unfolds-that-table, the-fold-keeps-the-twelve-column-boundary-and-every-column-an-arrow-ends-on, a-large-schema-opens-at-forty-percent-on-its-top-left-and-fit-view-shows-it-whole, a-relation-to-a-table-not-drawn-ends-on-a-dashed-chip-that-opens-that-table, a-relation-to-another-schema-ends-on-a-chip-that-opens-that-table, the-url-picks-the-schema-and-the-table-and-names-what-it-cannot-find, a-schema-without-a-table-says-so-and-offers-no-note-or-auto-layout, dragging-a-table-saves-the-layout-and-everyone-reads-it, a-table-not-placed-yet-takes-its-automatic-place-and-placed-tables-stay, auto-layout-previews-the-arrangement-and-keep-or-discard-decides, auto-layout-keeps-groups-together-and-clear-of-notes-that-never-move, n-and-the-note-button-drop-a-note-ready-to-write-and-it-is-saved-with-the-schema, a-double-click-edits-a-note-and-the-trash-button-and-delete-remove-it, notes-belong-to-their-schema-and-everyone-reads-them, undo-and-redo-cover-every-move-and-note-and-are-saved, escape-leaves-the-find-field-then-lifts-the-focus-then-clears-the-selection | | [data](data.md) | # Data | the-instance-picker-lists-named-instances-with-a-search-and-a-limit, list-clamps-the-page-and-orders-the-rows, list-filters-search-and-counts-follow-the-wire-tokens, the-selection-decodes-schema-table-and-instance, columns-get-and-tables-answer-what-the-grid-needs, references-count-the-rows-pointing-at-a-row, the-browse-api-answers-the-platform-owner-only, the-sidebar-counts-each-table-in-the-picked-instance, tables-open-as-preview-tabs-and-are-kept-on-demand, links-open-the-table-in-the-instance-they-name, search-filters-and-sort-narrow-and-order-the-rows, the-footer-pages-1250-rows-with-exact-ranges-at-every-size, r-refreshes-the-rows-and-the-search-shortcut-works-from-the-grid, the-row-drawer-steps-through-the-page-with-j-and-k, the-row-drawer-shows-fields-json-and-the-rows-pointing-at-it, the-fields-tab-widens-long-values-and-sets-null-with-the-dashed-circle, all-instances-is-a-read-only-view-with-the-instance-column, recently-opened-tables-are-offered-when-no-tab-is-open, no-match-and-empty-tables-say-so, a-refused-read-shows-the-error-and-try-again-reads-it-again | | [editing](editing.md) | # Editing | edits-are-staged-then-reviewed-then-written-one-put-per-row, invalid-drafts-are-refused-esc-cancels-and-a-click-away-decides, null-empties-a-cell-and-backslash-null-is-the-text-null, object-and-array-cells-open-the-json-editor-in-a-side-drawer, the-json-editor-is-as-tall-as-the-drawer, discard-and-closing-a-tab-with-staged-changes-ask-first, undo-writes-the-previous-values-back-within-the-window, undo-is-offered-for-ten-seconds-then-the-values-stay, a-row-deleted-meanwhile-drops-its-changes-and-the-rest-is-saved, a-failed-write-stops-the-save-and-the-rows-left-stay-staged, a-saved-row-shows-in-place-unless-the-save-may-move-rows, a-save-under-a-search-or-a-filter-reads-the-page-again, an-edit-and-its-undo-land-in-the-instance-of-the-tab-only, saved-cells-keep-their-type-numbers-booleans-dates-and-objects, the-edit-route-writes-typed-values-and-refuses-the-rest, hashed-encrypted-and-localized-columns-are-written-as-typed, the-row-drawer-stages-edits-like-the-cells-do, an-undo-whose-write-fails-keeps-the-saved-values-and-offers-undo-again | diff --git a/.agents/skills/verify-dms-database/features/schemas.md b/.agents/skills/verify-dms-database/features/schemas.md index ae8e541..f10f485 100644 --- a/.agents/skills/verify-dms-database/features/schemas.md +++ b/.agents/skills/verify-dms-database/features/schemas.md @@ -31,13 +31,6 @@ The Schemas page lists every table the loaded modules register, with the rows co ## Sub-features -- `the-source-counts-rows-columns-indexes-relations-and-modifiers-of-each-table`: the source route's exact figures for ten known tables, `all` equal to the tables the schemas route registers. -- `schema-instance-search-and-structure-filters-narrow-the-source-and-combine`: scope, name or column search (case, trim), relations, modifiers, empty, combinations, unknown flags, `all` unchanged by filters. -- `rows-are-counted-in-the-picked-instance-default-named-or-all`: default, `eu`, `us`, `all` and an unknown instance, and `empty` judged in the picked instance. -- `the-instances-route-searches-sorts-and-limits-the-named-instances-of-a-schema`: search, numeric sort, limit and its clamps, 400 and 404. -- `a-table-is-read-by-its-schema-and-name-id`: the single-table route and its refusals. -- `columns-are-declared-in-code-and-inferred-from-sampled-rows`: declared columns first, sampled columns after, nulls as unions, arrays by element, no instance tag, a column named `constructor`. -- `the-tables-and-schemas-routes-answer-the-platform-owner-only`: 401 without a session, 403 for a member. - `each-filter-of-the-bar-narrows-the-list-and-sets-its-own-url-key`: every filter in the UI, its URL key, the `N of M tables` count only while filtered. - `the-url-restores-every-filter-after-a-reload-and-clear-removes-them`: shared link, reload, Clear, Escape, another schema dropping a named instance. - `slash-focuses-the-search-field-but-not-while-typing-or-with-a-modifier`: the `/` shortcut. @@ -54,6 +47,18 @@ The Schemas page lists every table the loaded modules register, with the rows co - `with-modifiers-keeps-a-table-with-only-a-hashed-only-a-localized-or-only-an-encrypted-column`: the "or" of the With modifiers filter: three single-modifier tables of the `mods` schema stay in the API and in the list, each flagging only its own modifier. - `a-narrow-inspector-scrolls-its-columns-table-and-its-tabs-sideways`: the drawer narrowed to its minimum scrolls the columns table and the tab strip sideways. +## Integration tests + +`pnpm test` runs these in `src/test/schemas.journeys.test.ts`, one `it` per id, so `-g ` selects one. + +- `the-source-counts-rows-columns-indexes-relations-and-modifiers-of-each-table`: the source route's exact figures for ten known tables, `all` equal to the tables the schemas route registers. +- `schema-instance-search-and-structure-filters-narrow-the-source-and-combine`: scope, name or column search (case, trim), relations, modifiers, empty, combinations, unknown flags, `all` unchanged by filters. +- `rows-are-counted-in-the-picked-instance-default-named-or-all`: default, `eu`, `us`, `all` and an unknown instance, and `empty` judged in the picked instance. +- `the-instances-route-searches-sorts-and-limits-the-named-instances-of-a-schema`: search, numeric sort, limit and its clamps, 400 and 404. +- `a-table-is-read-by-its-schema-and-name-id`: the single-table route and its refusals. +- `columns-are-declared-in-code-and-inferred-from-sampled-rows`: declared columns first, sampled columns after, nulls as unions, arrays by element, no instance tag, a column named `constructor`. +- `the-tables-and-schemas-routes-answer-the-platform-owner-only`: 401 without a session, 403 for a member. + ## How to get to it (user POV) - Modules › Database › Schemas (`/modules/database/schemas`); `?scope=&instance=&q=&has=` filter, `?record=::` opens an inspector. diff --git a/e2e/journeys/parts/schema-api.mjs b/e2e/journeys/parts/schema-api.mjs index d61b008..ce22957 100644 --- a/e2e/journeys/parts/schema-api.mjs +++ b/e2e/journeys/parts/schema-api.mjs @@ -41,35 +41,3 @@ export async function source(ctx, label, filters = {}) { export function ids(rows) { return rows.map((row) => text(row, "id")); } - -/** - * @param {Row[]} rows Source rows - * @param {string} id A `schema::table` id - * @returns {Row | undefined} The row with that id - */ -export function rowOf(rows, id) { - return rows.find((row) => text(row, "id") === id); -} - -/** - * Reads every schema with its tables. - * - * @param {Ctx} ctx The journey - * @param {string} label What the call does - * @returns {Promise} The schemas - */ -export async function schemas(ctx, label) { - const answer = await db(ctx, label, "GET", "/schemas"); - return list(answer.body, "schemas"); -} - -/** - * @param {Row[]} all The schemas - * @param {string} schemaId A schema id - * @param {string} table A table name - * @returns {Row | undefined} The table's summary - */ -export function tableOf(all, schemaId, table) { - const schema = all.find((entry) => text(entry, "id") === schemaId); - return list(schema, "tables").find((entry) => text(entry, "name") === table); -} diff --git a/e2e/journeys/parts/schema-source-rows.mjs b/e2e/journeys/parts/schema-source-rows.mjs deleted file mode 100644 index 24418bf..0000000 --- a/e2e/journeys/parts/schema-source-rows.mjs +++ /dev/null @@ -1,111 +0,0 @@ -import { check, db, isRow, list, member, pick, text } from "../../database.mjs"; -import { schemas, tableOf } from "./schema-api.mjs"; - -/** @typedef {import("../../database.mjs").Ctx} Ctx */ -/** @typedef {{ id: string, title: string, entryPoint: string, run: (ctx: Ctx) => Promise }} JourneyDef */ - -/** @type {JourneyDef} */ -export const instanceSearch = { - id: "the-instances-route-searches-sorts-and-limits-the-named-instances-of-a-schema", - title: "a schema's named instances come sorted with numbers by value, are searched by part of the name in any case, cut at the limit (clamped between 1 and 500) with how many matched, and refuse a missing or unknown schema", - entryPoint: "GET /api/database/tables/instances", - async run(ctx) { - const get = (/** @type {string} */ label, /** @type {string} */ query) => db(ctx, label, "GET", `/tables/instances?${query}`); - const shop = await get("instances of shop", "schema=shop"); - const searchedEu = await get("search E", "schema=shop&search=E"); - const searchedUs = await get("search S", "schema=shop&search=S"); - const noMatch = await get("search zzz", "schema=shop&search=zzz"); - const tenants = await get("instances of links", "schema=links"); - const limited = await get("limit 2", "schema=links&limit=2"); - const floor = await get("limit 0", "schema=links&limit=0"); - const garbage = await get("limit abc", "schema=links&limit=abc"); - const ceiling = await get("limit 9999", "schema=links&limit=9999"); - const plain = await get("instances of metrics", "schema=metrics"); - const unknown = await get("unknown schema", "schema=nope"); - const absent = await get("no schema", ""); - await ctx.verify("the named instances", [ - check("shop has eu and us", JSON.stringify(pick(shop.body, "instances")) === '["eu","us"]' && pick(shop.body, "total") === 2, shop.body), - check("a search matches part of a name in any case", JSON.stringify(pick(searchedEu.body, "instances")) === '["eu"]' && JSON.stringify(pick(searchedUs.body, "instances")) === '["us"]', [searchedEu.body, searchedUs.body]), - check("a search with no match is empty", JSON.stringify(pick(noMatch.body, "instances")) === "[]" && pick(noMatch.body, "total") === 0, noMatch.body), - check("numbers sort by value", JSON.stringify(pick(tenants.body, "instances")) === '["tenant-1","tenant-2","tenant-10"]', tenants.body), - check("the limit cuts the list and total says how many matched", JSON.stringify(pick(limited.body, "instances")) === '["tenant-1","tenant-2"]' && pick(limited.body, "total") === 3, limited.body), - check("a limit under 1 is read as 1", JSON.stringify(pick(floor.body, "instances")) === '["tenant-1"]' && pick(floor.body, "total") === 3, floor.body), - check("an unreadable limit falls back to the default of 100", pick(garbage.body, "total") === 3 && list(garbage.body, "instances").length === 0 && Array.isArray(pick(garbage.body, "instances")) && String(pick(garbage.body, "instances")) === "tenant-1,tenant-2,tenant-10", garbage.body), - check("a large limit is clamped, not refused", ceiling.status === 200 && pick(ceiling.body, "total") === 3, ceiling.body), - check("a schema without named instances lists none", JSON.stringify(pick(plain.body, "instances")) === "[]" && pick(plain.body, "total") === 0, plain.body), - check("an unknown schema is refused 404", unknown.status === 404, unknown), - check("a missing schema is refused 400", absent.status === 400, absent), - ]); - }, -}; - -/** @type {JourneyDef} */ -export const singleRow = { - id: "a-table-is-read-by-its-schema-and-name-id", - title: "the row of a table is read by its schema::name id with its rows counted in the default instance, an unknown id is refused 404 and a missing one 400", - entryPoint: "GET /api/database/tables/source/row", - async run(ctx) { - const found = await db(ctx, "read vault::wide_records", "GET", "/tables/source/row?id=vault::wide_records"); - const related = await db(ctx, "read links::customer_refs", "GET", "/tables/source/row?id=links::customer_refs"); - const wrongCase = await db(ctx, "read VAULT::wide_records", "GET", "/tables/source/row?id=VAULT::wide_records"); - const unknown = await db(ctx, "read an unknown id", "GET", "/tables/source/row?id=vault::nothing"); - const missing = await db(ctx, "read without an id", "GET", "/tables/source/row"); - const blank = await db(ctx, "read an empty id", "GET", "/tables/source/row?id="); - await ctx.verify("single table rows", [ - check("the row holds the table's figures", pick(found.body, "schema") === "vault" && pick(found.body, "name") === "wide_records" && pick(found.body, "elementCount") === 1 && pick(found.body, "columnCount") === 17 && pick(found.body, "indexCount") === 0, found.body), - check("its relation is named without the schema when it is the same", JSON.stringify(pick(found.body, "relations")) === '["parents_registry"]', found.body), - check("a relation to another schema is named with it", JSON.stringify(pick(related.body, "relations")) === '["shop.customers"]', related.body), - check("ids are case-sensitive", wrongCase.status === 404, wrongCase.status), - check("an unknown id is refused 404", unknown.status === 404, unknown), - check("a missing id is refused 400", missing.status === 400, missing), - check("an empty id is refused 400", blank.status === 400, blank), - ]); - }, -}; - -/** @type {JourneyDef} */ -export const inference = { - id: "columns-are-declared-in-code-and-inferred-from-sampled-rows", - title: "a table lists its declared columns first (key, indexed, relation fields), then the other columns sampled from its rows with their types, null shown as a union, objects and arrays typed, the instance tag left out, and a column named like an object member kept", - entryPoint: "GET /api/database/schemas", - async run(ctx) { - const all = await schemas(ctx, "read the schemas"); - const fieldsOf = (/** @type {string} */ schema, /** @type {string} */ table) => pick(tableOf(all, schema, table), "fields"); - const kinds = (/** @type {unknown} */ fields) => (isRow(fields) ? Object.entries(fields).map(([name, descriptor]) => `${name}:${text(descriptor, "kind")}`) : []); - const orders = fieldsOf("shop", "orders"); - const members = fieldsOf("quirks", "members"); - const shop = all.find((schema) => text(schema, "id") === "shop"); - const hollow = all.find((schema) => text(schema, "id") === "hollow"); - await ctx.verify("column inference", [ - check("declared columns come first, sampled ones after, in order", JSON.stringify(kinds(orders)) === JSON.stringify(["_id:string", "number:string", "customer_id:string", "status:string", "created_at:date", "channel:string", "total:number", "currency:string", "coupon_id:union", "shipping:object"]), kinds(orders)), - check("a column holding null in some rows is a union of its type and null", JSON.stringify(pick(orders, "coupon_id", "members")) === JSON.stringify([{ kind: "string" }, { kind: "null" }]), pick(orders, "coupon_id")), - check("columns no decorator names are typed by their rows", JSON.stringify(kinds(fieldsOf("shop", "customers"))) === JSON.stringify(["_id:string", "email:string", "company:string", "credit_limit:number", "vip:boolean"]), kinds(fieldsOf("shop", "customers"))), - check("an array is typed by its elements", JSON.stringify(pick(fieldsOf("shop", "products"), "tags")) === JSON.stringify({ kind: "array", element: { kind: "string" } }), pick(fieldsOf("shop", "products"), "tags")), - check("an array of no element stays untyped", JSON.stringify(pick(fieldsOf("demo", "posts"), "tag_ids")) === JSON.stringify({ kind: "array" }), pick(fieldsOf("demo", "posts"), "tag_ids")), - check("the columns of a table whose rows are all in named instances are sampled from them", Object.keys(fieldsOf("shop", "order_items") ?? {}).join() === "_id,order_id,product_id,quantity,unit_price", fieldsOf("shop", "order_items")), - check("the instance tag of the store is not a column", ![...Object.keys(orders ?? {}), ...Object.keys(fieldsOf("shop", "customers") ?? {})].includes("_instance"), Object.keys(orders ?? {})), - check("a column named constructor is a column of its own", JSON.stringify(Object.keys(members ?? {})) === JSON.stringify(["_id", "constructor", "note"]), Object.keys(members ?? {})), - check("a schema reports its instances and stats", JSON.stringify(pick(shop, "instances")) === '["eu","us"]' && JSON.stringify(pick(shop, "stats")) === JSON.stringify({ tableCount: 4, elementCount: 6, instanceCount: 3 }), pick(shop, "stats")), - check("a schema without a table is listed with none", hollow !== undefined && list(hollow, "tables").length === 0 && pick(hollow, "stats", "tableCount") === 0, hollow), - ]); - }, -}; - -/** @type {JourneyDef} */ -export const ownerOnly = { - id: "the-tables-and-schemas-routes-answer-the-platform-owner-only", - title: "the schemas and tables routes refuse a request without a session 401 and a member who is not the platform owner 403", - entryPoint: "GET /api/database/schemas, /tables/source, /tables/source/row, /tables/instances", - async run(ctx) { - await member(ctx, "reader", []); - const paths = ["/schemas", "/tables/source", "/tables/source/row?id=shop::orders", "/tables/instances?schema=shop"]; - const checks = []; - for (const path of paths) { - const anon = await db(ctx, `${path} without a session`, "GET", path, { as: "anon" }); - const reader = await db(ctx, `${path} as a member`, "GET", path, { as: "reader" }); - const owner = await db(ctx, `${path} as the owner`, "GET", path); - checks.push(check(`${path} refuses nobody 401`, anon.status === 401, anon.status), check(`${path} refuses a member 403`, reader.status === 403, reader.status), check(`${path} answers the owner`, owner.status === 200, owner.status)); - } - await ctx.verify("who may read", checks); - }, -}; diff --git a/e2e/journeys/parts/schema-source.mjs b/e2e/journeys/parts/schema-source.mjs deleted file mode 100644 index 5bf0926..0000000 --- a/e2e/journeys/parts/schema-source.mjs +++ /dev/null @@ -1,131 +0,0 @@ -import { check, db, list, pick, text } from "../../database.mjs"; -import { ids, rowOf, schemas, source } from "./schema-api.mjs"; - -/** @typedef {import("../../database.mjs").Ctx} Ctx */ -/** @typedef {{ id: string, title: string, entryPoint: string, run: (ctx: Ctx) => Promise }} JourneyDef */ - -/** - * @param {import("../../database.mjs").Row | undefined} row A source row - * @param {{ rows: number, columns: number, indexes: number, relations: string[], modifiers: string[] }} expected What the row holds - * @returns {boolean} Whether it holds exactly that - */ -function rowIs(row, expected) { - return ( - pick(row, "elementCount") === expected.rows && - pick(row, "columnCount") === expected.columns && - pick(row, "indexCount") === expected.indexes && - JSON.stringify(pick(row, "relations")) === JSON.stringify(expected.relations) && - JSON.stringify(pick(row, "modifiers")) === JSON.stringify(expected.modifiers) - ); -} - -/** @type {JourneyDef} */ -export const tableCounts = { - id: "the-source-counts-rows-columns-indexes-relations-and-modifiers-of-each-table", - title: "each table of the source holds its rows in the default instance, its column, index and relation counts, the tables it points to (schema.table outside its schema) and its modifier names", - entryPoint: "GET /api/database/tables/source", - async run(ctx) { - const listing = await source(ctx, "list every table"); - const reference = await schemas(ctx, "read the schemas the source is made of"); - const registered = reference.reduce((sum, schema) => sum + list(schema, "tables").length, 0); - const expectations = { - "shop::customers": { rows: 0, columns: 5, indexes: 1, relations: [], modifiers: [] }, - "shop::products": { rows: 6, columns: 4, indexes: 1, relations: [], modifiers: [] }, - "shop::orders": { rows: 0, columns: 10, indexes: 3, relations: ["customers"], modifiers: [] }, - "shop::order_items": { rows: 0, columns: 5, indexes: 1, relations: ["orders", "products"], modifiers: [] }, - "vault::accounts": { rows: 2, columns: 5, indexes: 1, relations: [], modifiers: ["Hashed", "Encrypted", "Localized"] }, - "vault::wide_records": { rows: 1, columns: 17, indexes: 0, relations: ["parents_registry"], modifiers: [] }, - "links::customer_refs": { rows: 0, columns: 2, indexes: 0, relations: ["shop.customers"], modifiers: [] }, - "demo::posts": { rows: 3, columns: 5, indexes: 2, relations: ["tags"], modifiers: [] }, - "metrics::readings": { rows: 1250, columns: 4, indexes: 1, relations: [], modifiers: [] }, - "metrics::empty_log": { rows: 0, columns: 2, indexes: 0, relations: [], modifiers: [] }, - }; - await ctx.verify("the listing counts", [ - check("the call answers 200", listing.status === 200, listing.status), - check("total is the number of rows listed", listing.total === listing.rows.length, [listing.total, listing.rows.length]), - check("all is the number of tables the schemas register", listing.all === registered && registered === listing.rows.length, [listing.all, registered, listing.rows.length]), - check("every id is schema::table and unique", new Set(ids(listing.rows)).size === listing.rows.length && ids(listing.rows).every((id) => id === `${id.split("::")[0]}::${id.split("::")[1]}` && id.split("::").length === 2), ids(listing.rows).slice(0, 5)), - ...Object.entries(expectations).map(([id, expected]) => check(`${id} holds ${JSON.stringify(expected)}`, rowIs(rowOf(listing.rows, id), expected), rowOf(listing.rows, id))), - check("every row names its schema and table", listing.rows.every((row) => text(row, "id") === `${text(row, "schema")}::${text(row, "name")}`), listing.rows.length), - ]); - }, -}; - -/** @type {JourneyDef} */ -export const filters = { - id: "schema-instance-search-and-structure-filters-narrow-the-source-and-combine", - title: "the schema, the name or column search (any case, trimmed), the relations, modifiers and empty flags narrow the tables, combine all together, ignore unknown flags, and leave the all count alone", - entryPoint: "GET /api/database/tables/source?filter_scope=&filter_q=&filter_has=", - async run(ctx) { - const everything = await source(ctx, "unfiltered"); - const shop = await source(ctx, "scope shop", { scope: "shop" }); - const none = await source(ctx, "scope that does not exist", { scope: "nope" }); - const byName = await source(ctx, "search ORDER in shop", { scope: "shop", q: "ORDER" }); - const trimmed = await source(ctx, "search ' order ' in shop", { scope: "shop", q: " order " }); - const byColumn = await source(ctx, "search email in shop", { scope: "shop", q: "email" }); - const either = await source(ctx, "search customer in shop", { scope: "shop", q: "customer" }); - const exactColumn = await source(ctx, "search customer_id in shop", { scope: "shop", q: "customer_id" }); - const tail = await source(ctx, "search tail_marker everywhere", { q: "tail_marker" }); - const related = await source(ctx, "relations in shop", { scope: "shop", has: "relations" }); - const modified = await source(ctx, "modifiers in vault", { scope: "vault", has: "modifiers" }); - const both = await source(ctx, "relations and modifiers in vault", { scope: "vault", has: "relations,modifiers" }); - const spaced = await source(ctx, "relations with an unknown flag", { scope: "shop", has: "relations, bogus" }); - const bogus = await source(ctx, "only an unknown flag", { scope: "shop", has: "bogus" }); - const empty = await source(ctx, "empty in shop, default instance", { scope: "shop", has: "empty" }); - const combined = await source(ctx, "search, relations and empty in shop", { scope: "shop", q: "order", has: "relations,empty" }); - const nonEmptyPlusModifiers = await source(ctx, "empty and modifiers in vault", { scope: "vault", has: "modifiers,empty" }); - const sorted = (/** @type {{ rows: import("../../database.mjs").Row[] }} */ listing) => ids(listing.rows).sort(); - await ctx.verify("the filters", [ - check("unfiltered lists every table", everything.total === everything.all && everything.rows.length === everything.all, [everything.total, everything.all]), - check("a schema lists its own tables only", JSON.stringify(sorted(shop)) === JSON.stringify(["shop::customers", "shop::order_items", "shop::orders", "shop::products"]), sorted(shop)), - check("the schema filter leaves all as the registered count", shop.all === everything.all && shop.total === 4, [shop.total, shop.all]), - check("an unknown schema lists nothing", none.total === 0 && none.rows.length === 0 && none.all === everything.all, [none.total, none.all]), - check("a name matches in any case", JSON.stringify(sorted(byName)) === JSON.stringify(["shop::order_items", "shop::orders"]), sorted(byName)), - check("a search is trimmed", JSON.stringify(sorted(trimmed)) === JSON.stringify(sorted(byName)), sorted(trimmed)), - check("a column name finds its table", JSON.stringify(sorted(byColumn)) === JSON.stringify(["shop::customers"]), sorted(byColumn)), - check("a search names the table or a column", JSON.stringify(sorted(either)) === JSON.stringify(["shop::customers", "shop::orders"]), sorted(either)), - check("a column name is not a table name", JSON.stringify(sorted(exactColumn)) === JSON.stringify(["shop::orders"]), sorted(exactColumn)), - check("a column found beyond the first twelve still finds the table", JSON.stringify(sorted(tail)) === JSON.stringify(["vault::wide_records"]), sorted(tail)), - check("relations keeps the tables that point to another table", JSON.stringify(sorted(related)) === JSON.stringify(["shop::order_items", "shop::orders"]), sorted(related)), - check("modifiers keeps the tables with hashed, localized or encrypted columns", JSON.stringify(sorted(modified)) === JSON.stringify(["vault::accounts"]), sorted(modified)), - check("both structure flags must hold", both.total === 0, sorted(both)), - check("an unknown flag is ignored among known ones", JSON.stringify(sorted(spaced)) === JSON.stringify(sorted(related)), sorted(spaced)), - check("only an unknown flag filters nothing", bogus.total === 4, sorted(bogus)), - check("empty keeps the tables without a row in the default instance", JSON.stringify(sorted(empty)) === JSON.stringify(["shop::customers", "shop::order_items", "shop::orders"]), sorted(empty)), - check("search, relations and empty combine", JSON.stringify(sorted(combined)) === JSON.stringify(["shop::order_items", "shop::orders"]), sorted(combined)), - check("modifiers and empty combine: vault.accounts holds two rows, so no table is both", JSON.stringify(sorted(nonEmptyPlusModifiers)) === "[]", sorted(nonEmptyPlusModifiers)), - ]); - }, -}; - -/** @type {JourneyDef} */ -export const instanceCounts = { - id: "rows-are-counted-in-the-picked-instance-default-named-or-all", - title: "rows count in the default instance unless an instance is picked: a region counts its own rows, all counts every instance at once, and empty means no row in the picked instance", - entryPoint: "GET /api/database/tables/source?filter_instance=", - async run(ctx) { - const counts = async (/** @type {string | undefined} */ instance) => { - const listing = await source(ctx, `shop rows in ${instance ?? "the default instance"}`, { scope: "shop", instance }); - return Object.fromEntries(listing.rows.map((row) => [text(row, "name"), pick(row, "elementCount")])); - }; - const byDefault = await counts(undefined); - const eu = await counts("eu"); - const us = await counts("us"); - const all = await counts("all"); - const missing = await counts("atlantis"); - const emptyInEu = await source(ctx, "empty in eu", { scope: "shop", instance: "eu", has: "empty" }); - const emptyInAll = await source(ctx, "empty in all", { scope: "shop", instance: "all", has: "empty" }); - const metricsInEu = await source(ctx, "empty metrics in eu", { scope: "metrics", instance: "eu", has: "empty" }); - const row = await db(ctx, "read orders by id", "GET", "/tables/source/row?id=shop::orders"); - await ctx.verify("rows per instance", [ - check("no instance counts the default one", JSON.stringify(byDefault) === JSON.stringify({ customers: 0, products: 6, orders: 0, order_items: 0 }), byDefault), - check("eu counts its own rows", JSON.stringify(eu) === JSON.stringify({ customers: 24, products: 6, orders: 80, order_items: 160 }), eu), - check("us counts its own rows", JSON.stringify(us) === JSON.stringify({ customers: 24, products: 6, orders: 80, order_items: 160 }), us), - check("all counts every instance at once", all.customers === 48 && all.orders === 160 && all.order_items === 320 && all.products === 18, all), - check("an instance that does not exist counts nothing", Object.values(missing).every((count) => count === 0), missing), - check("empty is judged in the picked instance", emptyInEu.total === 0 && emptyInAll.total === 0, [emptyInEu.total, emptyInAll.total]), - check("empty in eu keeps both metrics tables", JSON.stringify(ids(metricsInEu.rows).sort()) === JSON.stringify(["metrics::empty_log", "metrics::readings"]), ids(metricsInEu.rows)), - check("a single row is counted in the default instance", pick(row.body, "elementCount") === 0 && pick(row.body, "id") === "shop::orders" && pick(row.body, "columnCount") === 10, row.body), - ]); - }, -}; diff --git a/e2e/journeys/schemas.mjs b/e2e/journeys/schemas.mjs index d96afd7..f2b4a59 100644 --- a/e2e/journeys/schemas.mjs +++ b/e2e/journeys/schemas.mjs @@ -4,8 +4,6 @@ import { resizing, stepping } from "./parts/schema-inspector.mjs"; import { factsAndColumns, indexesAndRelations, quirkColumn, sampleRow } from "./parts/schema-tabs.mjs"; import { modifierJourneys } from "./parts/schema-modifiers.mjs"; import { actions } from "./parts/schema-actions.mjs"; -import { filters, instanceCounts, tableCounts } from "./parts/schema-source.mjs"; -import { inference, instanceSearch, ownerOnly, singleRow } from "./parts/schema-source-rows.mjs"; /** The Schemas page: its tables, filters, sorting, inspector and the routes behind them. */ -export const journeys = [tableCounts, filters, instanceCounts, instanceSearch, singleRow, inference, ownerOnly, eachFilter, restored, slash, noResult, sorting, columnsOfTags, stepping, resizing, factsAndColumns, quirkColumn, indexesAndRelations, sampleRow, actions, ...modifierJourneys]; +export const journeys = [eachFilter, restored, slash, noResult, sorting, columnsOfTags, stepping, resizing, factsAndColumns, quirkColumn, indexesAndRelations, sampleRow, actions, ...modifierJourneys]; diff --git a/src/test/helpers/schemasPlayground.ts b/src/test/helpers/schemasPlayground.ts new file mode 100644 index 0000000..83d85ec --- /dev/null +++ b/src/test/helpers/schemasPlayground.ts @@ -0,0 +1,387 @@ +import { strict as assert } from "node:assert"; +import { Schema } from "@antelopejs/interface-database"; +import { + EncryptionModifier, + Encrypted, + Field, + HashModifier, + Hashed, + Index, + LocalizationModifier, + Localized, + RegisterSchema, + RegisterTable, + Relation, + Table, +} from "@antelopejs/interface-database-decorators"; + +/** The schema ids of the Schemas journeys, unique to them. */ +export const SHOP = "schemas-journeys-shop"; +export const VAULT = "schemas-journeys-vault"; +export const LINKS = "schemas-journeys-links"; +export const DEMO = "schemas-journeys-demo"; +export const METRICS = "schemas-journeys-metrics"; +export const QUIRKS = "schemas-journeys-quirks"; +export const HOLLOW = "schemas-journeys-hollow"; +const REGIONS = ["eu", "us"]; +const TENANTS = ["tenant-10", "tenant-2", "tenant-1"]; +export const CUSTOMERS_PER_REGION = 3; +export const ORDERS_PER_REGION = 4; +const READINGS = 25; +const SECRET_KEY = "verify-secret-key-0123456789abcd"; + +@RegisterTable("customers", SHOP) +class SchemasJourneysCustomer extends Table { + declare _id: string; + @Index() declare email: string; + declare company: string; + declare credit_limit: number; + declare vip: boolean; +} + +@RegisterTable("products", SHOP) +class SchemasJourneysProduct extends Table { + declare _id: string; + @Index() declare name: string; + declare price: number; + declare tags: string[]; +} + +@RegisterTable("orders", SHOP) +class SchemasJourneysOrder extends Table { + declare _id: string; + @Index() declare number: string; + @Index() + @Relation({ to: () => SchemasJourneysCustomer }) + declare customer_id: string; + @Index({ group: "status_created" }) declare status: string; + declare channel: string; + declare total: number; + declare currency: string; + declare coupon_id: string | null; + declare shipping: Record; + @Index({ group: "status_created" }) declare created_at: Date; +} + +@RegisterTable("order_items", SHOP) +class SchemasJourneysOrderItem extends Table { + declare _id: string; + @Index() + @Relation({ to: () => SchemasJourneysOrder }) + declare order_id: string; + @Relation({ to: () => SchemasJourneysProduct }) declare product_id: string; + declare quantity: number; + declare unit_price: number; +} + +@RegisterTable("accounts", VAULT) +class SchemasJourneysAccount extends Table.with( + HashModifier, + EncryptionModifier, + LocalizationModifier, +) { + @Field("string") declare _id: string; + @Index() @Field("string") declare handle: string; + @Hashed() @Field("string") declare password: string; + @Encrypted({ secretKey: SECRET_KEY }) + @Field("string") + declare card_number: string; + @Localized({ fallbackLocale: "en" }) + @Field("string") + declare display_name: string; +} + +@RegisterTable("parents_registry", VAULT) +class SchemasJourneysParentsRegistry extends Table { + @Field("string") declare _id: string; + @Field("string") declare label: string; +} + +@RegisterTable("wide_records", VAULT) +class SchemasJourneysWideRecord extends Table { + @Field("string") declare _id: string; + @Relation({ to: () => SchemasJourneysParentsRegistry }) + declare registry_id: string; + @Field("string") declare c01: string; + @Field("string") declare c02: string; + @Field("string") declare c03: string; + @Field("string") declare c04: string; + @Field("string") declare c05: string; + @Field("string") declare c06: string; + @Field("string") declare c07: string; + @Field("string") declare c08: string; + @Field("string") declare c09: string; + @Field("string") declare c10: string; + @Field("string") declare c11: string; + @Field("string") declare c12: string; + @Field("string") declare c13: string; + @Field("string") declare c14: string; + @Field("string") declare tail_marker: string; +} + +@RegisterTable("customer_refs", LINKS) +class SchemasJourneysCustomerRef extends Table { + @Field("string") declare _id: string; + @Relation({ to: () => SchemasJourneysCustomer }) declare customer_id: string; +} + +@RegisterTable("tags", DEMO) +class SchemasJourneysTag extends Table { + declare _id: string; + @Index() declare name: string; +} + +@RegisterTable("posts", DEMO) +class SchemasJourneysPost extends Table { + declare _id: string; + @Index() declare title: string; + @Index() declare author: string; + declare views: number; + @Relation({ to: () => SchemasJourneysTag, many: true }) + declare tag_ids: string[]; +} + +@RegisterTable("readings", METRICS) +class SchemasJourneysReading extends Table { + @Field("string") declare _id: string; + @Index() @Field("number") declare seq: number; + @Field("string") declare band: string; + @Field("number") declare value: number; +} + +@RegisterTable("empty_log", METRICS) +class SchemasJourneysEmptyLog extends Table { + @Field("string") declare _id: string; + @Field("string") declare message: string; +} + +@RegisterTable("members", QUIRKS) +class SchemasJourneysMember extends Table { + @Field("string") declare _id: string; +} + +/** Keeps the decorated classes referenced: the decorator registers them. */ +const TABLES = [ + SchemasJourneysCustomer, + SchemasJourneysProduct, + SchemasJourneysOrder, + SchemasJourneysOrderItem, + SchemasJourneysAccount, + SchemasJourneysParentsRegistry, + SchemasJourneysWideRecord, + SchemasJourneysCustomerRef, + SchemasJourneysTag, + SchemasJourneysPost, + SchemasJourneysReading, + SchemasJourneysEmptyLog, + SchemasJourneysMember, +]; + +new Schema(HOLLOW, {}); + +function schema(id: string) { + const found = Schema.get(id); + assert.ok(found, `${id} is registered`); + return found; +} + +const PRODUCTS = [ + ["sku_desk", "Standing desk", 640], + ["sku_chair", "Task chair", 320], + ["sku_lamp", "Desk lamp", 48], + ["sku_monitor", "27-inch monitor", 289], + ["sku_keyboard", "Mechanical keyboard", 129], + ["sku_dock", "USB-C dock", 179], +] as const; + +function products(region?: string) { + return PRODUCTS.map(([sku, name, price], index) => ({ + _id: region ? `${region}_${sku}` : sku, + name, + price, + tags: index % 2 === 0 ? ["office", "bestseller"] : ["office"], + })); +} + +async function seedShop(): Promise { + const shop = schema(SHOP); + for (const region of REGIONS) { + await shop + .createInstance(region) + .run() + .catch(() => undefined); + const tables = shop.instance(region); + await tables + .table("customers") + .insert( + Array.from({ length: CUSTOMERS_PER_REGION }, (_, index) => ({ + _id: `${region}_cus_${index}`, + email: `buyer${index}@${region}.test`, + company: `Company ${index}`, + credit_limit: 1000 + index * 500, + vip: index === 0, + })), + ) + .run(); + await tables.table("products").insert(products(region)).run(); + await tables + .table("orders") + .insert( + Array.from({ length: ORDERS_PER_REGION }, (_, index) => ({ + _id: `${region}_ord_${index}`, + number: `#${10400 + index}`, + customer_id: `${region}_cus_${index % CUSTOMERS_PER_REGION}`, + status: index % 2 === 0 ? "paid" : "pending", + channel: "web", + total: 50 + index, + currency: region === "eu" ? "EUR" : "USD", + coupon_id: index === 0 ? "cpn_AUTUMN10" : null, + shipping: { carrier: "DHL", eta: "2026-11-20" }, + created_at: new Date(Date.UTC(2026, 10, 1 + index)), + })), + ) + .run(); + await tables + .table("order_items") + .insert( + Array.from({ length: ORDERS_PER_REGION * 2 }, (_, index) => ({ + _id: `${region}_itm_${index}`, + order_id: `${region}_ord_${Math.floor(index / 2)}`, + product_id: `${region}_${PRODUCTS[index % PRODUCTS.length]?.[0]}`, + quantity: 1 + (index % 3), + unit_price: 48, + })), + ) + .run(); + } + await shop.instance().table("products").insert(products()).run(); +} + +/** + * Registers the schemas of the Schemas journeys and fills them: a shop with an `eu` and a `us` instance, a vault + * with modifiers and a seventeen-column table, links with three tenants and a relation to the shop, demo posts, + * metrics readings, a `constructor` column and a schema without a table. + */ +export async function seed(): Promise { + assert.equal(TABLES.length, 13); + for (const id of [SHOP, VAULT, LINKS, DEMO, METRICS, QUIRKS]) + await RegisterSchema(id); + await seedShop(); + const vault = schema(VAULT).instance(); + await vault + .table("accounts") + .insert( + ["ada", "bob"].map((handle) => ({ + _id: `acc_${handle}`, + handle, + password: "hashed", + card_number: "sealed", + display_name: handle, + })), + ) + .run(); + await vault + .table("parents_registry") + .insert([{ _id: "reg_1", label: "registry one" }]) + .run(); + await vault + .table("wide_records") + .insert([ + { _id: "wide_1", registry_id: "reg_1", c01: "a", tail_marker: "tail" }, + ]) + .run(); + for (const tenant of TENANTS) + await schema(LINKS) + .createInstance(tenant) + .run() + .catch(() => undefined); + await schema(DEMO) + .instance() + .table("posts") + .insert( + ["First", "Second", "Third"].map((title, index) => ({ + _id: `post_${index}`, + title: `${title} post`, + author: index === 1 ? "bob" : "alice", + views: index * 10, + tag_ids: [], + })), + ) + .run(); + await schema(METRICS) + .instance() + .table("readings") + .insert( + Array.from({ length: READINGS }, (_, index) => ({ + _id: `r_${index + 1}`, + seq: index + 1, + band: `band-${(index % 5) + 1}`, + value: index * 7, + })), + ) + .run(); + await schema(QUIRKS) + .instance() + .table("members") + .insert([ + Object.fromEntries([ + ["_id", "member_1"], + ["constructor", "ctor value"], + ["note", "plain column"], + ]), + ]) + .run(); +} + +/** Removes what {@link seed} stored. */ +export async function cleanUp(): Promise { + for (const region of REGIONS) + await schema(SHOP).destroyInstance(region).run(); + for (const tenant of TENANTS) + await schema(LINKS).destroyInstance(tenant).run(); + const tables: [string, string][] = [ + [SHOP, "products"], + [VAULT, "accounts"], + [VAULT, "parents_registry"], + [VAULT, "wide_records"], + [DEMO, "posts"], + [METRICS, "readings"], + [QUIRKS, "members"], + ]; + for (const [id, table] of tables) + await schema(id).instance().table(table).delete().run(); +} + +const figures = (rows: number, columns: number, indexes: number) => ({ + rows, + columns, + indexes, + relations: [], + modifiers: [], +}); + +/** What the source route answers for ten tables of {@link seed}: rows in the default instance, column, index and relation counts, the tables each points to and its modifier names. */ +export const EXPECTED_FIGURES = [ + [`${SHOP}::customers`, figures(0, 5, 1)], + [`${SHOP}::products`, figures(6, 4, 1)], + [`${SHOP}::orders`, { ...figures(0, 10, 3), relations: ["customers"] }], + [ + `${SHOP}::order_items`, + { ...figures(0, 5, 1), relations: ["orders", "products"] }, + ], + [ + `${VAULT}::accounts`, + { ...figures(2, 5, 1), modifiers: ["Hashed", "Encrypted", "Localized"] }, + ], + [ + `${VAULT}::wide_records`, + { ...figures(1, 17, 0), relations: ["parents_registry"] }, + ], + [ + `${LINKS}::customer_refs`, + { ...figures(0, 2, 0), relations: [`${SHOP}.customers`] }, + ], + [`${DEMO}::posts`, { ...figures(3, 5, 2), relations: ["tags"] }], + [`${METRICS}::readings`, figures(READINGS, 4, 1)], + [`${METRICS}::empty_log`, figures(0, 2, 0)], +] as const; diff --git a/src/test/schemas.journeys.test.ts b/src/test/schemas.journeys.test.ts new file mode 100644 index 0000000..870dfb4 --- /dev/null +++ b/src/test/schemas.journeys.test.ts @@ -0,0 +1,505 @@ +import { strict as assert } from "node:assert"; +import type { JsonValue } from "../types/json"; +import { call } from "./helpers/http"; +import { at, itemsAt, keysAt, textAt } from "./helpers/jsonAt"; +import { + CUSTOMERS_PER_REGION, + DEMO, + EXPECTED_FIGURES, + HOLLOW, + LINKS, + METRICS, + ORDERS_PER_REGION, + QUIRKS, + SHOP, + VAULT, + cleanUp, + seed, +} from "./helpers/schemasPlayground"; +import { + createMemberSession, + createOwnerSession, + type OwnerSession, +} from "./ownerSession"; + +interface Listing { + status: number; + rows: JsonValue[]; + total: JsonValue; + all: JsonValue; +} + +interface Bar { + scope?: string; + instance?: string; + q?: string; + has?: string; +} + +let owner: OwnerSession; +let member: OwnerSession; + +const ids = (rows: JsonValue[]): string[] => + rows.map((row) => textAt(row, "id")); +const rowOf = (rows: JsonValue[], id: string): JsonValue => + rows.find((row) => textAt(row, "id") === id) ?? null; + +/** The tables the Schemas page lists for a filter bar state, as its table view asks for them. */ +async function source(bar: Bar = {}): Promise { + const query = new URLSearchParams(); + for (const [key, value] of Object.entries(bar)) + if (value) query.set(`filter_${key}`, `is:${value}`); + const search = query.size > 0 ? `?${query.toString()}` : ""; + const answer = await call(owner, "GET", `/database/tables/source${search}`); + return { + status: answer.status, + rows: itemsAt(answer.body, "results"), + total: at(answer.body, "total"), + all: at(answer.body, "all"), + }; +} + +async function listed(bar: Bar): Promise { + return ids((await source(bar)).rows).sort(); +} + +async function schemas(): Promise { + const answer = await call(owner, "GET", "/database/schemas"); + return itemsAt(answer.body, "schemas"); +} + +function schemaOf(all: JsonValue[], schemaId: string): JsonValue { + return all.find((entry) => textAt(entry, "id") === schemaId) ?? null; +} + +function tableOf(all: JsonValue[], schemaId: string, table: string): JsonValue { + const tables = itemsAt(schemaOf(all, schemaId), "tables"); + return tables.find((entry) => textAt(entry, "name") === table) ?? null; +} + +function instances(query: string) { + return call(owner, "GET", `/database/tables/instances?${query}`); +} + +function singleRow(query: string) { + return call(owner, "GET", `/database/tables/source/row${query}`); +} + +async function tableCounts(): Promise { + const listing = await source(); + const registered = (await schemas()).reduce( + (sum, entry) => sum + itemsAt(entry, "tables").length, + 0, + ); + assert.equal(listing.status, 200); + assert.equal(listing.total, listing.rows.length, "total is the rows listed"); + assert.deepEqual( + [listing.all, listing.rows.length], + [registered, registered], + "all counting one schema's tables would not match the schemas route", + ); + const listedIds = ids(listing.rows); + assert.equal(new Set(listedIds).size, listedIds.length, "ids are unique"); + assert.ok( + listedIds.every((id) => id.split("::").length === 2), + "every id is schema::table", + ); + assert.ok( + listing.rows.every( + (row) => + textAt(row, "id") === + `${textAt(row, "schema")}::${textAt(row, "name")}`, + ), + "every row names its schema and table", + ); + for (const [id, expected] of EXPECTED_FIGURES) { + const row = rowOf(listing.rows, id); + assert.deepEqual( + { + rows: at(row, "elementCount"), + columns: at(row, "columnCount"), + indexes: at(row, "indexCount"), + relations: at(row, "relations"), + modifiers: at(row, "modifiers"), + }, + expected, + `${id} holds its figures`, + ); + } +} + +async function filters(): Promise { + const everything = await source(); + const shop = await source({ scope: SHOP }); + const none = await source({ scope: "nope" }); + const byName = await listed({ scope: SHOP, q: "ORDER" }); + const orderTables = [`${SHOP}::order_items`, `${SHOP}::orders`]; + assert.deepEqual( + [everything.total, everything.rows.length], + [everything.all, everything.all], + "unfiltered lists every table", + ); + assert.deepEqual( + ids(shop.rows).sort(), + [`${SHOP}::customers`, ...orderTables, `${SHOP}::products`], + "a schema lists its own tables only", + ); + assert.deepEqual( + [shop.total, shop.all], + [4, everything.all], + "the schema filter leaves all as the registered count", + ); + assert.deepEqual( + [none.total, none.rows.length, none.all], + [0, 0, everything.all], + "an unknown schema lists nothing", + ); + assert.deepEqual(byName, orderTables, "a name matches in any case"); + assert.deepEqual( + await listed({ scope: SHOP, q: " order " }), + byName, + "a search is trimmed", + ); + assert.deepEqual( + await listed({ scope: SHOP, q: "email" }), + [`${SHOP}::customers`], + "a column name finds its table", + ); + assert.deepEqual( + await listed({ scope: SHOP, q: "customer" }), + [`${SHOP}::customers`, `${SHOP}::orders`], + "a search names the table or a column", + ); + assert.deepEqual( + await listed({ scope: SHOP, q: "customer_id" }), + [`${SHOP}::orders`], + "a column name is not a table name", + ); + assert.deepEqual( + await listed({ q: "tail_marker" }), + [`${VAULT}::wide_records`], + "a search of the first twelve columns only would miss the seventeenth", + ); +} + +async function structureFilters(): Promise { + const orderTables = [`${SHOP}::order_items`, `${SHOP}::orders`]; + const related = await listed({ scope: SHOP, has: "relations" }); + assert.deepEqual(related, orderTables, "relations keeps the related tables"); + assert.deepEqual( + await listed({ scope: VAULT, has: "modifiers" }), + [`${VAULT}::accounts`], + "modifiers keeps the tables with hashed, localized or encrypted columns", + ); + assert.equal( + (await source({ scope: VAULT, has: "relations,modifiers" })).total, + 0, + "both structure flags must hold", + ); + assert.deepEqual( + await listed({ scope: SHOP, has: "relations, bogus" }), + related, + "an unknown flag is ignored among known ones", + ); + assert.equal( + (await source({ scope: SHOP, has: "bogus" })).total, + 4, + "only an unknown flag filters nothing", + ); + assert.deepEqual( + await listed({ scope: SHOP, has: "empty" }), + [`${SHOP}::customers`, ...orderTables], + "empty keeps the tables without a row in the default instance", + ); + assert.deepEqual( + await listed({ scope: SHOP, q: "order", has: "relations,empty" }), + orderTables, + "search, relations and empty combine", + ); + assert.deepEqual( + await listed({ scope: VAULT, has: "modifiers,empty" }), + [], + "modifiers and empty combine: accounts holds two rows", + ); +} + +async function sourceFilters(): Promise { + await filters(); + await structureFilters(); +} + +async function shopCounts(instance?: string) { + const { rows } = await source({ scope: SHOP, instance }); + return Object.fromEntries( + rows.map((row) => [textAt(row, "name"), at(row, "elementCount")]), + ); +} + +async function instanceCounts(): Promise { + const perRegion = { + customers: CUSTOMERS_PER_REGION, + products: 6, + orders: ORDERS_PER_REGION, + order_items: ORDERS_PER_REGION * 2, + }; + assert.deepEqual( + await shopCounts(), + { customers: 0, products: 6, orders: 0, order_items: 0 }, + "no instance counts the default one", + ); + assert.deepEqual(await shopCounts("eu"), perRegion, "eu counts its rows"); + assert.deepEqual(await shopCounts("us"), perRegion, "us counts its rows"); + assert.deepEqual( + await shopCounts("all"), + { + customers: CUSTOMERS_PER_REGION * 2, + products: 18, + orders: ORDERS_PER_REGION * 2, + order_items: ORDERS_PER_REGION * 4, + }, + "all counts every instance at once", + ); + assert.ok( + Object.values(await shopCounts("atlantis")).every((count) => count === 0), + "an instance that does not exist counts nothing", + ); + const emptyIn = async (instance: string) => + (await source({ scope: SHOP, instance, has: "empty" })).total; + assert.deepEqual( + [await emptyIn("eu"), await emptyIn("all")], + [0, 0], + "empty judged in the default instance would keep three shop tables", + ); + assert.deepEqual( + await listed({ scope: METRICS, instance: "eu", has: "empty" }), + [`${METRICS}::empty_log`, `${METRICS}::readings`], + "empty in eu keeps both metrics tables", + ); + const row = await singleRow(`?id=${SHOP}::orders`); + assert.deepEqual( + [ + at(row.body, "elementCount"), + at(row.body, "id"), + at(row.body, "columnCount"), + ], + [0, `${SHOP}::orders`, 10], + "a single row is counted in the default instance", + ); +} + +async function instanceSearch(): Promise { + const named = async (query: string) => + at((await instances(query)).body, "instances"); + assert.deepEqual( + (await instances(`schema=${SHOP}`)).body, + { instances: ["eu", "us"], total: 2 }, + "shop has eu and us", + ); + assert.deepEqual( + [ + await named(`schema=${SHOP}&search=E`), + await named(`schema=${SHOP}&search=S`), + ], + [["eu"], ["us"]], + "a search matches part of a name in any case", + ); + assert.deepEqual( + (await instances(`schema=${SHOP}&search=zzz`)).body, + { instances: [], total: 0 }, + "a search with no match is empty", + ); + const tenants = ["tenant-1", "tenant-2", "tenant-10"]; + assert.deepEqual( + await named(`schema=${LINKS}`), + tenants, + "a sort by text would put tenant-10 before tenant-2", + ); + assert.deepEqual( + (await instances(`schema=${LINKS}&limit=2`)).body, + { instances: tenants.slice(0, 2), total: 3 }, + "the limit cuts the list and total says how many matched", + ); + assert.deepEqual( + (await instances(`schema=${LINKS}&limit=0`)).body, + { instances: tenants.slice(0, 1), total: 3 }, + "a limit under 1 is read as 1", + ); + assert.deepEqual( + (await instances(`schema=${LINKS}&limit=abc`)).body, + { instances: tenants, total: 3 }, + "an unreadable limit falls back to the default of 100", + ); + const ceiling = await instances(`schema=${LINKS}&limit=9999`); + assert.deepEqual( + [ceiling.status, at(ceiling.body, "total")], + [200, 3], + "a large limit is clamped, not refused", + ); + assert.deepEqual( + (await instances(`schema=${METRICS}`)).body, + { instances: [], total: 0 }, + "a schema without named instances lists none", + ); + assert.equal((await instances("schema=nope")).status, 404, "unknown: 404"); + assert.equal((await instances("")).status, 400, "missing schema: 400"); +} + +async function singleTable(): Promise { + const found = await singleRow(`?id=${VAULT}::wide_records`); + assert.deepEqual( + ["schema", "name", "elementCount", "columnCount", "indexCount"].map((key) => + at(found.body, key), + ), + [VAULT, "wide_records", 1, 17, 0], + "the row holds the table's figures", + ); + assert.deepEqual( + at(found.body, "relations"), + ["parents_registry"], + "a relation inside the schema is named without it", + ); + const related = await singleRow(`?id=${LINKS}::customer_refs`); + assert.deepEqual( + at(related.body, "relations"), + [`${SHOP}.customers`], + "a relation to another schema is named with it", + ); + const upper = await singleRow(`?id=${VAULT.toUpperCase()}::wide_records`); + assert.equal(upper.status, 404, "a case-insensitive lookup would find it"); + const unknown = await singleRow(`?id=${VAULT}::nothing`); + assert.equal(unknown.status, 404, "an unknown id is refused 404"); + assert.equal((await singleRow("")).status, 400, "a missing id: 400"); + assert.equal((await singleRow("?id=")).status, 400, "an empty id: 400"); +} + +async function inference(): Promise { + const all = await schemas(); + const fieldsOf = (schemaId: string, table: string) => + at(tableOf(all, schemaId, table), "fields"); + const kinds = (fields: JsonValue) => + keysAt(fields).map((name) => `${name}:${textAt(fields, name, "kind")}`); + const orders = fieldsOf(SHOP, "orders"); + const customers = fieldsOf(SHOP, "customers"); + assert.deepEqual( + kinds(orders), + [ + "_id:string", + "number:string", + "customer_id:string", + "status:string", + "created_at:date", + "channel:string", + "total:number", + "currency:string", + "coupon_id:union", + "shipping:object", + ], + "declared columns come first, sampled ones after, in order", + ); + assert.deepEqual( + at(orders, "coupon_id", "members"), + [{ kind: "string" }, { kind: "null" }], + "a column holding null in some rows is a union of its type and null", + ); + assert.deepEqual( + kinds(customers), + [ + "_id:string", + "email:string", + "company:string", + "credit_limit:number", + "vip:boolean", + ], + "columns no decorator names are typed by their rows", + ); + assert.deepEqual( + at(fieldsOf(SHOP, "products"), "tags"), + { kind: "array", element: { kind: "string" } }, + "an array is typed by its elements", + ); + assert.deepEqual( + at(fieldsOf(DEMO, "posts"), "tag_ids"), + { kind: "array" }, + "an array of no element stays untyped", + ); + assert.deepEqual( + keysAt(fieldsOf(SHOP, "order_items")), + ["_id", "order_id", "product_id", "quantity", "unit_price"], + "a table whose rows are all in named instances is sampled from them", + ); + assert.ok( + ![...keysAt(orders), ...keysAt(customers)].includes("_instance"), + "the instance tag of the store is not a column", + ); + assert.deepEqual( + keysAt(fieldsOf(QUIRKS, "members")), + ["_id", "constructor", "note"], + "a lookup through Object.prototype would drop the constructor column", + ); + const shop = schemaOf(all, SHOP); + assert.deepEqual(at(shop, "instances"), ["eu", "us"], "its instances"); + assert.deepEqual( + at(shop, "stats"), + { tableCount: 4, elementCount: 6, instanceCount: 3 }, + "a schema reports its stats", + ); + const hollow = schemaOf(all, HOLLOW); + assert.notEqual(hollow, null, "a schema without a table is listed"); + assert.deepEqual( + [itemsAt(hollow, "tables").length, at(hollow, "stats", "tableCount")], + [0, 0], + "with no table", + ); +} + +async function ownerOnly(): Promise { + const paths = [ + "/database/schemas", + "/database/tables/source", + `/database/tables/source/row?id=${SHOP}::orders`, + `/database/tables/instances?schema=${SHOP}`, + ]; + for (const path of paths) { + const anonymous = await call(null, "GET", path); + const reader = await call(member, "GET", path); + const allowed = await call(owner, "GET", path); + assert.equal(anonymous.status, 401, `${path} refuses nobody 401`); + assert.equal(reader.status, 403, `${path} refuses a member 403`); + assert.equal(allowed.status, 200, `${path} answers the owner`); + } +} + +describe("[integration] schemas journeys", function () { + this.timeout(30_000); + + before(async () => { + owner = await createOwnerSession("schemas-journeys-owner@test.local"); + member = await createMemberSession("schemas-journeys-member@test.local"); + await seed(); + }); + after(async () => { + await cleanUp(); + await owner.remove(); + await member.remove(); + }); + + it( + "the-source-counts-rows-columns-indexes-relations-and-modifiers-of-each-table", + tableCounts, + ); + it( + "schema-instance-search-and-structure-filters-narrow-the-source-and-combine", + sourceFilters, + ); + it( + "rows-are-counted-in-the-picked-instance-default-named-or-all", + instanceCounts, + ); + it( + "the-instances-route-searches-sorts-and-limits-the-named-instances-of-a-schema", + instanceSearch, + ); + it("a-table-is-read-by-its-schema-and-name-id", singleTable); + it("columns-are-declared-in-code-and-inferred-from-sampled-rows", inference); + it("the-tables-and-schemas-routes-answer-the-platform-owner-only", ownerOnly); +}); From a62db4d28bd3e3edf80161f8127e0a728cba4c70 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 08:44:27 +0000 Subject: [PATCH 04/12] test(extending): port the HTTP journeys to integration tests The introspection and table-watch journeys run in src/test/extending.journeys.test.ts, the table watch through a procedure of the dms-automation module the harness loads. The playground no longer loads dms-automation on a flag, which only the table-watch journey set. The silent no-op without dms-automation stays a journey: the harness always loads the module. --- .../verify-dms-database/features/README.md | 2 +- .../verify-dms-database/features/extending.md | 23 +- e2e/journeys/extending.mjs | 36 +- e2e/journeys/parts/query-wire.mjs | 15 - e2e/journeys/parts/table-watch.mjs | 98 ------ e2e/playground/antelope.config.ts | 14 - src/test/extending.journeys.test.ts | 317 ++++++++++++++++++ 7 files changed, 333 insertions(+), 172 deletions(-) delete mode 100644 e2e/journeys/parts/table-watch.mjs create mode 100644 src/test/extending.journeys.test.ts diff --git a/.agents/skills/verify-dms-database/features/README.md b/.agents/skills/verify-dms-database/features/README.md index 7a123a9..fd69ee5 100644 --- a/.agents/skills/verify-dms-database/features/README.md +++ b/.agents/skills/verify-dms-database/features/README.md @@ -15,7 +15,7 @@ One file per feature. `covers:` lists the source globs it owns, `docs:` the page | [query](query.md) | # Query | a-query-returns-its-rows-in-the-order-it-asks, an-instance-and-every-instance-are-targeted, a-failed-query-says-what-failed-and-offers-the-nearest-name, the-insert-chips-add-their-operation, ctrl-space-completes-schemas-and-tables-from-the-workspace, an-empty-console-offers-examples-built-on-your-own-tables, results-over-1000-rows-are-cut-at-1000, the-table-view-shows-every-returned-row, an-export-of-uneven-rows-keeps-every-key-in-csv-and-json, csv-quotes-a-comma-a-quote-and-a-line-break-so-the-cell-reads-back, format-strips-trailing-spaces-and-blank-lines, ctrl-space-inside-a-filter-completes-the-columns-of-the-table, the-chart-plots-the-first-numeric-column-with-pickers-for-both-axes, open-in-data-browser-opens-the-target-table-or-the-row, copy-as-json-puts-the-returned-rows-on-the-clipboard, a-link-opens-the-console-on-the-table-in-the-instance-it-names | | [guard](guard.md) | # Guard | a-delete-names-its-operation-target-and-rows-and-waits-for-the-table-name, every-write-names-its-operation-and-counts-the-rows-it-would-touch, confirming-a-single-row-update-needs-the-table-name-as-the-docs-say, a-confirmed-write-acts-on-the-data-of-that-moment, a-read-query-runs-straight-away | | [library](library.md) | # Library | history-keeps-your-last-500-runs-newest-first, history-records-failures-and-writes-with-their-status, history-is-searchable-and-clearing-it-keeps-the-saved-queries, a-saved-query-needs-a-name-and-can-be-edited-and-deleted, a-shared-query-reaches-the-team-and-only-its-author-changes-it, history-belongs-to-its-user-and-a-link-restores-a-run, the-library-survives-a-backend-restart, history-groups-runs-by-day-with-yesterday-and-older-dates, a-history-row-without-a-status-reads-as-ok | -| [extending](extending.md) | # Extending | a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers, deep-links-open-the-documented-pages-on-the-table, without-the-automation-module-the-trigger-registration-is-a-silent-no-op | +| [extending](extending.md) | # Extending | deep-links-open-the-documented-pages-on-the-table, without-the-automation-module-the-trigger-registration-is-a-silent-no-op | | [external](external.md) | # External | an-external-database-is-picked-browsed-edited-and-left, an-external-database-refuses-what-it-cannot-serve-with-sentences | | [package](package.md) | # Package | none: `src/test/package.test.ts` checks the tarball, the locales and the ranges | diff --git a/.agents/skills/verify-dms-database/features/extending.md b/.agents/skills/verify-dms-database/features/extending.md index 74c0402..21656b7 100644 --- a/.agents/skills/verify-dms-database/features/extending.md +++ b/.agents/skills/verify-dms-database/features/extending.md @@ -16,10 +16,15 @@ What the module picks up from the rest of the project (registered schemas, their ## Sub-features -- `a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers`: introspection of declared tables, instances and modifiers. - `deep-links-open-the-documented-pages-on-the-table`: the four links of the Link to the console table, with `instance=` and `instance=all`. - `without-the-automation-module-the-trigger-registration-is-a-silent-no-op`: a quiet start without `@antelopejs/dms-automation`. -- `the-table-watch-hands-a-procedure-each-insert-update-and-delete`: with the automation module loaded (`VERIFY_DATABASE_AUTOMATION`, on a `dev` backend), a procedure on a Table watch runs on each write of the default instance and not on a write of another instance. + +## Integration tests + +`pnpm test` runs these in `src/test/extending.journeys.test.ts`, one `it` per id, so `-g ` selects one. + +- `a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers`: introspection of declared tables, instances and modifiers. +- `the-table-watch-hands-a-procedure-each-insert-update-and-delete`: with the automation module loaded, a procedure on a Table watch runs on each write of the default instance and not on a write of another instance. ## How to get to it (user POV) @@ -34,18 +39,18 @@ pnpm e2e:run specs/extending.spec.ts ## Gotchas - The Schemas, Diagram, Data and Query features drive the pages behind the links in depth; this feature checks that each link lands on the right table. -- The table-watch journey adds a module to the playground, which a production backend refuses (its build fixes the module set), so it asks for a `dev` backend (`backend: "dev"`). +- The playground runs without `@antelopejs/dms-automation`, and the `pnpm test` harness always loads it, so the silent no-op stays a journey and the table watch runs in the integration test. ## Coverage | Documented behaviour | Journey and check | |---|---| -| Registered schemas appear with tables, columns, indexes, relations | first journey | -| Each instance is listed in the pickers | first journey (instances API), Data feature (pickers) | -| Hashed, localized, encrypted columns carry a modifier badge | first journey (API), Schemas feature (badge) | -| Deep links with `instance=` and `instance=all` | second journey | -| Without the automation module the registration is a silent no-op | third journey | -| Table watch trigger: config, output (type, old and new rows without the instance tag) | fourth journey | +| Registered schemas appear with tables, columns, indexes, relations | `a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers` (integration test) | +| Each instance is listed in the pickers | `a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers` (integration test, instances API), Data feature (pickers) | +| Hashed, localized, encrypted columns carry a modifier badge | `a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers` (integration test, API), Schemas feature (badge) | +| Deep links with `instance=` and `instance=all` | `deep-links-open-the-documented-pages-on-the-table` | +| Without the automation module the registration is a silent no-op | `without-the-automation-module-the-trigger-registration-is-a-silent-no-op` | +| Table watch trigger: config, output (type, old and new rows without the instance tag) | `the-table-watch-hands-a-procedure-each-insert-update-and-delete` (integration test) | | Table watch trigger: one node, reconnect once | Not driven: the run has one backend, and a journey cannot break its change stream | | On a standalone MongoDB activation fails with "$changeStream is only supported on replica sets" | Not driven: the run's `mongod` is a replica set | | On a collection that records no pre-images activation fails with the store's `collMod` sentence | Not driven: the playground's collections are created by the driver, with pre-images; `src/test/table-watch-feed.test.ts` checks it | diff --git a/e2e/journeys/extending.mjs b/e2e/journeys/extending.mjs index d3e0da0..2084a2c 100644 --- a/e2e/journeys/extending.mjs +++ b/e2e/journeys/extending.mjs @@ -1,42 +1,9 @@ -import { check, db, isRow, list, pick, text } from "../database.mjs"; -import { tableWatchJourney } from "./parts/table-watch.mjs"; +import { check, db } from "../database.mjs"; /** @typedef {import("../database.mjs").Ctx} Ctx */ -/** - * @param {unknown} schemas The schemas answer - * @param {string} schema A schema id - * @param {string} table A table name - * @returns {unknown} The table's summary - */ -function tableOf(schemas, schema, table) { - const found = list(schemas, "schemas").find((row) => text(row, "id") === schema); - return list(found, "tables").find((row) => text(row, "name") === table); -} - /** What a module gets by registering a schema, and the links other pages use. */ export const journeys = [ - { - id: "a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers", - title: "a schema registered with RegisterSchema lists its tables with their columns, indexes, relations and modifiers, and a table with named instances lists them", - entryPoint: "GET /api/database/schemas, /tables/instances", - async run(/** @type {Ctx} */ ctx) { - const schemas = await db(ctx, "schemas", "GET", "/schemas"); - const orders = tableOf(schemas.body, "shop", "orders"); - const accounts = tableOf(schemas.body, "vault", "accounts"); - const instances = await db(ctx, "shop instances", "GET", "/tables/instances?schema=shop"); - const none = await db(ctx, "demo instances", "GET", "/tables/instances?schema=demo"); - const fields = pick(orders, "fields"); - await ctx.verify("the introspection", [ - check("orders has its declared columns", ["_id", "number", "customer_id", "status", "total", "created_at"].every((name) => isRow(fields) && name in fields), fields), - check("orders has the indexes number, customer_id and the status_created group", JSON.stringify(Object.keys(pick(orders, "indexes") ?? {}).sort()) === JSON.stringify(["customer_id", "number", "status_created"]), pick(orders, "indexes")), - check("orders points to customers through customer_id", list(orders, "relations").some((relation) => text(relation, "fromField") === "customer_id" && text(relation, "toTable") === "customers"), pick(orders, "relations")), - check("accounts carries hashed, encrypted and localized modifiers on their fields", JSON.stringify(pick(accounts, "modifiers")) === JSON.stringify({ password: ["HashModifier"], card_number: ["EncryptionModifier"], display_name: ["LocalizationModifier"] }), pick(accounts, "modifiers")), - check("shop lists its eu and us instances", JSON.stringify(pick(instances.body, "instances")) === JSON.stringify(["eu", "us"]), instances.body), - check("a schema without named instances lists none", JSON.stringify(pick(none.body, "instances")) === "[]", none.body), - ]); - }, - }, { id: "deep-links-open-the-documented-pages-on-the-table", title: "each link of the Link to the console table opens its page on the table: the inspector, the diagram focused on it, the data browser (default instance, a named instance, all instances) and the query console", @@ -77,5 +44,4 @@ export const journeys = [ ]); }, }, - tableWatchJourney, ]; diff --git a/e2e/journeys/parts/query-wire.mjs b/e2e/journeys/parts/query-wire.mjs index 2a2660f..d9a5041 100644 --- a/e2e/journeys/parts/query-wire.mjs +++ b/e2e/journeys/parts/query-wire.mjs @@ -109,19 +109,4 @@ export function queryDelete(ctx, schema, table, id, instance) { return runQuery(ctx, `delete ${table} ${id} by query`, query, `schemas.${schema}.instance(${instance ? JSON.stringify(instance) : ""}).table("${table}").get("${id}").delete()`); } -/** - * Inserts rows through the query console's route. - * - * @param {Ctx} ctx The journey - * @param {string} schema The schema - * @param {string} table The table - * @param {Row[]} rows The rows - * @param {string} [instance] The instance - * @returns {Promise} The answer - */ -export function queryInsert(ctx, schema, table, rows, instance) { - const query = stagedTable(schema, table, instance).insert(rows); - return runQuery(ctx, `insert into ${table} by query`, query, `schemas.${schema}.instance(${instance ? JSON.stringify(instance) : ""}).table("${table}").insert(${JSON.stringify(rows)})`); -} - export { pick }; diff --git a/e2e/journeys/parts/table-watch.mjs b/e2e/journeys/parts/table-watch.mjs deleted file mode 100644 index 422a950..0000000 --- a/e2e/journeys/parts/table-watch.mjs +++ /dev/null @@ -1,98 +0,0 @@ -import { setTimeout as delay } from "node:timers/promises"; -import { check, db, isRow, list, parseJson, pick, show, text, withConfig } from "../../database.mjs"; -import { queryDelete, queryInsert } from "./query-wire.mjs"; - -/** - * @typedef {import("../../database.mjs").Ctx} Ctx - * @typedef {import("../../database.mjs").Answer} Answer - */ - -const AUTOMATION = "/api/automation"; -const ROW = { _id: "watch-1", name: "Watched lamp", price: 12, tags: ["office"] }; -const OTHER_INSTANCE_ROW = { _id: "watch-eu", name: "Lamp of eu", price: 9, tags: [] }; - -/** - * Calls the automation module's API as the platform owner. - * - * @param {Ctx} ctx The journey - * @param {string} label What the call does - * @param {string} method The HTTP method - * @param {string} path The path under `/api/automation` - * @param {unknown} [body] The JSON body - * @returns {Promise} The answer - */ -function automation(ctx, label, method, path, body) { - return ctx.api(label, { method, path: `${AUTOMATION}${path}`, body }); -} - -/** A procedure whose only node is a table watch on the default instance of shop.products. */ -const PROCEDURE = { - name: "Watch products", - description: "", - graph: { - nodes: [{ id: "watch", kind: "trigger", typeId: "database.table-watch", config: { schema: "shop", table: "products" }, position: { x: 0, y: 0 } }], - triggerEdges: [], - dataEdges: [], - }, -}; - -/** - * Reads the runs of a procedure until `count` are listed or 20 s pass, then 2 s more so a late extra run shows. - * - * @param {Ctx} ctx The journey - * @param {string} id The procedure id - * @param {number} count The runs expected - * @returns {Promise} The runs, oldest first - */ -async function runsOf(ctx, id, count) { - const read = async () => list((await automation(ctx, "the procedure's runs", "GET", `/procedures/${id}/runs`)).body).toReversed(); - for (let waited = 0; waited < 20_000; waited += 1_000) { - if ((await read()).length >= count) break; - await delay(1_000); - } - await delay(2_000); - return read(); -} - -/** - * @param {unknown} run A run of the runs list - * @param {Ctx} ctx The journey - * @returns {Promise<{ type: string, old: unknown, new: unknown }>} What the trigger handed the run - */ -async function payloadOf(run, ctx) { - const detail = await automation(ctx, "a run", "GET", `/runs/${text(run, "_id")}`); - const payload = parseJson(text(detail.body, "triggerPayload")); - return { type: text(payload, "type"), old: pick(payload, "old"), new: pick(payload, "new") }; -} - -/** The table watch trigger seen through a procedure of the automation module. */ -export const tableWatchJourney = { - id: "the-table-watch-hands-a-procedure-each-insert-update-and-delete", - title: "with @antelopejs/dms-automation loaded, an enabled procedure on a Table watch of shop.products runs once on an insert, an update and a delete of a row of the default instance, each run carrying the rows, and not on a row of the eu instance", - entryPoint: "POST /api/automation/procedures/import, PUT /procedures/:id/enabled, POST /api/database/query/execute, PUT /api/database/browse/edit, GET /procedures/:id/runs, /runs/:id", - backend: "dev", - async run(/** @type {Ctx} */ ctx) { - await withConfig(ctx, { VERIFY_DATABASE_AUTOMATION: "1" }, async () => { - const created = await automation(ctx, "import the procedure", "POST", "/procedures/import", { json: JSON.stringify(PROCEDURE) }); - const id = text(created.body, "_id"); - const enabled = await automation(ctx, "enable it", "PUT", `/procedures/${id}/enabled`, { enabled: true }); - await ctx.verify("the procedure is armed", [check("the import answers an id", id !== "", show(created.body)), check("enabling answers 200", enabled.status === 200, show(enabled.body))], { critical: true }); - await delay(3_000); - await queryInsert(ctx, "shop", "products", [OTHER_INSTANCE_ROW], "eu"); - await queryDelete(ctx, "shop", "products", OTHER_INSTANCE_ROW._id, "eu"); - const inserted = await queryInsert(ctx, "shop", "products", [ROW]); - const edited = await db(ctx, "rename the row in the data browser", "PUT", `/browse/edit?filter_schema=is:shop&filter_table=is:products&id=${ROW._id}&connection=own`, { body: { name: "Renamed lamp" } }); - const deleted = await queryDelete(ctx, "shop", "products", ROW._id); - await ctx.verify("the writes", [check("the insert answers 200", inserted.status === 200, show(inserted.body)), check("the edit answers 200", edited.status === 200, show(edited.body)), check("the delete answers 200", deleted.status === 200, show(deleted.body))]); - const payloads = await Promise.all((await runsOf(ctx, id, 3)).map((run) => payloadOf(run, ctx))); - const renamed = { ...ROW, name: "Renamed lamp" }; - await ctx.verify("one run per write of the default instance", [ - check("three runs, insert then update then delete", JSON.stringify(payloads.map((payload) => payload.type)) === JSON.stringify(["insert", "update", "delete"]), show(payloads)), - check("the insert carries the new row and no old one", JSON.stringify(payloads[0]) === JSON.stringify({ type: "insert", old: null, new: ROW }), show(payloads[0])), - check("the update carries the row before and after", JSON.stringify(payloads[1]) === JSON.stringify({ type: "update", old: ROW, new: renamed }), show(payloads[1])), - check("the delete carries the row it removed", JSON.stringify(payloads[2]) === JSON.stringify({ type: "delete", old: renamed, new: null }), show(payloads[2])), - check("no run carries the eu row", !payloads.some((payload) => [payload.old, payload.new].some((row) => isRow(row) && row._id === OTHER_INSTANCE_ROW._id)), show(payloads)), - ]); - }); - }, -}; diff --git a/e2e/playground/antelope.config.ts b/e2e/playground/antelope.config.ts index 0ac237d..4b8125a 100644 --- a/e2e/playground/antelope.config.ts +++ b/e2e/playground/antelope.config.ts @@ -83,19 +83,6 @@ function externalModules(): NonNullable { }; } -/** - * `@antelopejs/dms-automation`, loaded only while `VERIFY_DATABASE_AUTOMATION` - * is set, so every other journey runs the module without it. - */ -function automationModules(): NonNullable { - if (!process.env.VERIFY_DATABASE_AUTOMATION) return {}; - return { - "dms-automation": { - source: { type: "local", path: "../../node_modules/@antelopejs/dms-automation" }, - }, - }; -} - /** * The repository's playground with the ports, origins, secrets and mail * `dms-control` sets for a run, a fixture module (`app`) and the module under @@ -113,7 +100,6 @@ export default defineConfig({ config: databaseConfig(), importOverrides: databaseOverrides(), }, - ...automationModules(), ...externalModules(), dms: { source: { diff --git a/src/test/extending.journeys.test.ts b/src/test/extending.journeys.test.ts new file mode 100644 index 0000000..ce7e986 --- /dev/null +++ b/src/test/extending.journeys.test.ts @@ -0,0 +1,317 @@ +import { strict as assert } from "node:assert"; +import { setTimeout as delay } from "node:timers/promises"; +import { Schema } from "@antelopejs/interface-database"; +import { + EncryptionModifier, + Encrypted, + Field, + HashModifier, + Hashed, + Index, + LocalizationModifier, + Localized, + RegisterSchema, + RegisterTable, + Relation, + Table, +} from "@antelopejs/interface-database-decorators"; +import { isJsonValue, type JsonObject, type JsonValue } from "../types/json"; +import { call } from "./helpers/http"; +import { at, itemsAt, keysAt, textAt } from "./helpers/jsonAt"; +import { createOwnerSession, type OwnerSession } from "./ownerSession"; +import { encode } from "./stagedWire"; + +const SHOP = "extending-journeys-shop"; +const VAULT = "extending-journeys-vault"; +const PLAIN = "extending-journeys-plain"; +const REGIONS = ["eu", "us"]; +const SECRET_KEY = "verify-secret-key-0123456789abcd"; + +@RegisterTable("customers", SHOP) +class ExtendingJourneysCustomer extends Table { + declare _id: string; + @Index() declare email: string; +} + +@RegisterTable("orders", SHOP) +class ExtendingJourneysOrder extends Table { + declare _id: string; + @Index() declare number: string; + @Index() + @Relation({ to: () => ExtendingJourneysCustomer }) + declare customer_id: string; + @Index({ group: "status_created" }) declare status: string; + declare total: number; + @Index({ group: "status_created" }) declare created_at: Date; +} + +@RegisterTable("products", SHOP) +class ExtendingJourneysProduct extends Table { + declare _id: string; + declare name: string; + declare price: number; + declare tags: string[]; +} + +@RegisterTable("accounts", VAULT) +class ExtendingJourneysAccount extends Table.with( + HashModifier, + EncryptionModifier, + LocalizationModifier, +) { + @Field("string") declare _id: string; + @Hashed() @Field("string") declare password: string; + @Encrypted({ secretKey: SECRET_KEY }) + @Field("string") + declare card_number: string; + @Localized({ fallbackLocale: "en" }) + @Field("string") + declare display_name: string; +} + +@RegisterTable("notes", PLAIN) +class ExtendingJourneysNote extends Table { + @Field("string") declare _id: string; +} + +/** Keeps the decorated classes referenced: the decorator registers them. */ +const TABLES = [ + ExtendingJourneysCustomer, + ExtendingJourneysOrder, + ExtendingJourneysProduct, + ExtendingJourneysAccount, + ExtendingJourneysNote, +]; + +function shop() { + const found = Schema.get(SHOP); + assert.ok(found, "the shop schema is registered"); + return found; +} + +const ROW = { + _id: "watch-1", + name: "Watched lamp", + price: 12, + tags: ["office"], +}; +const OTHER_INSTANCE_ROW = { + _id: "watch-eu", + name: "Lamp of eu", + price: 9, + tags: [], +}; + +/** A procedure whose only node is a table watch on the default instance of the shop's products. */ +const PROCEDURE = { + name: "Watch products", + description: "", + graph: { + nodes: [ + { + id: "watch", + kind: "trigger", + typeId: "database.table-watch", + config: { schema: SHOP, table: "products" }, + position: { x: 0, y: 0 }, + }, + ], + triggerEdges: [], + dataEdges: [], + }, +}; + +let owner: OwnerSession; + +function automation(method: string, path: string, body?: JsonObject) { + return call(owner, method, `/automation${path}`, body); +} + +function execute(query: JsonObject, source: string) { + return call(owner, "POST", "/database/query/execute", { + query, + source, + language: "aql", + }); +} + +function products(instance?: string) { + return shop().instance(instance).table("products"); +} + +async function seedOrders(): Promise { + for (const region of REGIONS) { + await shop() + .createInstance(region) + .run() + .catch(() => undefined); + await shop() + .instance(region) + .table("orders") + .insert([ + { + _id: `${region}-ord-1`, + number: "#1", + customer_id: `${region}-cus-1`, + status: "paid", + total: 10, + created_at: new Date(Date.UTC(2026, 10, 1)), + }, + ]) + .run(); + } +} + +async function introspection(): Promise { + const answer = await call(owner, "GET", "/database/schemas"); + const schemas = itemsAt(answer.body, "schemas"); + const tableOf = (schema: string, table: string): JsonValue => { + const found = schemas.find((row) => textAt(row, "id") === schema) ?? null; + const tables = itemsAt(found, "tables"); + return tables.find((row) => textAt(row, "name") === table) ?? null; + }; + const orders = tableOf(SHOP, "orders"); + const columns = keysAt(orders, "fields"); + assert.ok( + ["_id", "number", "customer_id", "status", "total", "created_at"].every( + (name) => columns.includes(name), + ), + `orders has its declared columns: ${columns.join()}`, + ); + assert.deepEqual( + keysAt(orders, "indexes").sort(), + ["customer_id", "number", "status_created"], + "an index per grouped field would list status and created_at", + ); + assert.ok( + itemsAt(orders, "relations").some( + (relation) => + textAt(relation, "fromField") === "customer_id" && + textAt(relation, "toTable") === "customers", + ), + "orders points to customers through customer_id", + ); + assert.deepEqual( + at(tableOf(VAULT, "accounts"), "modifiers"), + { + password: ["HashModifier"], + card_number: ["EncryptionModifier"], + display_name: ["LocalizationModifier"], + }, + "accounts carries hashed, encrypted and localized modifiers", + ); + const instancesOf = async (schema: string) => + at( + (await call(owner, "GET", `/database/tables/instances?schema=${schema}`)) + .body, + "instances", + ); + assert.deepEqual(await instancesOf(SHOP), ["eu", "us"], "eu and us"); + assert.deepEqual(await instancesOf(PLAIN), [], "no named instance"); +} + +/** Writes the eu row, then inserts, renames and deletes the default instance's row; each write must answer 200. */ +async function writeProducts(): Promise { + const answers = [ + await execute( + encode(products("eu").insert([OTHER_INSTANCE_ROW])), + "insert the eu row", + ), + await execute( + encode(products("eu").get(OTHER_INSTANCE_ROW._id).delete()), + "delete the eu row", + ), + await execute(encode(products().insert([ROW])), "insert the row"), + await call( + owner, + "PUT", + `/database/browse/edit?filter_schema=is:${SHOP}&filter_table=is:products&id=${ROW._id}&connection=own`, + { name: "Renamed lamp" }, + ), + await execute(encode(products().get(ROW._id).delete()), "delete the row"), + ]; + assert.deepEqual( + answers.map((answer) => answer.status), + [200, 200, 200, 200, 200], + `the writes answer 200: ${answers.map((answer) => answer.text).join(" ")}`, + ); +} + +/** The trigger payloads of a procedure's runs, oldest first, once `count` are listed or 20 s pass, then 2 s more. */ +async function payloadsOf(id: string, count: number) { + const runs = async () => + itemsAt((await automation("GET", `/procedures/${id}/runs`)).body); + for (let waited = 0; waited < 20_000; waited += 1_000) { + if ((await runs()).length >= count) break; + await delay(1_000); + } + await delay(2_000); + return Promise.all( + (await runs()).toReversed().map(async (run) => { + const detail = await automation("GET", `/runs/${textAt(run, "_id")}`); + const payload: unknown = JSON.parse( + textAt(detail.body, "triggerPayload") || "null", + ); + const parsed = isJsonValue(payload) ? payload : null; + return { + type: textAt(parsed, "type"), + old: at(parsed, "old"), + new: at(parsed, "new"), + }; + }), + ); +} + +async function tableWatch(): Promise { + const created = await automation("POST", "/procedures/import", { + json: JSON.stringify(PROCEDURE), + }); + const id = textAt(created.body, "_id"); + assert.notEqual(id, "", `the import answers an id: ${created.text}`); + try { + const enabled = await automation("PUT", `/procedures/${id}/enabled`, { + enabled: true, + }); + assert.equal(enabled.status, 200, `enabling answers 200: ${enabled.text}`); + await delay(3_000); + await writeProducts(); + const renamed = { ...ROW, name: "Renamed lamp" }; + assert.deepEqual( + await payloadsOf(id, 3), + [ + { type: "insert", old: null, new: ROW }, + { type: "update", old: ROW, new: renamed }, + { type: "delete", old: renamed, new: null }, + ], + "a watch of every instance would add the eu row's runs", + ); + } finally { + await automation("PUT", `/procedures/${id}/enabled`, { enabled: false }); + await automation("DELETE", `/procedures/${id}`); + } +} + +describe("[integration] extending journeys", function () { + this.timeout(60_000); + + before(async () => { + assert.equal(TABLES.length, 5); + owner = await createOwnerSession("extending-journeys-owner@test.local"); + for (const id of [SHOP, VAULT, PLAIN]) await RegisterSchema(id); + await seedOrders(); + }); + after(async () => { + for (const region of REGIONS) await shop().destroyInstance(region).run(); + await shop().instance().table("products").delete().run(); + await owner.remove(); + }); + + it( + "a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers", + introspection, + ); + it( + "the-table-watch-hands-a-procedure-each-insert-update-and-delete", + tableWatch, + ); +}); From 1d3964c3f1f27714c61cfe606286a67ed06a8f6f Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 08:44:34 +0000 Subject: [PATCH 05/12] test(library): port the HTTP journeys to integration tests The library-survives-a-restart journey runs in src/test/library.journeys.test.ts: the harness cannot restart its backend, so the test reads the run and the shared saved query from the module's own tables through a MongoDB client of its own, then through the routes. --- .../verify-dms-database/features/README.md | 2 +- .../verify-dms-database/features/library.md | 9 +- e2e/journeys/parts/library-saved.mjs | 15 +-- src/test/library.journeys.test.ts | 101 ++++++++++++++++++ 4 files changed, 110 insertions(+), 17 deletions(-) create mode 100644 src/test/library.journeys.test.ts diff --git a/.agents/skills/verify-dms-database/features/README.md b/.agents/skills/verify-dms-database/features/README.md index fd69ee5..996cfdb 100644 --- a/.agents/skills/verify-dms-database/features/README.md +++ b/.agents/skills/verify-dms-database/features/README.md @@ -14,7 +14,7 @@ One file per feature. `covers:` lists the source globs it owns, `docs:` the page | [editing](editing.md) | # Editing | edits-are-staged-then-reviewed-then-written-one-put-per-row, invalid-drafts-are-refused-esc-cancels-and-a-click-away-decides, null-empties-a-cell-and-backslash-null-is-the-text-null, object-and-array-cells-open-the-json-editor-in-a-side-drawer, the-json-editor-is-as-tall-as-the-drawer, discard-and-closing-a-tab-with-staged-changes-ask-first, undo-writes-the-previous-values-back-within-the-window, undo-is-offered-for-ten-seconds-then-the-values-stay, a-row-deleted-meanwhile-drops-its-changes-and-the-rest-is-saved, a-failed-write-stops-the-save-and-the-rows-left-stay-staged, a-saved-row-shows-in-place-unless-the-save-may-move-rows, a-save-under-a-search-or-a-filter-reads-the-page-again, an-edit-and-its-undo-land-in-the-instance-of-the-tab-only, saved-cells-keep-their-type-numbers-booleans-dates-and-objects, the-edit-route-writes-typed-values-and-refuses-the-rest, hashed-encrypted-and-localized-columns-are-written-as-typed, the-row-drawer-stages-edits-like-the-cells-do, an-undo-whose-write-fails-keeps-the-saved-values-and-offers-undo-again | | [query](query.md) | # Query | a-query-returns-its-rows-in-the-order-it-asks, an-instance-and-every-instance-are-targeted, a-failed-query-says-what-failed-and-offers-the-nearest-name, the-insert-chips-add-their-operation, ctrl-space-completes-schemas-and-tables-from-the-workspace, an-empty-console-offers-examples-built-on-your-own-tables, results-over-1000-rows-are-cut-at-1000, the-table-view-shows-every-returned-row, an-export-of-uneven-rows-keeps-every-key-in-csv-and-json, csv-quotes-a-comma-a-quote-and-a-line-break-so-the-cell-reads-back, format-strips-trailing-spaces-and-blank-lines, ctrl-space-inside-a-filter-completes-the-columns-of-the-table, the-chart-plots-the-first-numeric-column-with-pickers-for-both-axes, open-in-data-browser-opens-the-target-table-or-the-row, copy-as-json-puts-the-returned-rows-on-the-clipboard, a-link-opens-the-console-on-the-table-in-the-instance-it-names | | [guard](guard.md) | # Guard | a-delete-names-its-operation-target-and-rows-and-waits-for-the-table-name, every-write-names-its-operation-and-counts-the-rows-it-would-touch, confirming-a-single-row-update-needs-the-table-name-as-the-docs-say, a-confirmed-write-acts-on-the-data-of-that-moment, a-read-query-runs-straight-away | -| [library](library.md) | # Library | history-keeps-your-last-500-runs-newest-first, history-records-failures-and-writes-with-their-status, history-is-searchable-and-clearing-it-keeps-the-saved-queries, a-saved-query-needs-a-name-and-can-be-edited-and-deleted, a-shared-query-reaches-the-team-and-only-its-author-changes-it, history-belongs-to-its-user-and-a-link-restores-a-run, the-library-survives-a-backend-restart, history-groups-runs-by-day-with-yesterday-and-older-dates, a-history-row-without-a-status-reads-as-ok | +| [library](library.md) | # Library | history-keeps-your-last-500-runs-newest-first, history-records-failures-and-writes-with-their-status, history-is-searchable-and-clearing-it-keeps-the-saved-queries, a-saved-query-needs-a-name-and-can-be-edited-and-deleted, a-shared-query-reaches-the-team-and-only-its-author-changes-it, history-belongs-to-its-user-and-a-link-restores-a-run, history-groups-runs-by-day-with-yesterday-and-older-dates, a-history-row-without-a-status-reads-as-ok | | [extending](extending.md) | # Extending | deep-links-open-the-documented-pages-on-the-table, without-the-automation-module-the-trigger-registration-is-a-silent-no-op | | [external](external.md) | # External | an-external-database-is-picked-browsed-edited-and-left, an-external-database-refuses-what-it-cannot-serve-with-sentences | | [package](package.md) | # Package | none: `src/test/package.test.ts` checks the tarball, the locales and the ranges | diff --git a/.agents/skills/verify-dms-database/features/library.md b/.agents/skills/verify-dms-database/features/library.md index f02a03d..0f5c8d7 100644 --- a/.agents/skills/verify-dms-database/features/library.md +++ b/.agents/skills/verify-dms-database/features/library.md @@ -25,9 +25,14 @@ The history, saved and team queries beside the console. - `history-belongs-to-its-user-and-a-link-restores-a-run`: per-user history and the `?history=` link. - `history-groups-runs-by-day-with-yesterday-and-older-dates`: runs aged through `ctx.database` list under Today, Yesterday and an older day's date, in that order. - `a-history-row-without-a-status-reads-as-ok`: a row written without status, mutation or error reads as a successful run (design Q26), in the API and in the library. -- `the-library-survives-a-backend-restart`: persistence. - `clear-history-empties-only-your-own-runs`: two owners, each clearing leaves the other's runs. +## Integration tests + +`pnpm test` runs these in `src/test/library.journeys.test.ts`, one `it` per id, so `-g ` selects one. + +- `the-library-survives-a-backend-restart`: persistence. The harness cannot restart its backend, so the test reads the run and the saved query from the module's own tables through a MongoDB client of its own, then through the routes. + ## How to get to it (user POV) - Query console, the library on the left: History, Saved, Team. @@ -55,6 +60,6 @@ pnpm e2e:run specs/library.spec.ts | Team: shared queries; teammates run them; only the author edits or deletes (README, FAQ) | `a-shared-query-reaches-the-team-and-only-its-author-changes-it` | | FAQ: only you see your saved queries unless you tick Share with team | same journey (the private query is not in Team) | | History records failures; old rows without status read as ok (design Q26) | failures: `history-records-failures-and-writes-with-their-status`; old rows: `a-history-row-without-a-status-reads-as-ok` | -| Persistence in the module's own schema | `the-library-survives-a-backend-restart` | +| Persistence in the module's own schema | `the-library-survives-a-backend-restart` (integration test) | | Clear history empties it (yours only; per-user, two users) | 5.query-console.md:60 | `clear-history-empties-only-your-own-runs` | | The 500 runs are kept per user | 5.query-console.md:60 | `history-keeps-your-last-500-runs-newest-first` (a teammate's runs survive the owner's 503) | diff --git a/e2e/journeys/parts/library-saved.mjs b/e2e/journeys/parts/library-saved.mjs index 92397ee..95d6241 100644 --- a/e2e/journeys/parts/library-saved.mjs +++ b/e2e/journeys/parts/library-saved.mjs @@ -4,7 +4,7 @@ import { SLICE, TAGS_QUERY, TAGS_SOURCE, history, libraryTab, save } from "./lib /** @typedef {import("../../database.mjs").Ctx} Ctx */ /** @typedef {import("../../database.mjs").Tab} Tab */ -/** Saved and team queries, and the library after a restart. */ +/** Saved and team queries. */ export const savedJourneys = [ { id: "a-saved-query-needs-a-name-and-can-be-edited-and-deleted", @@ -101,17 +101,4 @@ export const savedJourneys = [ await ctx.verify("the link", [check("the run's query is in the editor", (await editorText(tab)) === `${TAGS_SOURCE}.slice(0, 2)`, await editorText(tab))]); }, }, - { - id: "the-library-survives-a-backend-restart", - title: "history and saved queries are stored in the module's own tables, so they are still there after the backend restarts", - entryPoint: "GET /query/history, /query/saved after a restart", - async run(/** @type {Ctx} */ ctx) { - await runQuery(ctx, TAGS_SOURCE, TAGS_QUERY); - await save(ctx, "Durable", true); - await ctx.restartBackend(); - const runs = await history(ctx); - const saved = list((await db(ctx, "saved after restart", "GET", "/query/saved")).body, "items"); - await ctx.verify("after the restart", [check("the run is kept", runs.items.length === 1 && text(runs.items[0], "source") === TAGS_SOURCE, runs.items), check("the saved query is kept, still shared", saved.length === 1 && text(saved[0], "name") === "Durable" && pick(saved[0], "shared") === true, saved)]); - }, - }, ]; diff --git a/src/test/library.journeys.test.ts b/src/test/library.journeys.test.ts new file mode 100644 index 0000000..352aac2 --- /dev/null +++ b/src/test/library.journeys.test.ts @@ -0,0 +1,101 @@ +import { strict as assert } from "node:assert"; +import { Schema } from "@antelopejs/interface-database"; +import { SCHEMA_NAME } from "../types/constants"; +import { call } from "./helpers/http"; +import { at, itemsAt, textAt } from "./helpers/jsonAt"; +import { withOwnDatabase } from "./ownDatabase"; +import { createOwnerSession, type OwnerSession } from "./ownerSession"; +import { encode } from "./stagedWire"; + +const SCHEMA = "library-journeys-tags"; +const schema = new Schema<{ tags: { _id: string; name: string } }>(SCHEMA, { + tags: { fields: { _id: "string", name: "string" }, indexes: {} }, +}); +const QUERY = encode(schema.instance().table("tags")); +const SOURCE = `schemas["${SCHEMA}"].instance().table("tags")`; + +/** What the library journey reads of a stored history or saved-query row. */ +interface StoredRow { + source: string; + name?: string; + shared?: boolean; +} + +/** The rows of one of the module's own tables, read by a client of its own, as a restarted backend would read them. */ +function storedRows(table: string, filter: Partial) { + return withOwnDatabase((db) => + db.collection(`${SCHEMA_NAME}__${table}`).find(filter).toArray(), + ); +} + +describe("[integration] library journeys", () => { + let owner: OwnerSession; + let savedId = ""; + + before(async () => { + owner = await createOwnerSession("library-journeys-owner@test.local"); + await schema + .instance() + .table("tags") + .insert([{ _id: "t1", name: "intro" }]) + .run(); + }); + after(async () => { + await call(owner, "DELETE", "/database/query/history"); + if (savedId) + await call(owner, "DELETE", `/database/query/saved/${savedId}`); + await owner.remove(); + await schema.instance().table("tags").delete().run(); + }); + + it("the-library-survives-a-backend-restart", async () => { + const run = await call(owner, "POST", "/database/query/execute", { + query: QUERY, + source: SOURCE, + language: "aql", + }); + assert.equal(run.status, 200, run.text); + const saved = await call(owner, "POST", "/database/query/saved", { + name: "Durable", + description: "about Durable", + query: QUERY, + source: SOURCE, + language: "aql", + shared: true, + }); + savedId = textAt(saved.body, "id"); + assert.notEqual(savedId, "", saved.text); + + const history = await storedRows("query_history", { source: SOURCE }); + const library = await storedRows("saved_queries", { source: SOURCE }); + assert.deepEqual( + history.map((row) => row.source), + [SOURCE], + "a history kept in the backend's memory would leave no row in the module's own table", + ); + assert.deepEqual( + library.map((row) => [row.name, row.shared]), + [["Durable", true]], + "a saved query kept in the backend's memory would leave no row in the module's own table", + ); + + const runs = itemsAt( + (await call(owner, "GET", "/database/query/history?limit=500")).body, + "items", + ); + assert.deepEqual( + runs.map((item) => textAt(item, "source")), + [SOURCE], + "the run is kept", + ); + const listed = itemsAt( + (await call(owner, "GET", "/database/query/saved")).body, + "items", + ); + assert.deepEqual( + listed.map((item) => [at(item, "name"), at(item, "shared")]), + [["Durable", true]], + "the saved query is kept, still shared", + ); + }); +}); From bb884f77acb271aec52c2f6a1c8fdca0862d1ba5 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 08:46:21 +0000 Subject: [PATCH 06/12] test(access): port the HTTP journeys to integration tests every-route-needs-a-signed-in-session, a-member-gets-403-from-every-route-and-writes-nothing and the-owner-only-gate-is-logged-at-start leave the Playwright suite for src/test/access.journeys.test.ts. The owner-only gate is checked on each page's layout route, which the start log reports on. the-catalog-tile-reads-the-database takes the @smoke tag. --- .../verify-dms-database/features/README.md | 2 +- .../verify-dms-database/features/access.md | 15 +- e2e/journeys/access.mjs | 90 +------- src/test/access.journeys.test.ts | 216 ++++++++++++++++++ src/test/helpers/http.ts | 31 ++- src/test/helpers/pick.ts | 42 ++++ src/test/ownerSession.ts | 40 +++- 7 files changed, 338 insertions(+), 98 deletions(-) create mode 100644 src/test/access.journeys.test.ts create mode 100644 src/test/helpers/pick.ts diff --git a/.agents/skills/verify-dms-database/features/README.md b/.agents/skills/verify-dms-database/features/README.md index 249e6c9..a675cde 100644 --- a/.agents/skills/verify-dms-database/features/README.md +++ b/.agents/skills/verify-dms-database/features/README.md @@ -7,7 +7,7 @@ One file per feature. `covers:` lists the source globs it owns, `docs:` the page | [smoke](smoke.md) | # Smoke | smoke | | [overview](overview.md) | # Overview | the-connection-card-reads-the-probe, a-configured-driver-label-shows-beside-the-age, without-a-driver-label-the-card-shows-a-dash, the-card-age-counts-up-and-the-probe-repeats-every-thirty-seconds, schema-cards-list-every-schema-largest-first, largest-tables-rank-the-default-instances-by-rows, recent-queries-list-your-last-five-runs, the-header-buttons-lead-to-the-working-pages, an-unreachable-database-shows-unavailable-and-check-again-recovers | | [config](config.md) | # Config | built-in-patterns-label-schemas-by-the-start-of-their-id, an-exact-key-beats-a-pattern-which-beats-a-built-in-label, a-glob-key-matches-the-whole-schema-id, a-label-takes-each-of-the-seven-tones | -| [access](access.md) | # Access | every-route-needs-a-signed-in-session, a-member-gets-403-from-every-route-and-writes-nothing, a-member-sees-neither-the-pages-nor-the-catalog-tile, the-catalog-tile-reads-the-database, the-owner-only-gate-is-logged-at-start | +| [access](access.md) | # Access | a-member-sees-neither-the-pages-nor-the-catalog-tile, the-catalog-tile-reads-the-database | | [schemas](schemas.md) | # Schemas | the-source-counts-rows-columns-indexes-relations-and-modifiers-of-each-table, schema-instance-search-and-structure-filters-narrow-the-source-and-combine, rows-are-counted-in-the-picked-instance-default-named-or-all, the-instances-route-searches-sorts-and-limits-the-named-instances-of-a-schema, a-table-is-read-by-its-schema-and-name-id, columns-are-declared-in-code-and-inferred-from-sampled-rows, the-tables-and-schemas-routes-answer-the-platform-owner-only, each-filter-of-the-bar-narrows-the-list-and-sets-its-own-url-key, the-url-restores-every-filter-after-a-reload-and-clear-removes-them, slash-focuses-the-search-field-but-not-while-typing-or-with-a-modifier, a-filter-that-matches-nothing-says-no-result-and-clear-filters-restores-the-list, each-of-the-five-sortable-columns-sorts-both-ways-and-the-third-click-restores-the-default-order, the-relations-and-modifiers-columns-name-the-tables-and-the-flags, a-row-click-opens-the-inspector-and-previous-next-j-and-k-step-through-the-list, dragging-the-drawer-edge-resizes-it-and-it-opens-at-the-width-you-left-it, the-inspector-states-the-counts-and-lists-each-column-with-its-type-null-and-notes, a-column-named-constructor-is-listed-like-any-other-column, the-indexes-and-relations-tabs-list-what-the-table-declares-and-a-relation-opens-the-other-table, the-sample-row-tab-shows-one-row-and-another-row-pages-through-the-table, browse-query-and-diagram-actions-open-the-other-pages-on-the-same-table | | [diagram](diagram.md) | # Diagram | the-layout-api-stores-one-layout-per-schema-and-refuses-bad-positions, the-notes-api-creates-lists-updates-and-deletes-notes-per-schema, the-notes-api-refuses-missing-numbers-with-400-and-unknown-notes-with-404, every-diagram-route-answers-the-platform-owner-only, tables-list-their-columns-with-types-and-icons-and-relations-are-arrows, an-encrypted-column-carries-the-lock-icon-of-the-legend, a-table-of-more-than-twelve-columns-comes-folded-and-folding-is-not-saved, folding-is-a-setting-of-your-own-view-and-is-not-saved-with-the-team-layout, finding-a-column-a-folded-table-hides-unfolds-that-table, the-fold-keeps-the-twelve-column-boundary-and-every-column-an-arrow-ends-on, a-large-schema-opens-at-forty-percent-on-its-top-left-and-fit-view-shows-it-whole, a-relation-to-a-table-not-drawn-ends-on-a-dashed-chip-that-opens-that-table, a-relation-to-another-schema-ends-on-a-chip-that-opens-that-table, the-url-picks-the-schema-and-the-table-and-names-what-it-cannot-find, a-schema-without-a-table-says-so-and-offers-no-note-or-auto-layout, dragging-a-table-saves-the-layout-and-everyone-reads-it, a-table-not-placed-yet-takes-its-automatic-place-and-placed-tables-stay, auto-layout-previews-the-arrangement-and-keep-or-discard-decides, auto-layout-keeps-groups-together-and-clear-of-notes-that-never-move, n-and-the-note-button-drop-a-note-ready-to-write-and-it-is-saved-with-the-schema, a-double-click-edits-a-note-and-the-trash-button-and-delete-remove-it, notes-belong-to-their-schema-and-everyone-reads-them, undo-and-redo-cover-every-move-and-note-and-are-saved, escape-leaves-the-find-field-then-lifts-the-focus-then-clears-the-selection | | [data](data.md) | # Data | the-instance-picker-lists-named-instances-with-a-search-and-a-limit, list-clamps-the-page-and-orders-the-rows, list-filters-search-and-counts-follow-the-wire-tokens, the-selection-decodes-schema-table-and-instance, columns-get-and-tables-answer-what-the-grid-needs, references-count-the-rows-pointing-at-a-row, the-browse-api-answers-the-platform-owner-only, the-sidebar-counts-each-table-in-the-picked-instance, tables-open-as-preview-tabs-and-are-kept-on-demand, links-open-the-table-in-the-instance-they-name, search-filters-and-sort-narrow-and-order-the-rows, the-footer-pages-1250-rows-with-exact-ranges-at-every-size, r-refreshes-the-rows-and-the-search-shortcut-works-from-the-grid, the-row-drawer-steps-through-the-page-with-j-and-k, the-row-drawer-shows-fields-json-and-the-rows-pointing-at-it, the-fields-tab-widens-long-values-and-sets-null-with-the-dashed-circle, all-instances-is-a-read-only-view-with-the-instance-column, recently-opened-tables-are-offered-when-no-tab-is-open, no-match-and-empty-tables-say-so, a-refused-read-shows-the-error-and-try-again-reads-it-again | diff --git a/.agents/skills/verify-dms-database/features/access.md b/.agents/skills/verify-dms-database/features/access.md index 0024055..55c30f7 100644 --- a/.agents/skills/verify-dms-database/features/access.md +++ b/.agents/skills/verify-dms-database/features/access.md @@ -18,11 +18,11 @@ The pages and the module's API answer to the platform owner only, and the module ## Sub-features -- `every-route-needs-a-signed-in-session`: every read and write route answers 401 without a session. -- `a-member-gets-403-from-every-route-and-writes-nothing`: a member with the module's permissions gets 403 from every route and changes nothing. +- `every-route-needs-a-signed-in-session`: every read and write route answers 401 without a session. Integration test in `src/test/access.journeys.test.ts`. +- `a-member-gets-403-from-every-route-and-writes-nothing`: a member with the module's permissions gets 403 from every route and changes nothing. Integration test in `src/test/access.journeys.test.ts`. - `a-member-sees-neither-the-pages-nor-the-catalog-tile`: no tile and no page for a member; the owner sees the tile. - `the-catalog-tile-reads-the-database`: the tile's two readout lines, version and category. -- `the-owner-only-gate-is-logged-at-start`: the five 'gated owner-only' log lines. +- `the-owner-only-gate-is-logged-at-start`: the five 'gated owner-only' log lines. Integration test in `src/test/access.journeys.test.ts`. ## How to get to it (user POV) @@ -34,9 +34,16 @@ The pages and the module's API answer to the platform owner only, and the module pnpm e2e:run specs/access.spec.ts ``` +The journeys marked integration test run in `pnpm test`; one file alone after `pnpm run build`: + +```bash +pnpm exec ajs module test . -f dist/test/access.journeys.test.js +``` + ## Gotchas - The member is made by the playground's fixture (`POST /verify-database/member`) with a role of the given permission ids. +- The integration tests make it with `createMemberWithRole` (`src/test/ownerSession.ts`). ## Coverage @@ -45,6 +52,6 @@ pnpm e2e:run specs/access.spec.ts | Pages reserved to the platform owner; routes answer only to the owner | the first three journeys | | Tenants and their members never see it | `a-member-sees-neither-the-pages-nor-the-catalog-tile` | | Adds a Database entry to the Modules catalog | `the-catalog-tile-reads-the-database` | -| FAQ: the backend logs the owner-only gate at start | `the-owner-only-gate-is-logged-at-start` | +| FAQ: the backend logs the owner-only gate at start | `the-owner-only-gate-is-logged-at-start`: the integration test checks the gate the line reports, each page's layout route under `/modules/database/` answering the owner and refusing a member with the module's permissions; the line itself is written once at start, before a test can listen | | Own tables (`dms-database` schema) hold layouts, notes, history, saved queries | `schemas` feature lists the schema; persistence journeys of `diagram` and `library` | | Blocks carry names so the role editor can hide one per role | Not driven: the role editor lists blocks of pages the owner alone reaches; a hidden block has no observable effect on the owner | diff --git a/e2e/journeys/access.mjs b/e2e/journeys/access.mjs index 7e73d62..d3f860e 100644 --- a/e2e/journeys/access.mjs +++ b/e2e/journeys/access.mjs @@ -1,88 +1,11 @@ import { readFileSync } from "node:fs"; import { join } from "node:path"; -import { check, db, list, member, parseJson, pick, runQuery, tableQuery, text } from "../database.mjs"; +import { check, db, member, parseJson, pick, text } from "../database.mjs"; /** @typedef {import("../database.mjs").Ctx} Ctx */ -const SELECTION = "filter_schema=shop&filter_table=products"; - -/** Every read route of the module, with the query string it needs. */ -const READS = [ - "/health", - "/schemas", - "/overview/schemas", - "/overview/largest", - "/overview/recent-queries", - "/tables/source", - "/tables/instances?schema=shop", - `/browse/list?${SELECTION}`, - `/browse/count?${SELECTION}`, - `/browse/columns?${SELECTION}`, - "/browse/tables?filter_schema=shop", - `/browse/references?${SELECTION}&id=sku_desk`, - `/browse/get?${SELECTION}&id=sku_desk`, - "/diagram/layout/shop", - "/diagram/notes?schema=shop", - "/query/saved", - "/query/history", - "/query/history/none", -]; - -/** - * Every write route of the module, with a body it would accept from the owner. - * - * @type {[string, string, Record | undefined][]} - */ -const WRITES = [ - ["PUT", "/browse/edit", { schema: "shop", table: "products", updates: [] }], - ["POST", "/query/execute", { query: tableQuery("demo", "tags"), source: "x", language: "aql" }], - ["POST", "/query/dry-run", { query: tableQuery("demo", "tags") }], - ["POST", "/query/saved", { name: "q", query: tableQuery("demo", "tags"), source: "x", language: "aql", shared: true }], - ["PUT", "/query/saved/none", { name: "q", query: tableQuery("demo", "tags"), source: "x", language: "aql" }], - ["DELETE", "/query/saved/none", undefined], - ["DELETE", "/query/history", undefined], - ["PUT", "/diagram/layout/shop", { positions: {} }], - ["POST", "/diagram/notes", { schema: "shop", text: "x", x: 0, y: 0 }], - ["PUT", "/diagram/notes/none", { text: "x" }], - ["DELETE", "/diagram/notes/none", undefined], -]; - /** Who may reach the module: the platform owner, nobody else. */ export const journeys = [ - { - id: "every-route-needs-a-signed-in-session", - tag: "@smoke", - title: "each page and API route of the module answers 401 to a visitor with no session, and the owner is not refused", - entryPoint: "GET/PUT/POST/DELETE /api/database/* as nobody and as the owner", - async run(/** @type {Ctx} */ ctx) { - const anonymous = []; - for (const path of READS) anonymous.push({ label: `GET ${path}`, answer: await db(ctx, `GET ${path} as nobody`, "GET", path, { as: "anon" }) }); - for (const [method, path, body] of WRITES) anonymous.push({ label: `${method} ${path}`, answer: await db(ctx, `${method} ${path} as nobody`, method, path, { as: "anon", body }) }); - const owner = await db(ctx, "health as the owner", "GET", "/health"); - await ctx.verify("401 without a session", [...anonymous.map((row) => check(`${row.label} is 401`, row.answer.status === 401, row.answer.status)), check("the owner reaches the module", owner.status === 200, owner.status)]); - }, - }, - { - id: "a-member-gets-403-from-every-route-and-writes-nothing", - title: "a signed-in member, even one whose role holds the module's permissions, gets 403 from every route and changes no data, note, layout or history", - entryPoint: "GET/PUT/POST/DELETE /api/database/* as a member", - async run(/** @type {Ctx} */ ctx) { - await runQuery(ctx, 'schemas.demo.instance().table("tags")', tableQuery("demo", "tags")); - const beforeNotes = list((await db(ctx, "notes before", "GET", "/diagram/notes?schema=shop")).body, "notes").length; - const beforeHistory = list((await db(ctx, "history before", "GET", "/query/history")).body, "items").length; - await member(ctx, "granted", ["modules.database", "modules.database.explore", "modules.database.work"]); - const refused = []; - for (const path of READS) refused.push({ label: `GET ${path}`, answer: await db(ctx, `GET ${path} as the member`, "GET", path, { as: "granted" }) }); - for (const [method, path, body] of WRITES) refused.push({ label: `${method} ${path}`, answer: await db(ctx, `${method} ${path} as the member`, method, path, { as: "granted", body }) }); - const afterNotes = list((await db(ctx, "notes after", "GET", "/diagram/notes?schema=shop")).body, "notes").length; - const history = await db(ctx, "history after", "GET", "/query/history"); - await ctx.verify("403 for the member", [ - ...refused.map((row) => check(`${row.label} is 403`, row.answer.status === 403, row.answer.status)), - check("no note was added", afterNotes === beforeNotes, [beforeNotes, afterNotes]), - check("the owner's history is intact", list(history.body, "items").length === beforeHistory && beforeHistory === 1, pick(history.body, "total")), - ]); - }, - }, { id: "a-member-sees-neither-the-pages-nor-the-catalog-tile", title: "a member whose role holds the module's permissions does not see the Database module in the Modules catalog and cannot open its pages, while the owner sees the tile", @@ -108,6 +31,7 @@ export const journeys = [ }, { id: "the-catalog-tile-reads-the-database", + tag: "@smoke", title: "the Modules catalog tile of the owner reads the tables, rows, schemas and probe latency of the database, in the Data category, with the module's version", entryPoint: "/modules, GET /api/database/health", async run(/** @type {Ctx} */ ctx) { @@ -127,14 +51,4 @@ export const journeys = [ ]); }, }, - { - id: "the-owner-only-gate-is-logged-at-start", - title: "at start the backend logs 'Module route /modules/database//... gated owner-only' for each of the five pages, as the FAQ tells an owner to check", - entryPoint: "the backend log of the run", - async run(/** @type {Ctx} */ ctx) { - await ctx.restartBackend(); - const log = ctx.backendLog(); - await ctx.verify("the log", ["overview", "schemas", "diagram", "data", "query"].map((page) => check(`${page} is gated`, log.includes(`Module route /modules/database/${page}/... gated owner-only`), page))); - }, - }, ]; diff --git a/src/test/access.journeys.test.ts b/src/test/access.journeys.test.ts new file mode 100644 index 0000000..1eaafa8 --- /dev/null +++ b/src/test/access.journeys.test.ts @@ -0,0 +1,216 @@ +import { strict as assert } from "node:assert"; +import { Schema } from "@antelopejs/interface-database"; +import { pageRoutePath } from "@antelopejs/interface-dms/page"; +import type { JsonObject, JsonValue } from "../types/json"; +import { callBackend, callDatabase, type HttpAnswer } from "./helpers/http"; +import { pick } from "./helpers/pick"; +import { + createMemberWithRole, + createOwnerSession, + type OwnerSession, +} from "./ownerSession"; + +const SCHEMA = "access-journeys"; +const SELECTION = `filter_schema=${SCHEMA}&filter_table=products`; +const PAGES = ["overview", "schemas", "diagram", "data", "query"]; +const MODULE_PERMISSIONS = [ + "modules.database", + "modules.database.explore", + "modules.database.work", +]; + +const schema = new Schema<{ products: { _id: string; name: string } }>(SCHEMA, { + products: { fields: { _id: "string", name: "string" }, indexes: {} }, +}); + +function tableQuery(table: string): JsonObject { + return { + __cls: "Table", + stages: [ + { stage: "schema", args: [], options: { id: SCHEMA } }, + { stage: "instance", args: [] }, + { stage: "table", args: [], options: { id: table } }, + ], + }; +} + +/** Every read route of the module, with the query string it needs. */ +const READS = [ + "/health", + "/schemas", + "/overview/schemas", + "/overview/largest", + "/overview/recent-queries", + "/tables/source", + `/tables/instances?schema=${SCHEMA}`, + `/browse/list?${SELECTION}`, + `/browse/count?${SELECTION}`, + `/browse/columns?${SELECTION}`, + `/browse/tables?filter_schema=${SCHEMA}`, + `/browse/references?${SELECTION}&id=sku_desk`, + `/browse/get?${SELECTION}&id=sku_desk`, + `/diagram/layout/${SCHEMA}`, + `/diagram/notes?schema=${SCHEMA}`, + "/query/saved", + "/query/history", + "/query/history/none", +]; + +/** Every write route of the module, with a body it would accept from the owner. */ +const WRITES: readonly [string, string, JsonValue | undefined][] = [ + ["PUT", "/browse/edit", { schema: SCHEMA, table: "products", updates: [] }], + [ + "POST", + "/query/execute", + { query: tableQuery("products"), source: "x", language: "aql" }, + ], + ["POST", "/query/dry-run", { query: tableQuery("products") }], + [ + "POST", + "/query/saved", + { + name: "q", + query: tableQuery("products"), + source: "x", + language: "aql", + shared: true, + }, + ], + [ + "PUT", + "/query/saved/none", + { name: "q", query: tableQuery("products"), source: "x", language: "aql" }, + ], + ["DELETE", "/query/saved/none", undefined], + ["DELETE", "/query/history", undefined], + ["PUT", `/diagram/layout/${SCHEMA}`, { positions: {} }], + ["POST", "/diagram/notes", { schema: SCHEMA, text: "x", x: 0, y: 0 }], + ["PUT", "/diagram/notes/none", { text: "x" }], + ["DELETE", "/diagram/notes/none", undefined], +]; + +/** The status every read and write route answers `session`, keyed by method and path. */ +async function statusOfEveryRoute( + session: OwnerSession | null, +): Promise> { + const statuses: Record = {}; + for (const path of READS) { + statuses[`GET ${path}`] = (await callDatabase(session, "GET", path)).status; + } + for (const [method, path, body] of WRITES) { + statuses[`${method} ${path}`] = ( + await callDatabase(session, method, path, body) + ).status; + } + return statuses; +} + +function everyRouteAnswers(status: number): Record { + return Object.fromEntries( + [ + ...READS.map((path) => `GET ${path}`), + ...WRITES.map(([method, path]) => `${method} ${path}`), + ].map((route) => [route, status]), + ); +} + +/** The length of the list `field` of an answer, or -1 when it holds none. */ +function listLength(answer: HttpAnswer, field: string): number { + const items = pick(answer.body, field); + return Array.isArray(items) ? items.length : -1; +} + +describe("[integration] access journeys", () => { + let owner: OwnerSession; + let granted: OwnerSession; + + before(async () => { + await schema + .createInstance() + .run() + .catch(() => undefined); + await schema + .instance() + .table("products") + .insert([{ _id: "sku_desk", name: "Standing desk" }]) + .run(); + owner = await createOwnerSession("access-journeys-owner@example.test"); + granted = await createMemberWithRole( + "access-journeys-member@example.test", + MODULE_PERMISSIONS, + ); + }); + + after(async () => { + await owner.remove(); + await granted.remove(); + await schema.instance().table("products").delete().run(); + }); + + it("every-route-needs-a-signed-in-session", async () => { + assert.deepEqual( + await statusOfEveryRoute(null), + everyRouteAnswers(401), + "a route that skips the session check answers a visitor", + ); + const health = await callDatabase(owner, "GET", "/health"); + assert.equal( + health.status, + 200, + `a gate that refuses everyone also refuses the owner: ${health.text}`, + ); + }); + + it("a-member-gets-403-from-every-route-and-writes-nothing", async () => { + const run = await callDatabase(owner, "POST", "/query/execute", { + query: tableQuery("products"), + source: `schemas["${SCHEMA}"].instance().table("products")`, + language: "aql", + }); + assert.equal(run.status, 200, run.text); + const notesPath = `/diagram/notes?schema=${SCHEMA}`; + const notesBefore = listLength( + await callDatabase(owner, "GET", notesPath), + "items", + ); + const historyBefore = listLength( + await callDatabase(owner, "GET", "/query/history"), + "items", + ); + + assert.deepEqual( + await statusOfEveryRoute(granted), + everyRouteAnswers(403), + "a route gated by the module's permissions instead of the owner answers this member", + ); + assert.equal( + listLength(await callDatabase(owner, "GET", notesPath), "items"), + notesBefore, + "the member's POST /diagram/notes added a note", + ); + assert.deepEqual( + [ + historyBefore, + listLength(await callDatabase(owner, "GET", "/query/history"), "items"), + ], + [1, 1], + "the member's DELETE /query/history cleared the owner's history", + ); + }); + + it("the-owner-only-gate-is-logged-at-start", async () => { + const layouts: Record = {}; + for (const page of PAGES) { + const path = pageRoutePath(`/modules/database/${page}`, "/pagelayout"); + layouts[page] = [ + (await callBackend(owner, "GET", path)).status, + (await callBackend(granted, "GET", path)).status, + ]; + } + assert.deepEqual( + layouts, + Object.fromEntries(PAGES.map((page) => [page, [200, 403]])), + "a page outside /modules/database, or one gated by permission rather than owner-only, answers otherwise", + ); + }); +}); diff --git a/src/test/helpers/http.ts b/src/test/helpers/http.ts index c92f878..d7fe810 100644 --- a/src/test/helpers/http.ts +++ b/src/test/helpers/http.ts @@ -1,8 +1,11 @@ import { isJsonValue, type JsonValue } from "../../types/json"; import type { OwnerSession } from "../ownerSession"; -/** The test DMS's API root, served by the harness's `api` module. */ -export const API_ROOT = "http://127.0.0.1:5023/api"; +/** The test DMS's backend, served by the harness's `api` module. */ +export const BACKEND_ROOT = "http://127.0.0.1:5023"; + +/** The root of the modules' API routes on {@link BACKEND_ROOT}. */ +export const API_ROOT = `${BACKEND_ROOT}/api`; /** What the backend answered: its status, its body as JSON (`null` when it is not JSON), and its raw text. */ export interface HttpAnswer { @@ -24,7 +27,27 @@ function parsed(text: string): JsonValue { * Calls `path` under {@link API_ROOT} as `session`, or with no session when it is `null`, the way the dashboard * does: a bearer token and the default namespace. Never throws on a status. */ -export async function call( +export function call( + session: OwnerSession | null, + method: string, + path: string, + body?: JsonValue, +): Promise { + return callBackend(session, method, `/api${path}`, body); +} + +/** Calls `path` under the module's own API, `/api/database`, the way {@link call} does. */ +export function callDatabase( + session: OwnerSession | null, + method: string, + path: string, + body?: JsonValue, +): Promise { + return call(session, method, `/database${path}`, body); +} + +/** Calls `path` under {@link BACKEND_ROOT}, such as a page's route under `/dms/pages`, the way {@link call} does. */ +export async function callBackend( session: OwnerSession | null, method: string, path: string, @@ -36,7 +59,7 @@ export async function call( }); if (body !== undefined) headers.set("content-type", "application/json"); if (session !== null) headers.set("authorization", `Bearer ${session.token}`); - const response = await fetch(`${API_ROOT}${path}`, { + const response = await fetch(`${BACKEND_ROOT}${path}`, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), diff --git a/src/test/helpers/pick.ts b/src/test/helpers/pick.ts new file mode 100644 index 0000000..25c57d5 --- /dev/null +++ b/src/test/helpers/pick.ts @@ -0,0 +1,42 @@ +import { + isJsonObjectValue, + type JsonObject, + type JsonValue, +} from "../../types/json"; +import { isNumber, isString } from "../../utils/guards"; + +/** The value at `path` in `value`, through objects by key and arrays by index; `undefined` when a step is missing. */ +export function pick( + value: JsonValue | undefined, + ...path: readonly (string | number)[] +): JsonValue | undefined { + let current = value; + for (const step of path) { + if (isNumber(step) && Array.isArray(current)) { + current = current[step]; + } else if ( + isString(step) && + current !== undefined && + isJsonObjectValue(current) + ) { + current = current[step]; + } else { + return undefined; + } + } + return current; +} + +/** A text value, or the empty string for any other value. */ +export function text(value: JsonValue | undefined): string { + return isString(value) ? value : ""; +} + +/** The objects of the array at `path` in `value`; none when it is no array. */ +export function objectsAt( + value: JsonValue | undefined, + ...path: readonly (string | number)[] +): JsonObject[] { + const items = pick(value, ...path); + return Array.isArray(items) ? items.filter(isJsonObjectValue) : []; +} diff --git a/src/test/ownerSession.ts b/src/test/ownerSession.ts index e236b37..dbaffa0 100644 --- a/src/test/ownerSession.ts +++ b/src/test/ownerSession.ts @@ -2,6 +2,7 @@ import { createHmac } from "node:crypto"; import { GetModel } from "@antelopejs/interface-database-decorators"; import { SessionModel, UserModel } from "@antelopejs/interface-dms/auth/db"; import { DEFAULT_TENANT_ID } from "@antelopejs/interface-dms/constants"; +import { RoleModel, TenantMemberModel } from "@antelopejs/interface-dms/db"; import type { JsonValue } from "../types/json"; /** An owner signed in to the test DMS: the bearer token its requests send, and how to sign out. */ @@ -20,10 +21,46 @@ export function createMemberSession(email: string): Promise { return createSession(email, false); } +/** + * Creates a member of the default tenant whose role grants `permissions`, each stored with the ids it sits under + * (`modules.database.work` also grants `modules` and `modules.database`), as the DMS roles editor stores them. + */ +export async function createMemberWithRole( + email: string, + permissions: readonly string[], +): Promise { + const { userId, ...session } = await createSession(email, false); + const roles = GetModel(RoleModel, DEFAULT_TENANT_ID); + const members = GetModel(TenantMemberModel, DEFAULT_TENANT_ID); + const granted = permissions.flatMap((id) => + id + .split(".") + .map((_, index, segments) => segments.slice(0, index + 1).join(".")), + ); + const [roleId] = await roles.insert({ + name: `${email} role`, + permissions: [...new Set(granted)], + }); + const [memberId] = await members.insert({ + userId, + roleIds: roleId === undefined ? [] : [roleId], + isTenantOwner: false, + invitedBy: null, + }); + return { + token: session.token, + async remove() { + if (memberId !== undefined) await members.delete(memberId); + if (roleId !== undefined) await roles.delete(roleId); + await session.remove(); + }, + }; +} + async function createSession( email: string, owner: boolean, -): Promise { +): Promise { const users = GetModel(UserModel); const sessions = GetModel(SessionModel); const now = new Date(); @@ -79,6 +116,7 @@ async function createSession( .update(unsigned) .digest("base64url"); return { + userId, token: `${unsigned}.${signature}`, async remove() { await sessions.delete(sessionId); From 4b2f7078e1c680cbf1cc529b7e8b3819ef899712 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 08:46:27 +0000 Subject: [PATCH 07/12] test(config): port the HTTP journeys to integration tests built-in-patterns-label-schemas-by-the-start-of-their-id, an-exact-key-beats-a-pattern-which-beats-a-built-in-label and a-glob-key-matches-the-whole-schema-id leave the Playwright suite for src/test/config.journeys.test.ts. The harness sets schemaLabels whose keys match only that file's schemas, so each resolution rule is read over HTTP without a restart; the built-in journey removes the option for its run. --- .../verify-dms-database/features/README.md | 2 +- .../verify-dms-database/features/config.md | 13 +- e2e/journeys/config.mjs | 58 -------- src/test/config.journeys.test.ts | 131 ++++++++++++++++++ src/test/harness.ts | 2 + src/test/schemaLabelConfig.ts | 21 +++ 6 files changed, 165 insertions(+), 62 deletions(-) create mode 100644 src/test/config.journeys.test.ts create mode 100644 src/test/schemaLabelConfig.ts diff --git a/.agents/skills/verify-dms-database/features/README.md b/.agents/skills/verify-dms-database/features/README.md index a675cde..a67c7c1 100644 --- a/.agents/skills/verify-dms-database/features/README.md +++ b/.agents/skills/verify-dms-database/features/README.md @@ -6,7 +6,7 @@ One file per feature. `covers:` lists the source globs it owns, `docs:` the page |---|---|---| | [smoke](smoke.md) | # Smoke | smoke | | [overview](overview.md) | # Overview | the-connection-card-reads-the-probe, a-configured-driver-label-shows-beside-the-age, without-a-driver-label-the-card-shows-a-dash, the-card-age-counts-up-and-the-probe-repeats-every-thirty-seconds, schema-cards-list-every-schema-largest-first, largest-tables-rank-the-default-instances-by-rows, recent-queries-list-your-last-five-runs, the-header-buttons-lead-to-the-working-pages, an-unreachable-database-shows-unavailable-and-check-again-recovers | -| [config](config.md) | # Config | built-in-patterns-label-schemas-by-the-start-of-their-id, an-exact-key-beats-a-pattern-which-beats-a-built-in-label, a-glob-key-matches-the-whole-schema-id, a-label-takes-each-of-the-seven-tones | +| [config](config.md) | # Config | a-label-takes-each-of-the-seven-tones | | [access](access.md) | # Access | a-member-sees-neither-the-pages-nor-the-catalog-tile, the-catalog-tile-reads-the-database | | [schemas](schemas.md) | # Schemas | the-source-counts-rows-columns-indexes-relations-and-modifiers-of-each-table, schema-instance-search-and-structure-filters-narrow-the-source-and-combine, rows-are-counted-in-the-picked-instance-default-named-or-all, the-instances-route-searches-sorts-and-limits-the-named-instances-of-a-schema, a-table-is-read-by-its-schema-and-name-id, columns-are-declared-in-code-and-inferred-from-sampled-rows, the-tables-and-schemas-routes-answer-the-platform-owner-only, each-filter-of-the-bar-narrows-the-list-and-sets-its-own-url-key, the-url-restores-every-filter-after-a-reload-and-clear-removes-them, slash-focuses-the-search-field-but-not-while-typing-or-with-a-modifier, a-filter-that-matches-nothing-says-no-result-and-clear-filters-restores-the-list, each-of-the-five-sortable-columns-sorts-both-ways-and-the-third-click-restores-the-default-order, the-relations-and-modifiers-columns-name-the-tables-and-the-flags, a-row-click-opens-the-inspector-and-previous-next-j-and-k-step-through-the-list, dragging-the-drawer-edge-resizes-it-and-it-opens-at-the-width-you-left-it, the-inspector-states-the-counts-and-lists-each-column-with-its-type-null-and-notes, a-column-named-constructor-is-listed-like-any-other-column, the-indexes-and-relations-tabs-list-what-the-table-declares-and-a-relation-opens-the-other-table, the-sample-row-tab-shows-one-row-and-another-row-pages-through-the-table, browse-query-and-diagram-actions-open-the-other-pages-on-the-same-table | | [diagram](diagram.md) | # Diagram | the-layout-api-stores-one-layout-per-schema-and-refuses-bad-positions, the-notes-api-creates-lists-updates-and-deletes-notes-per-schema, the-notes-api-refuses-missing-numbers-with-400-and-unknown-notes-with-404, every-diagram-route-answers-the-platform-owner-only, tables-list-their-columns-with-types-and-icons-and-relations-are-arrows, an-encrypted-column-carries-the-lock-icon-of-the-legend, a-table-of-more-than-twelve-columns-comes-folded-and-folding-is-not-saved, folding-is-a-setting-of-your-own-view-and-is-not-saved-with-the-team-layout, finding-a-column-a-folded-table-hides-unfolds-that-table, the-fold-keeps-the-twelve-column-boundary-and-every-column-an-arrow-ends-on, a-large-schema-opens-at-forty-percent-on-its-top-left-and-fit-view-shows-it-whole, a-relation-to-a-table-not-drawn-ends-on-a-dashed-chip-that-opens-that-table, a-relation-to-another-schema-ends-on-a-chip-that-opens-that-table, the-url-picks-the-schema-and-the-table-and-names-what-it-cannot-find, a-schema-without-a-table-says-so-and-offers-no-note-or-auto-layout, dragging-a-table-saves-the-layout-and-everyone-reads-it, a-table-not-placed-yet-takes-its-automatic-place-and-placed-tables-stay, auto-layout-previews-the-arrangement-and-keep-or-discard-decides, auto-layout-keeps-groups-together-and-clear-of-notes-that-never-move, n-and-the-note-button-drop-a-note-ready-to-write-and-it-is-saved-with-the-schema, a-double-click-edits-a-note-and-the-trash-button-and-delete-remove-it, notes-belong-to-their-schema-and-everyone-reads-them, undo-and-redo-cover-every-move-and-note-and-are-saved, escape-leaves-the-find-field-then-lifts-the-focus-then-clears-the-selection | diff --git a/.agents/skills/verify-dms-database/features/config.md b/.agents/skills/verify-dms-database/features/config.md index 267c307..6a957c7 100644 --- a/.agents/skills/verify-dms-database/features/config.md +++ b/.agents/skills/verify-dms-database/features/config.md @@ -13,9 +13,9 @@ The `schemaLabels` option and the built-in patterns that badge schemas. ## Sub-features -- `built-in-patterns-label-schemas-by-the-start-of-their-id`: with no configuration, app, core, global, staging, reviews and production schemas get their label and tone; others get none. -- `an-exact-key-beats-a-pattern-which-beats-a-built-in-label`: the resolution order, and that the first matching `*` key wins. -- `a-glob-key-matches-the-whole-schema-id`: a `*` key labels a schema only when it covers the whole id, from its first to its last character. +- `built-in-patterns-label-schemas-by-the-start-of-their-id`: with no configuration, app, core, global, staging, reviews and production schemas get their label and tone; others get none. Integration test in `src/test/config.journeys.test.ts`. +- `an-exact-key-beats-a-pattern-which-beats-a-built-in-label`: the resolution order, and that the first matching `*` key wins. Integration test in `src/test/config.journeys.test.ts`. +- `a-glob-key-matches-the-whole-schema-id`: a `*` key labels a schema only when it covers the whole id, from its first to its last character. Integration test in `src/test/config.journeys.test.ts`. - `a-label-takes-each-of-the-seven-tones`: each tone, the primary default, and that options are read at start. ## How to get to it (user POV) @@ -28,8 +28,15 @@ The `schemaLabels` option and the built-in patterns that badge schemas. pnpm e2e:run specs/config.spec.ts ``` +The journeys marked integration test run in `pnpm test`; one file alone after `pnpm run build`: + +```bash +pnpm exec ajs module test . -f dist/test/config.journeys.test.js +``` + ## Gotchas +- The integration tests read the `schemaLabels` the test harness sets (`src/test/schemaLabelConfig.ts`), whose keys match only their own schemas; the built-in journey removes the option with `setModuleConfig` for its run. - `withConfig` restarts the backend with `VERIFY_DATABASE_SCHEMA_LABELS` (`key:Label:tone;...`) and again without it. ## Coverage diff --git a/e2e/journeys/config.mjs b/e2e/journeys/config.mjs index dba185e..90503a6 100644 --- a/e2e/journeys/config.mjs +++ b/e2e/journeys/config.mjs @@ -15,64 +15,6 @@ async function badges(ctx) { /** `schemaLabels` and the built-in patterns that badge schemas. */ export const journeys = [ - { - id: "built-in-patterns-label-schemas-by-the-start-of-their-id", - title: "with no configuration, schemas starting with app, core, global, staging, reviews and production get Application/info, Core/primary, Global/neutral, Staging/warning, Reviews/secondary and Production/success; others get no label", - entryPoint: "GET /api/database/overview/schemas", - async run(/** @type {Ctx} */ ctx) { - const found = await badges(ctx); - const expected = { "app-site": "Application/info", core: "Core/primary", global: "Global/neutral", "staging-eu": "Staging/warning", reviews: "Reviews/secondary", production: "Production/success", billing: "none/primary", "tenant-acme": "none/primary", demo: "none/primary", shop: "none/primary" }; - await ctx.verify("the built-in labels", Object.entries(expected).map(([id, badge]) => check(`${id} is ${badge}`, found.get(id) === badge, found.get(id)))); - }, - }, - { - id: "an-exact-key-beats-a-pattern-which-beats-a-built-in-label", - title: "schemaLabels resolve in order: the entry whose key equals the schema id, then the first key with * that matches, then the built-in pattern; two matching patterns give the first one", - entryPoint: "schemaLabels option, GET /api/database/overview/schemas", - async run(/** @type {Ctx} */ ctx) { - const labels = "tenant-acme:Acme:error;tenant-*:Tenant data:warning;*-acme:Late:info;billing:Billing:success;core:Kernel:neutral;app-*:Apps:secondary"; - await withConfig(ctx, { VERIFY_DATABASE_SCHEMA_LABELS: labels }, async () => { - const found = await badges(ctx); - await ctx.verify("the resolution order", [ - check("an exact key wins over a pattern that also matches (tenant-acme)", found.get("tenant-acme") === "Acme/error", found.get("tenant-acme")), - check("an exact key wins over a built-in label (core)", found.get("core") === "Kernel/neutral", found.get("core")), - check("an exact key labels a schema with none (billing)", found.get("billing") === "Billing/success", found.get("billing")), - check("a pattern wins over a built-in label (app-site)", found.get("app-site") === "Apps/secondary", found.get("app-site")), - check("a schema no entry matches keeps its built-in label (global)", found.get("global") === "Global/neutral", found.get("global")), - check("a schema nothing matches has no label (shop)", found.get("shop") === "none/primary", found.get("shop")), - ]); - }); - await withConfig(ctx, { VERIFY_DATABASE_SCHEMA_LABELS: "tenant-*:Tenant data:warning;*-acme:Late:info" }, async () => { - const found = await badges(ctx); - await ctx.verify("the first matching pattern wins", [check("tenant-acme takes the first pattern", found.get("tenant-acme") === "Tenant data/warning", found.get("tenant-acme"))]); - }); - await withConfig(ctx, { VERIFY_DATABASE_SCHEMA_LABELS: "*-acme:Late:info;tenant-*:Tenant data:warning" }, async () => { - const found = await badges(ctx); - await ctx.verify("the order of the entries decides", [check("tenant-acme takes the other pattern when it comes first", found.get("tenant-acme") === "Late/info", found.get("tenant-acme"))]); - }); - }, - }, - { - id: "a-glob-key-matches-the-whole-schema-id", - title: "a key with * labels a schema only when the pattern covers its whole id: app-*i, *-ac and pp-* leave app-site and tenant-acme with their own label, while app-*e and *-acme label them", - entryPoint: "schemaLabels option, GET /api/database/overview/schemas", - async run(/** @type {Ctx} */ ctx) { - await withConfig(ctx, { VERIFY_DATABASE_SCHEMA_LABELS: "app-*i:Cut:error;*-ac:Cut:error;pp-*:Cut:error" }, async () => { - const found = await badges(ctx); - await ctx.verify("a pattern that covers part of the id", [ - check("app-*i stops before the end of app-site and pp-* starts after its beginning: app-site keeps its built-in label", found.get("app-site") === "Application/info", found.get("app-site")), - check("*-ac stops before the end of tenant-acme: it keeps none", found.get("tenant-acme") === "none/primary", found.get("tenant-acme")), - ]); - }); - await withConfig(ctx, { VERIFY_DATABASE_SCHEMA_LABELS: "app-*e:Whole:error;*-acme:Whole:warning" }, async () => { - const found = await badges(ctx); - await ctx.verify("a pattern that covers the whole id", [ - check("app-*e labels app-site", found.get("app-site") === "Whole/error", found.get("app-site")), - check("*-acme labels tenant-acme", found.get("tenant-acme") === "Whole/warning", found.get("tenant-acme")), - ]); - }); - }, - }, { id: "a-label-takes-each-of-the-seven-tones", title: "color takes primary, secondary, success, info, warning, error or neutral and shows as the card's tone; a label without a color shows the primary tone", diff --git a/src/test/config.journeys.test.ts b/src/test/config.journeys.test.ts new file mode 100644 index 0000000..aeb8a57 --- /dev/null +++ b/src/test/config.journeys.test.ts @@ -0,0 +1,131 @@ +import { strict as assert } from "node:assert"; +import { Schema } from "@antelopejs/interface-database"; +import { getModuleConfig, setModuleConfig } from "../config"; +import { callDatabase } from "./helpers/http"; +import { objectsAt, text } from "./helpers/pick"; +import { createOwnerSession, type OwnerSession } from "./ownerSession"; + +/** + * The schemas whose badge each journey reads, with the label and tone the Overview feed must give them under the + * harness's `schemaLabels` (`schemaLabelConfig.ts`). `none/primary` is a schema with no label. + */ +const BUILT_IN = { + "app-cfgj6": "Application/info", + "core-cfgj6": "Core/primary", + "global-cfgj6": "Global/neutral", + "staging-cfgj6": "Staging/warning", + "reviews-cfgj6": "Reviews/secondary", + "production-cfgj6": "Production/success", + "billing-cfgj6": "none/primary", + "tenant-acme-cfgj6": "none/primary", + "shop-cfgj6": "none/primary", +}; + +/** With no `schemaLabels`, the schemas the option labels fall back to their built-in label or to none. */ +const UNCONFIGURED = { + ...BUILT_IN, + "core-cfgj7": "Core/primary", + "app-site-cfgj7": "Application/info", + "tenant-acme-cfgj7": "none/primary", +}; + +const RESOLUTION_ORDER = { + "tenant-acme-cfgj7": "Acme/error", + "core-cfgj7": "Kernel/neutral", + "billing-cfgj7": "Billing/success", + "app-site-cfgj7": "Apps/secondary", + "global-cfgj7": "Global/neutral", + "shop-cfgj7": "none/primary", + "tenant-x-acme-cfgj7": "Tenant data/warning", + "tenant-acme-cfgj7o": "Late/info", +}; + +const WHOLE_ID = { + "app-cfgj8p-site": "Application/info", + "tenant-cfgj8p-acme": "none/primary", + "app-cfgj8w-site": "Whole/error", + "tenant-cfgj8w-acme": "Whole/warning", +}; + +const SCHEMAS = [BUILT_IN, RESOLUTION_ORDER, WHOLE_ID].flatMap((expected) => + Object.keys(expected).map( + (id) => + new Schema<{ rows: { _id: string } }>(id, { + rows: { fields: { _id: "string" }, indexes: {} }, + }), + ), +); + +/** The badge of each schema of `expected`, read from the Overview feed as "label/tone". */ +async function badges( + owner: OwnerSession, + expected: Record, +): Promise> { + const feed = await callDatabase(owner, "GET", "/overview/schemas"); + assert.equal(feed.status, 200, feed.text); + const found = new Map( + objectsAt(feed.body, "items").map((card) => [ + text(card.id), + `${text(card.description) || "none"}/${text(card.iconTone)}`, + ]), + ); + return Object.fromEntries( + Object.keys(expected).map((id) => [id, found.get(id)]), + ); +} + +describe("[integration] config journeys", () => { + let owner: OwnerSession; + + before(async () => { + for (const schema of SCHEMAS) { + await schema + .createInstance() + .run() + .catch(() => undefined); + await schema + .instance() + .table("rows") + .insert([{ _id: "r1" }]) + .run(); + } + owner = await createOwnerSession("config-journeys-owner@example.test"); + }); + + after(async () => { + await owner.remove(); + for (const schema of SCHEMAS) { + await schema.instance().table("rows").delete().run(); + } + }); + + it("built-in-patterns-label-schemas-by-the-start-of-their-id", async () => { + const configured = getModuleConfig(); + setModuleConfig({ ...configured, schemaLabels: undefined }); + try { + assert.deepEqual( + await badges(owner, UNCONFIGURED), + UNCONFIGURED, + "a built-in pattern that is missing, mis-toned or matches inside the id instead of at its start, or a label the removed option still gives", + ); + } finally { + setModuleConfig(configured); + } + }); + + it("an-exact-key-beats-a-pattern-which-beats-a-built-in-label", async () => { + assert.deepEqual( + await badges(owner, RESOLUTION_ORDER), + RESOLUTION_ORDER, + "a pattern tried before the exact key, the built-in table before the option, or the last matching pattern kept instead of the first", + ); + }); + + it("a-glob-key-matches-the-whole-schema-id", async () => { + assert.deepEqual( + await badges(owner, WHOLE_ID), + WHOLE_ID, + "a pattern compiled without its ^ or $ anchor labels a schema it covers only part of", + ); + }); +}); diff --git a/src/test/harness.ts b/src/test/harness.ts index 29b429e..a103695 100644 --- a/src/test/harness.ts +++ b/src/test/harness.ts @@ -15,6 +15,7 @@ import { seedExternalDatabases, } from "./externalDatabases"; import { OWN_DATABASE_NAME, OWN_DATABASE_URL_VARIABLE } from "./ownDatabase"; +import { SCHEMA_LABELS } from "./schemaLabelConfig"; const API_PORT = 5023; const JWT_SECRET = "test-jwt-secret"; @@ -41,6 +42,7 @@ export default defineConfig({ installCommand: process.env.DMS_PREBUILT ? [] : ["pnpm build"], }, config: { + schemaLabels: SCHEMA_LABELS, externalConnections: { ledger: { access: "read-write" }, legacy: { access: "read" }, diff --git a/src/test/schemaLabelConfig.ts b/src/test/schemaLabelConfig.ts new file mode 100644 index 0000000..6bb8a9e --- /dev/null +++ b/src/test/schemaLabelConfig.ts @@ -0,0 +1,21 @@ +import type { SchemaLabelOverrides } from "../service/schemaLabels"; + +/** + * The harness's `schemaLabels` option, in the order a project would write it. Every key ends in a token only the + * schemas of `config.journeys.test.ts` carry, so no other suite's schema takes one of these labels. + */ +export const SCHEMA_LABELS: SchemaLabelOverrides = { + "tenant-acme-cfgj7": { label: "Acme", color: "error" }, + "tenant-*cfgj7": { label: "Tenant data", color: "warning" }, + "*-acme-cfgj7": { label: "Late", color: "info" }, + "billing-cfgj7": { label: "Billing", color: "success" }, + "core-cfgj7": { label: "Kernel", color: "neutral" }, + "app-*cfgj7": { label: "Apps", color: "secondary" }, + "*-acme-cfgj7o": { label: "Late", color: "info" }, + "tenant-*cfgj7o": { label: "Tenant data", color: "warning" }, + "app-cfgj8p-*i": { label: "Cut", color: "error" }, + "*-cfgj8p-ac": { label: "Cut", color: "error" }, + "pp-cfgj8p-*": { label: "Cut", color: "error" }, + "app-cfgj8w-*e": { label: "Whole", color: "error" }, + "*-cfgj8w-acme": { label: "Whole", color: "warning" }, +}; From c710918f94f28d9151489d5d35ba89bac89e6c48 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 08:46:36 +0000 Subject: [PATCH 08/12] test(data): port the HTTP journeys to integration tests The seven browse API journeys leave the Playwright suite for src/test/data.journeys.test.ts and src/test/data-reads.journeys.test.ts, split to stay under the lint's line caps, over a copy of the playground's shop, metrics and demo data seeded by src/test/dataJourneys.ts. The column-order check e2e carried as a known failure passes on @antelopejs/mongodb 1.8.11. --- .../verify-dms-database/features/README.md | 2 +- .../verify-dms-database/features/data.md | 24 +- e2e/journeys/data.mjs | 3 +- e2e/journeys/parts/browse-api-kit.mjs | 31 -- e2e/journeys/parts/browse-api-read.mjs | 145 ------- e2e/journeys/parts/browse-api.mjs | 138 ------- e2e/journeys/parts/browse.mjs | 3 - src/test/data-reads.journeys.test.ts | 354 ++++++++++++++++++ src/test/data.journeys.test.ts | 337 +++++++++++++++++ src/test/dataJourneys.ts | 328 ++++++++++++++++ 10 files changed, 1037 insertions(+), 328 deletions(-) delete mode 100644 e2e/journeys/parts/browse-api-kit.mjs delete mode 100644 e2e/journeys/parts/browse-api-read.mjs delete mode 100644 e2e/journeys/parts/browse-api.mjs create mode 100644 src/test/data-reads.journeys.test.ts create mode 100644 src/test/data.journeys.test.ts create mode 100644 src/test/dataJourneys.ts diff --git a/.agents/skills/verify-dms-database/features/README.md b/.agents/skills/verify-dms-database/features/README.md index a67c7c1..d3caf8c 100644 --- a/.agents/skills/verify-dms-database/features/README.md +++ b/.agents/skills/verify-dms-database/features/README.md @@ -10,7 +10,7 @@ One file per feature. `covers:` lists the source globs it owns, `docs:` the page | [access](access.md) | # Access | a-member-sees-neither-the-pages-nor-the-catalog-tile, the-catalog-tile-reads-the-database | | [schemas](schemas.md) | # Schemas | the-source-counts-rows-columns-indexes-relations-and-modifiers-of-each-table, schema-instance-search-and-structure-filters-narrow-the-source-and-combine, rows-are-counted-in-the-picked-instance-default-named-or-all, the-instances-route-searches-sorts-and-limits-the-named-instances-of-a-schema, a-table-is-read-by-its-schema-and-name-id, columns-are-declared-in-code-and-inferred-from-sampled-rows, the-tables-and-schemas-routes-answer-the-platform-owner-only, each-filter-of-the-bar-narrows-the-list-and-sets-its-own-url-key, the-url-restores-every-filter-after-a-reload-and-clear-removes-them, slash-focuses-the-search-field-but-not-while-typing-or-with-a-modifier, a-filter-that-matches-nothing-says-no-result-and-clear-filters-restores-the-list, each-of-the-five-sortable-columns-sorts-both-ways-and-the-third-click-restores-the-default-order, the-relations-and-modifiers-columns-name-the-tables-and-the-flags, a-row-click-opens-the-inspector-and-previous-next-j-and-k-step-through-the-list, dragging-the-drawer-edge-resizes-it-and-it-opens-at-the-width-you-left-it, the-inspector-states-the-counts-and-lists-each-column-with-its-type-null-and-notes, a-column-named-constructor-is-listed-like-any-other-column, the-indexes-and-relations-tabs-list-what-the-table-declares-and-a-relation-opens-the-other-table, the-sample-row-tab-shows-one-row-and-another-row-pages-through-the-table, browse-query-and-diagram-actions-open-the-other-pages-on-the-same-table | | [diagram](diagram.md) | # Diagram | the-layout-api-stores-one-layout-per-schema-and-refuses-bad-positions, the-notes-api-creates-lists-updates-and-deletes-notes-per-schema, the-notes-api-refuses-missing-numbers-with-400-and-unknown-notes-with-404, every-diagram-route-answers-the-platform-owner-only, tables-list-their-columns-with-types-and-icons-and-relations-are-arrows, an-encrypted-column-carries-the-lock-icon-of-the-legend, a-table-of-more-than-twelve-columns-comes-folded-and-folding-is-not-saved, folding-is-a-setting-of-your-own-view-and-is-not-saved-with-the-team-layout, finding-a-column-a-folded-table-hides-unfolds-that-table, the-fold-keeps-the-twelve-column-boundary-and-every-column-an-arrow-ends-on, a-large-schema-opens-at-forty-percent-on-its-top-left-and-fit-view-shows-it-whole, a-relation-to-a-table-not-drawn-ends-on-a-dashed-chip-that-opens-that-table, a-relation-to-another-schema-ends-on-a-chip-that-opens-that-table, the-url-picks-the-schema-and-the-table-and-names-what-it-cannot-find, a-schema-without-a-table-says-so-and-offers-no-note-or-auto-layout, dragging-a-table-saves-the-layout-and-everyone-reads-it, a-table-not-placed-yet-takes-its-automatic-place-and-placed-tables-stay, auto-layout-previews-the-arrangement-and-keep-or-discard-decides, auto-layout-keeps-groups-together-and-clear-of-notes-that-never-move, n-and-the-note-button-drop-a-note-ready-to-write-and-it-is-saved-with-the-schema, a-double-click-edits-a-note-and-the-trash-button-and-delete-remove-it, notes-belong-to-their-schema-and-everyone-reads-them, undo-and-redo-cover-every-move-and-note-and-are-saved, escape-leaves-the-find-field-then-lifts-the-focus-then-clears-the-selection | -| [data](data.md) | # Data | the-instance-picker-lists-named-instances-with-a-search-and-a-limit, list-clamps-the-page-and-orders-the-rows, list-filters-search-and-counts-follow-the-wire-tokens, the-selection-decodes-schema-table-and-instance, columns-get-and-tables-answer-what-the-grid-needs, references-count-the-rows-pointing-at-a-row, the-browse-api-answers-the-platform-owner-only, the-sidebar-counts-each-table-in-the-picked-instance, tables-open-as-preview-tabs-and-are-kept-on-demand, links-open-the-table-in-the-instance-they-name, search-filters-and-sort-narrow-and-order-the-rows, the-footer-pages-1250-rows-with-exact-ranges-at-every-size, r-refreshes-the-rows-and-the-search-shortcut-works-from-the-grid, the-row-drawer-steps-through-the-page-with-j-and-k, the-row-drawer-shows-fields-json-and-the-rows-pointing-at-it, the-fields-tab-widens-long-values-and-sets-null-with-the-dashed-circle, all-instances-is-a-read-only-view-with-the-instance-column, recently-opened-tables-are-offered-when-no-tab-is-open, no-match-and-empty-tables-say-so, a-refused-read-shows-the-error-and-try-again-reads-it-again | +| [data](data.md) | # Data | the-sidebar-counts-each-table-in-the-picked-instance, tables-open-as-preview-tabs-and-are-kept-on-demand, links-open-the-table-in-the-instance-they-name, search-filters-and-sort-narrow-and-order-the-rows, the-footer-pages-1250-rows-with-exact-ranges-at-every-size, r-refreshes-the-rows-and-the-search-shortcut-works-from-the-grid, the-row-drawer-steps-through-the-page-with-j-and-k, the-row-drawer-shows-fields-json-and-the-rows-pointing-at-it, the-fields-tab-widens-long-values-and-sets-null-with-the-dashed-circle, all-instances-is-a-read-only-view-with-the-instance-column, recently-opened-tables-are-offered-when-no-tab-is-open, no-match-and-empty-tables-say-so, a-refused-read-shows-the-error-and-try-again-reads-it-again | | [editing](editing.md) | # Editing | edits-are-staged-then-reviewed-then-written-one-put-per-row, invalid-drafts-are-refused-esc-cancels-and-a-click-away-decides, null-empties-a-cell-and-backslash-null-is-the-text-null, object-and-array-cells-open-the-json-editor-in-a-side-drawer, the-json-editor-is-as-tall-as-the-drawer, discard-and-closing-a-tab-with-staged-changes-ask-first, undo-writes-the-previous-values-back-within-the-window, undo-is-offered-for-ten-seconds-then-the-values-stay, a-row-deleted-meanwhile-drops-its-changes-and-the-rest-is-saved, a-failed-write-stops-the-save-and-the-rows-left-stay-staged, a-saved-row-shows-in-place-unless-the-save-may-move-rows, a-save-under-a-search-or-a-filter-reads-the-page-again, an-edit-and-its-undo-land-in-the-instance-of-the-tab-only, saved-cells-keep-their-type-numbers-booleans-dates-and-objects, the-edit-route-writes-typed-values-and-refuses-the-rest, hashed-encrypted-and-localized-columns-are-written-as-typed, the-row-drawer-stages-edits-like-the-cells-do, an-undo-whose-write-fails-keeps-the-saved-values-and-offers-undo-again | | [query](query.md) | # Query | a-query-returns-its-rows-in-the-order-it-asks, an-instance-and-every-instance-are-targeted, a-failed-query-says-what-failed-and-offers-the-nearest-name, the-insert-chips-add-their-operation, ctrl-space-completes-schemas-and-tables-from-the-workspace, an-empty-console-offers-examples-built-on-your-own-tables, results-over-1000-rows-are-cut-at-1000, the-table-view-shows-every-returned-row, an-export-of-uneven-rows-keeps-every-key-in-csv-and-json, csv-quotes-a-comma-a-quote-and-a-line-break-so-the-cell-reads-back, format-strips-trailing-spaces-and-blank-lines, ctrl-space-inside-a-filter-completes-the-columns-of-the-table, the-chart-plots-the-first-numeric-column-with-pickers-for-both-axes, open-in-data-browser-opens-the-target-table-or-the-row, copy-as-json-puts-the-returned-rows-on-the-clipboard, a-link-opens-the-console-on-the-table-in-the-instance-it-names | | [guard](guard.md) | # Guard | a-delete-names-its-operation-target-and-rows-and-waits-for-the-table-name, every-write-names-its-operation-and-counts-the-rows-it-would-touch, confirming-a-single-row-update-needs-the-table-name-as-the-docs-say, a-confirmed-write-acts-on-the-data-of-that-moment, a-read-query-runs-straight-away | diff --git a/.agents/skills/verify-dms-database/features/data.md b/.agents/skills/verify-dms-database/features/data.md index 1a299b1..8e02523 100644 --- a/.agents/skills/verify-dms-database/features/data.md +++ b/.agents/skills/verify-dms-database/features/data.md @@ -43,13 +43,13 @@ The Data browser's read side: the schema and instance pickers with the row count ## Sub-features -- `the-instance-picker-lists-named-instances-with-a-search-and-a-limit`: `tables/instances` sorted, searched without case, cut to the limit with the total, and its 400 and 404. -- `list-clamps-the-page-and-orders-the-rows`: `browse/list` answers 25 rows by default, clamps `limit` to 1..200 (199, 200, 201 driven) and `offset` to 0, sorts descending only for the word `desc`, and answers the exact total. -- `list-filters-search-and-counts-follow-the-wire-tokens`: `filter_` with `is:`, `contains:` (a substring on text, the whole value on a number), a bare value, an unknown mode and an empty value; search across the text and number cells; both combined; the totals. -- `the-selection-decodes-schema-table-and-instance`: `filter_schema`, `filter_table` and `filter_instance` (default, empty, named, `__CROSS_INSTANCE__`, `contains:`), the 400 and 404 refusals, and the `_instance` tag. -- `columns-get-and-tables-answer-what-the-grid-needs`: `browse/columns` (declared columns in declaration order, then sampled ones; runtime types; primary key), `browse/get` and `browse/tables` with the counts of the default instance, of eu, and across all instances. -- `references-count-the-rows-pointing-at-a-row`: `browse/references` counts per relation column, in the same instance, for one and many relations, and refuses all instances, a missing id and a missing row. -- `the-browse-api-answers-the-platform-owner-only`: anonymous 401, a member 403, on every browse route and on the edit route, nothing written. +- `the-instance-picker-lists-named-instances-with-a-search-and-a-limit`: `tables/instances` sorted, searched without case, cut to the limit with the total, and its 400 and 404. Integration test in `src/test/data.journeys.test.ts`. +- `list-clamps-the-page-and-orders-the-rows`: `browse/list` answers 25 rows by default, clamps `limit` to 1..200 (199, 200, 201 driven) and `offset` to 0, sorts descending only for the word `desc`, and answers the exact total. Integration test in `src/test/data.journeys.test.ts`. +- `list-filters-search-and-counts-follow-the-wire-tokens`: `filter_` with `is:`, `contains:` (a substring on text, the whole value on a number), a bare value, an unknown mode and an empty value; search across the text and number cells; both combined; the totals. Integration test in `src/test/data.journeys.test.ts`. +- `the-selection-decodes-schema-table-and-instance`: `filter_schema`, `filter_table` and `filter_instance` (default, empty, named, `__CROSS_INSTANCE__`, `contains:`), the 400 and 404 refusals, and the `_instance` tag. Integration test in `src/test/data-reads.journeys.test.ts`. +- `columns-get-and-tables-answer-what-the-grid-needs`: `browse/columns` (declared columns in declaration order, then sampled ones; runtime types; primary key), `browse/get` and `browse/tables` with the counts of the default instance, of eu, and across all instances. Integration test in `src/test/data-reads.journeys.test.ts`. +- `references-count-the-rows-pointing-at-a-row`: `browse/references` counts per relation column, in the same instance, for one and many relations, and refuses all instances, a missing id and a missing row. Integration test in `src/test/data-reads.journeys.test.ts`. +- `the-browse-api-answers-the-platform-owner-only`: anonymous 401, a member 403, on every browse route and on the edit route, nothing written. Integration test in `src/test/data.journeys.test.ts`. - `the-sidebar-counts-each-table-in-the-picked-instance`: the pickers, the counts of default, eu, us and All instances, the footer naming the instance, `T` focusing the table search, `Esc`, the no-match text and the counts that cannot be read. - `tables-open-as-preview-tabs-and-are-kept-on-demand`: italic preview tab, replaced by the next table; kept by a double-click in the list, the pin button, a double-click on the tab or a Ctrl-click; the hint line; closing; reload; the URL. - `links-open-the-table-in-the-instance-they-name`: `?schema=&table=`, `instance=eu`, `instance=us`, `instance=all`, a schema alone, and Open in query console for each. @@ -76,12 +76,20 @@ The Data browser's read side: the schema and instance pickers with the row count pnpm e2e:run specs/data.spec.ts ``` +The journeys marked integration test run in `pnpm test`; one file alone after `pnpm run build`: + +```bash +pnpm exec ajs module test . -f dist/test/data-reads.journeys.test.js +pnpm exec ajs module test . -f dist/test/data.journeys.test.js +``` + ## Gotchas - The playground's `shop` schema has the products of the default instance and of eu and us, with the orders, customers and order items of eu and us only; `metrics.readings` has 1,250 rows; `vault.accounts` has two rows written by `e2e/playground/src/browse-fixtures.ts`. - Unsorted rows come in stored order, which is not the order of the ids: journeys sort by a column or take the order from the API. - Single-instance rows carry `_instance` on MongoDB; the grid hides the column outside All instances. -- Known failure, open question: `columns-get-and-tables-answer-what-the-grid-needs` expects `browse/columns` to list the `_instance` tag last; on `@antelopejs/mongodb` 1.8.6 it comes after `created_at`, and no doc page fixes the order. +- `columns-get-and-tables-answer-what-the-grid-needs` expects `browse/columns` to list the `_instance` tag last. The e2e run on `@antelopejs/mongodb` 1.8.6 put it after `created_at`; the integration test passes on 1.8.11, the version the harness loads. +- The integration tests of the browse API seed their own copy of the playground's `shop`, `metrics` and `demo` data (`src/test/dataJourneys.ts`), under schema names of their own. - A journey that needs a failing server injects the failure with a page route (`page.route`) in the browser; the product code is untouched. - The drawer's J and K and the Previous and Next buttons are the DMS row header's, driven with the focus in the drawer. diff --git a/e2e/journeys/data.mjs b/e2e/journeys/data.mjs index b5faa01..c4662b3 100644 --- a/e2e/journeys/data.mjs +++ b/e2e/journeys/data.mjs @@ -1,4 +1,3 @@ -import { browseApiJourneys } from "./parts/browse-api.mjs"; import { gridJourneys } from "./parts/browse-grid.mjs"; import { emptyJourneys } from "./parts/browse-empty.mjs"; import { optionJourneys } from "./parts/browse-options.mjs"; @@ -7,4 +6,4 @@ import { stateJourneys } from "./parts/browse-states.mjs"; import { sidebarJourneys } from "./parts/browse-sidebar.mjs"; /** The Data browser: reading rows. */ -export const journeys = [...browseApiJourneys, ...sidebarJourneys, ...gridJourneys, ...rowJourneys, ...stateJourneys, ...emptyJourneys, ...optionJourneys]; +export const journeys = [...sidebarJourneys, ...gridJourneys, ...rowJourneys, ...stateJourneys, ...emptyJourneys, ...optionJourneys]; diff --git a/e2e/journeys/parts/browse-api-kit.mjs b/e2e/journeys/parts/browse-api-kit.mjs deleted file mode 100644 index 780c29c..0000000 --- a/e2e/journeys/parts/browse-api-kit.mjs +++ /dev/null @@ -1,31 +0,0 @@ -import { isText, pick, text } from "../../database.mjs"; - -/** @typedef {import("../../database.mjs").Ctx} Ctx */ - -/** - * @param {import("../../database.mjs").Answer} answer An error answer - * @returns {string} Its message: the body when the body is text, else the message field - */ -export function msg(answer) { - return isText(answer.body) ? answer.body : text(answer.body, "message"); -} - -/** - * @param {unknown} items A list of objects - * @param {number} index The position - * @param {string} field A field of the item - * @returns {unknown} The field of the item - */ -export function itemField(items, index, field) { - return Array.isArray(items) ? pick(items[index], field) : undefined; -} - -/** - * @param {import("../../database.mjs").Answer} answer A tables answer - * @returns {{ name: unknown, elementCount: unknown }[]} Its items - */ -export function rowsOfItems(answer) { - const items = pick(answer.body, "items"); - return Array.isArray(items) ? items.map((item) => ({ name: pick(item, "name"), elementCount: pick(item, "elementCount") })) : []; -} - diff --git a/e2e/journeys/parts/browse-api-read.mjs b/e2e/journeys/parts/browse-api-read.mjs deleted file mode 100644 index c46fa17..0000000 --- a/e2e/journeys/parts/browse-api-read.mjs +++ /dev/null @@ -1,145 +0,0 @@ -import { check, db, list, member, pick, show, text } from "../../database.mjs"; -import { ALL, browse, rowsOf } from "./browse.mjs"; -import { itemField, msg, rowsOfItems } from "./browse-api-kit.mjs"; - -/** @typedef {import("../../database.mjs").Ctx} Ctx */ - -/** @type {{ id: string, title: string, entryPoint: string, run: (ctx: Ctx) => Promise }} */ -export const columnsGetAndTables = { - id: "columns-get-and-tables-answer-what-the-grid-needs", - title: "browse/columns answers the sampled columns, their runtime types and the primary key; get answers a row by id; tables answers every table of the schema with its row count in the picked instance", - entryPoint: "GET /api/database/browse/columns, get, tables", - knownFailures: { - "the orders columns: the declared ones in declaration order, then the sampled ones in stored order, the instance tag last": "open question: browse/columns puts the _instance tag after created_at on @antelopejs/mongodb 1.8.6, and no doc page fixes the order", - }, - async run(/** @type {Ctx} */ ctx) { - const columns = await browse(ctx, "the columns of eu's orders", "columns", "shop.orders", { filter_instance: "is:eu" }); - const customerColumns = await browse(ctx, "the columns of customers", "columns", "shop.customers", { filter_instance: "is:eu" }); - const emptyColumns = await browse(ctx, "the columns of an empty table", "columns", "metrics.empty_log"); - const row = await browse(ctx, "one order", "get", "shop.orders", { filter_instance: "is:eu", id: "eu_ord_10400" }); - const otherInstance = await browse(ctx, "the same id in us", "get", "shop.orders", { filter_instance: "is:us", id: "eu_ord_10400" }); - const missing = await browse(ctx, "a missing row", "get", "shop.orders", { filter_instance: "is:eu", id: "nope" }); - const noId = await browse(ctx, "no id", "get", "shop.orders", { filter_instance: "is:eu" }); - const tablesEu = await db(ctx, "tables in eu", "GET", "/browse/tables?filter_schema=is:shop&filter_instance=is:eu"); - const tablesDefault = await db(ctx, "tables in the default instance", "GET", "/browse/tables?filter_schema=is:shop"); - const tablesAll = await db(ctx, "tables across every instance", "GET", `/browse/tables?filter_schema=is:shop&filter_instance=is:${ALL}`); - const tablesMetrics = await db(ctx, "tables of metrics", "GET", "/browse/tables?filter_schema=is:metrics"); - const noSchema = await db(ctx, "tables without a schema", "GET", "/browse/tables"); - const unknown = await db(ctx, "tables of an unknown schema", "GET", "/browse/tables?filter_schema=is:nowhere"); - /** @param {import("../../database.mjs").Answer} answer @returns {string} */ - const counts = (answer) => show(Object.fromEntries(rowsOfItems(answer).map((item) => [item.name, item.elementCount]))); - const types = pick(columns.body, "types"); - await ctx.verify("the grid's reads", [ - check("the orders columns: the declared ones in declaration order, then the sampled ones in stored order, the instance tag last", show(pick(columns.body, "columns")) === '["_id","number","customer_id","status","created_at","channel","total","currency","coupon_id","shipping","_instance"]', pick(columns.body, "columns")), - check("the primary key is _id", pick(columns.body, "primaryKey") === "_id", pick(columns.body, "primaryKey")), - check("the types name the runtime type of each column", show(types) !== "undefined" && pick(types, "total") === "number" && pick(types, "status") === "string" && pick(types, "shipping") === "object" && pick(types, "created_at") === "date", types), - check("a null cell takes the type of a later row: coupon_id is a string", pick(types, "coupon_id") === "string", pick(types, "coupon_id")), - check("customers: a boolean and a number column", pick(customerColumns.body, "types", "vip") === "boolean" && pick(customerColumns.body, "types", "credit_limit") === "number", pick(customerColumns.body, "types")), - check("an empty table has no sampled column", show(pick(emptyColumns.body, "columns")) === "[]", emptyColumns.body), - check("get answers the stored row", pick(row.body, "_id") === "eu_ord_10400" && pick(row.body, "number") === "#10400" && pick(row.body, "customer_id") === "eu_cus_000" && pick(row.body, "shipping", "carrier") === "DHL", row.body), - check("get reads the instance asked: the id of eu is not in us", otherInstance.status === 404 && /Row not found/.test(msg(otherInstance)), [otherInstance.status, otherInstance.body]), - check("get of a missing id is 404, without an id 400", missing.status === 404 && noId.status === 400, [missing.status, noId.status]), - check("tables of eu: 24 customers, 6 products, 80 orders, 160 order_items", counts(tablesEu) === '{"customers":24,"products":6,"orders":80,"order_items":160}', counts(tablesEu)), - check("tables of the default instance: only products hold rows", counts(tablesDefault) === '{"customers":0,"products":6,"orders":0,"order_items":0}', counts(tablesDefault)), - check("tables across every instance count the union", counts(tablesAll) === '{"customers":48,"products":18,"orders":160,"order_items":320}', counts(tablesAll)), - check("metrics: 1250 readings and an empty log", counts(tablesMetrics) === '{"readings":1250,"empty_log":0}', counts(tablesMetrics)), - check("tables without a schema is 400, an unknown schema 404", noSchema.status === 400 && unknown.status === 404 && /Unknown schema: nowhere/.test(msg(unknown)), [noSchema.status, unknown.status]), - ]); - }, -}; - -/** @type {{ id: string, title: string, entryPoint: string, run: (ctx: Ctx) => Promise }} */ -export const referencesCount = { - id: "references-count-the-rows-pointing-at-a-row", - title: "browse/references counts, per relation column, the rows of other tables pointing at one row in the same instance, answers an empty list for a table nothing points to, and refuses every instance, a missing id and a missing row", - entryPoint: "GET /api/database/browse/references", - async run(/** @type {Ctx} */ ctx) { - const order = await browse(ctx, "what points at an order", "references", "shop.orders", { filter_instance: "is:eu", id: "eu_ord_10400" }); - const customer = await browse(ctx, "what points at a customer", "references", "shop.customers", { filter_instance: "is:eu", id: "eu_cus_000" }); - const customerUs = await browse(ctx, "the same customer number in us", "references", "shop.customers", { filter_instance: "is:us", id: "us_cus_001" }); - const product = await browse(ctx, "what points at a product", "references", "shop.products", { filter_instance: "is:eu", id: "eu_sku_desk" }); - const defaultProduct = await browse(ctx, "what points at a default product", "references", "shop.products", { id: "sku_desk" }); - const items = await browse(ctx, "what points at an order item", "references", "shop.order_items", { filter_instance: "is:eu", id: "eu_itm_0" }); - const everywhere = await browse(ctx, "every instance", "references", "shop.orders", { filter_instance: `is:${ALL}`, id: "eu_ord_10400" }); - const noId = await browse(ctx, "no id", "references", "shop.orders", { filter_instance: "is:eu" }); - const missing = await browse(ctx, "a missing row", "references", "shop.orders", { filter_instance: "is:eu", id: "nope" }); - const tags = await browse(ctx, "what points at a tag", "references", "demo.tags", { id: "none" }); - const posts = await browse(ctx, "what points at a post", "references", "demo.posts", { id: "none" }); - const demoRows = await browse(ctx, "a tag id", "list", "demo.tags", { sortKey: "name", limit: 1 }); - const tagId = String(rowsOf(demoRows)[0]?._id); - const postRows = await browse(ctx, "a post", "list", "demo.posts", { sortKey: "title", limit: 1 }); - const postId = String(rowsOf(postRows)[0]?._id); - const postRefs = await browse(ctx, "what points at the first post", "references", "demo.posts", { id: postId }); - const tagRefs = await browse(ctx, "what points at the first tag", "references", "demo.tags", { id: tagId }); - /** @param {import("../../database.mjs").Answer} answer @returns {string} */ - const summary = (answer) => show(Object.fromEntries(Array.from(list(answer.body, "items").filter((item) => text(item, "schema") !== "links"), (/** @type {unknown} */ item) => [`${text(item, "table")}.${text(item, "field")}`, pick(item, "count")]))); - await ctx.verify("the references", [ - check("an order is pointed at by two order_items.order_id, not many", summary(order) === '{"order_items.order_id":2}' && itemField(pick(order.body, "items"), 0, "many") === false, order.body), - check("a customer: its 4 orders in eu", summary(customer) === '{"orders.customer_id":4}', customer.body), - check("us counts in us, not in eu", summary(customerUs) === '{"orders.customer_id":4}', customerUs.body), - check("an eu product counts the order items of eu only: 27", summary(product) === '{"order_items.product_id":27}', product.body), - check("the same product in the default instance counts the default instance: 0", summary(defaultProduct) === '{"order_items.product_id":0}', defaultProduct.body), - check("a table nothing points to answers an empty list", show(pick(items.body, "items")) === "[]", items.body), - check("every instance is refused 400", everywhere.status === 400 && /Pick one instance/.test(msg(everywhere)), [everywhere.status, everywhere.body]), - check("a missing id is 400 and a missing row 404", noId.status === 400 && missing.status === 404, [noId.status, missing.status]), - check("an unknown row of demo is 404", tags.status === 404 && posts.status === 404, [tags.status, posts.status]), - check("a many relation (posts.tag_ids -> tags) is counted with includes: 0 rows today", summary(tagRefs).includes("posts.tag_ids") && itemField(pick(tagRefs.body, "items"), 0, "many") === true, tagRefs.body), - check("a post is pointed at by comments.post", summary(postRefs).includes("comments.post"), postRefs.body), - ]); - }, -}; - -/** @type {{ id: string, title: string, entryPoint: string, run: (ctx: Ctx) => Promise }} */ -export const ownerOnly = { - id: "the-browse-api-answers-the-platform-owner-only", - title: "an anonymous caller and a member without the owner's rights are refused every browse route, edits included, and nothing is written", - entryPoint: "/api/database/browse/*", - async run(/** @type {Ctx} */ ctx) { - await member(ctx, "reader", []); - const paths = ["/browse/list?filter_schema=is:shop&filter_table=is:products", "/browse/count?filter_schema=is:shop&filter_table=is:products", "/browse/columns?filter_schema=is:shop&filter_table=is:products", "/browse/tables?filter_schema=is:shop", "/browse/get?filter_schema=is:shop&filter_table=is:products&id=sku_desk", "/browse/references?filter_schema=is:shop&filter_table=is:products&id=sku_desk", "/tables/instances?schema=shop"]; - const anon = []; - const reader = []; - for (const path of paths) { - anon.push((await db(ctx, `anonymous ${path}`, "GET", path, { as: "anon" })).status); - reader.push((await db(ctx, `member ${path}`, "GET", path, { as: "reader" })).status); - } - const edit = "/browse/edit?filter_schema=is:shop&filter_table=is:products&id=sku_desk"; - const anonEdit = await db(ctx, "anonymous edit", "PUT", edit, { as: "anon", body: { name: "Hacked" } }); - const readerEdit = await db(ctx, "member edit", "PUT", edit, { as: "reader", body: { name: "Hacked" } }); - const after = await browse(ctx, "the product after", "get", "shop.products", { id: "sku_desk" }); - await ctx.verify("who may browse", [ - check("anonymous: 401 on every read route", anon.every((status) => status === 401), anon), - check("a member without the owner's rights: refused on every read route", reader.every((status) => status === 403), reader), - check("anonymous and member edits are refused", anonEdit.status === 401 && readerEdit.status === 403, [anonEdit.status, readerEdit.status]), - check("the product is untouched", pick(after.body, "name") === "Standing desk", after.body), - ]); - }, -}; - -/** @type {{ id: string, title: string, entryPoint: string, run: (ctx: Ctx) => Promise }} */ -export const instancesRoute = { - id: "the-instance-picker-lists-named-instances-with-a-search-and-a-limit", - title: "tables/instances lists a schema's named instances sorted, filtered by a case-insensitive search, cut to the limit with the total of matches, and refuses a missing and an unknown schema", - entryPoint: "GET /api/database/tables/instances", - async run(/** @type {Ctx} */ ctx) { - const all = await db(ctx, "shop instances", "GET", "/tables/instances?schema=shop"); - const searched = await db(ctx, "search US", "GET", "/tables/instances?schema=shop&search=US"); - const both = await db(ctx, "search u", "GET", "/tables/instances?schema=shop&search=u"); - const none = await db(ctx, "search zzz", "GET", "/tables/instances?schema=shop&search=zzz"); - const limited = await db(ctx, "limit 1", "GET", "/tables/instances?schema=shop&limit=1"); - const zero = await db(ctx, "limit 0", "GET", "/tables/instances?schema=shop&limit=0"); - const metrics = await db(ctx, "metrics instances", "GET", "/tables/instances?schema=metrics"); - const missing = await db(ctx, "no schema", "GET", "/tables/instances"); - const unknown = await db(ctx, "unknown schema", "GET", "/tables/instances?schema=nowhere"); - await ctx.verify("named instances", [ - check("shop has eu and us, sorted, 2 in total", show(pick(all.body, "instances")) === '["eu","us"]' && pick(all.body, "total") === 2, all.body), - check("the search ignores case: US finds us only", show(pick(searched.body, "instances")) === '["us"]' && pick(searched.body, "total") === 1, searched.body), - check("u matches both", pick(both.body, "total") === 2, both.body), - check("no match: an empty list and 0", show(pick(none.body, "instances")) === "[]" && pick(none.body, "total") === 0, none.body), - check("limit 1 shows the first instance and still counts 2", show(pick(limited.body, "instances")) === '["eu"]' && pick(limited.body, "total") === 2, limited.body), - check("limit 0 is raised to 1", show(pick(zero.body, "instances")) === '["eu"]', zero.body), - check("a schema with no named instance answers none", show(pick(metrics.body, "instances")) === "[]" && pick(metrics.body, "total") === 0, metrics.body), - check("a missing schema is 400 and an unknown one 404", missing.status === 400 && unknown.status === 404, [missing.status, unknown.status]), - ]); - }, -}; diff --git a/e2e/journeys/parts/browse-api.mjs b/e2e/journeys/parts/browse-api.mjs deleted file mode 100644 index 1a5ff5f..0000000 --- a/e2e/journeys/parts/browse-api.mjs +++ /dev/null @@ -1,138 +0,0 @@ -import { check, db, pick, show } from "../../database.mjs"; -import { ALL, browse, ids, rowsOf } from "./browse.mjs"; -import { msg } from "./browse-api-kit.mjs"; -import { columnsGetAndTables, instancesRoute, ownerOnly, referencesCount } from "./browse-api-read.mjs"; - -/** @typedef {import("../../database.mjs").Ctx} Ctx */ - -/** @type {{ id: string, title: string, entryPoint: string, run: (ctx: Ctx) => Promise }} */ -const listClampsLimitAndOffset = { - id: "list-clamps-the-page-and-orders-the-rows", - title: "browse/list answers 25 rows by default, clamps limit to 1..200 and offset to 0, falls back to ascending for any direction but desc, and answers the exact total", - entryPoint: "GET /api/database/browse/list", - async run(/** @type {Ctx} */ ctx) { - const base = await browse(ctx, "default page", "list", "metrics.readings"); - const cap = await browse(ctx, "limit 500", "list", "metrics.readings", { limit: 500 }); - const exact = await browse(ctx, "limit 200", "list", "metrics.readings", { limit: 200 }); - const below = await browse(ctx, "limit 199", "list", "metrics.readings", { limit: 199 }); - const over = await browse(ctx, "limit 201", "list", "metrics.readings", { limit: 201 }); - const zero = await browse(ctx, "limit 0", "list", "metrics.readings", { limit: 0 }); - const negative = await browse(ctx, "limit -7", "list", "metrics.readings", { limit: -7 }); - const junk = await browse(ctx, "limit abc", "list", "metrics.readings", { limit: "abc" }); - const negativeOffset = await browse(ctx, "offset -3", "list", "metrics.readings", { offset: -3, limit: 5, sortKey: "seq" }); - const last = await browse(ctx, "last page at 200 per page", "list", "metrics.readings", { offset: 1200, limit: 200, sortKey: "seq" }); - const past = await browse(ctx, "past the end", "list", "metrics.readings", { offset: 1250, limit: 25, sortKey: "seq" }); - const asc = await browse(ctx, "seq ascending", "list", "metrics.readings", { sortKey: "seq", limit: 3 }); - const desc = await browse(ctx, "seq descending", "list", "metrics.readings", { sortKey: "seq", sortDirection: "desc", limit: 3 }); - const upper = await browse(ctx, "DESC upper case", "list", "metrics.readings", { sortKey: "seq", sortDirection: "DESC", limit: 3 }); - const upward = await browse(ctx, "direction up", "list", "metrics.readings", { sortKey: "seq", sortDirection: "up", limit: 3 }); - const noKey = await browse(ctx, "direction without key", "list", "metrics.readings", { sortDirection: "desc", limit: 2 }); - const seqs = (/** @type {import("../../database.mjs").Answer} */ answer) => rowsOf(answer).map((row) => row.seq); - await ctx.verify("the paging parameters", [ - check("no limit answers 25 rows, limit 25, offset 0, total 1250, the primary key", rowsOf(base).length === 25 && pick(base.body, "limit") === 25 && pick(base.body, "offset") === 0 && pick(base.body, "total") === 1250 && pick(base.body, "primaryKey") === "_id", [rowsOf(base).length, pick(base.body, "limit"), pick(base.body, "total"), pick(base.body, "primaryKey")]), - check("limit 500 is cut to 200 rows and reported as 200", rowsOf(cap).length === 200 && pick(cap.body, "limit") === 200, [rowsOf(cap).length, pick(cap.body, "limit")]), - check("limit 200 answers 200", rowsOf(exact).length === 200 && pick(exact.body, "limit") === 200, [rowsOf(exact).length, pick(exact.body, "limit")]), - check("limit 199 answers 199 rows", rowsOf(below).length === 199 && pick(below.body, "limit") === 199, [rowsOf(below).length, pick(below.body, "limit")]), - check("limit 201 is cut to 200", rowsOf(over).length === 200 && pick(over.body, "limit") === 200, [rowsOf(over).length, pick(over.body, "limit")]), - check("limit 0 is raised to 1", rowsOf(zero).length === 1 && pick(zero.body, "limit") === 1, [rowsOf(zero).length, pick(zero.body, "limit")]), - check("a negative limit is raised to 1", rowsOf(negative).length === 1 && pick(negative.body, "limit") === 1, [rowsOf(negative).length, pick(negative.body, "limit")]), - check("a limit that is not a number falls back to 25", rowsOf(junk).length === 25 && pick(junk.body, "limit") === 25, [rowsOf(junk).length, pick(junk.body, "limit")]), - check("a negative offset starts at the first row", pick(negativeOffset.body, "offset") === 0 && show(seqs(negativeOffset)) === "[1,2,3,4,5]", seqs(negativeOffset)), - check("offset 1200 at 200 rows answers the last 50 rows, 1201 to 1250", rowsOf(last).length === 50 && show(seqs(last).slice(0, 1)) === "[1201]" && show(seqs(last).slice(-1)) === "[1250]" && pick(last.body, "total") === 1250, [rowsOf(last).length, seqs(last).slice(0, 1), seqs(last).slice(-1)]), - check("an offset past the end answers no row and the total", rowsOf(past).length === 0 && pick(past.body, "total") === 1250, [rowsOf(past).length, pick(past.body, "total")]), - check("ascending by seq starts at 1", show(seqs(asc)) === "[1,2,3]", seqs(asc)), - check("descending by seq starts at 1250", show(seqs(desc)) === "[1250,1249,1248]", seqs(desc)), - check("only the word desc sorts descending: DESC and up fall back to ascending", show(seqs(upper)) === "[1,2,3]" && show(seqs(upward)) === "[1,2,3]", [seqs(upper), seqs(upward)]), - check("a direction without a sort key keeps the stored order", rowsOf(noKey).length === 2 && show(ids(rowsOf(noKey))) === show(ids(rowsOf(base)).slice(0, 2)), [ids(rowsOf(noKey)), ids(rowsOf(base)).slice(0, 2)]), - ]); - }, -}; - -/** @type {{ id: string, title: string, entryPoint: string, run: (ctx: Ctx) => Promise }} */ -const listFiltersAndSearch = { - id: "list-filters-search-and-counts-follow-the-wire-tokens", - title: "filter_ takes is: (exact, case-sensitive), contains: (case-insensitive) or a bare value (exact); an unknown mode or an empty value filters nothing; search matches any cell case-insensitively; filters and search combine and the total counts the matches", - entryPoint: "GET /api/database/browse/list", - async run(/** @type {Ctx} */ ctx) { - const is = await browse(ctx, "band is band-1", "list", "metrics.readings", { filter_band: "is:band-1", limit: 200, sortKey: "seq" }); - const bare = await browse(ctx, "band without a mode", "list", "metrics.readings", { filter_band: "band-1", limit: 1 }); - const upperIs = await browse(ctx, "is is case-sensitive", "list", "metrics.readings", { filter_band: "is:BAND-1", limit: 1 }); - const contains = await browse(ctx, "band contains AND-2", "list", "metrics.readings", { filter_band: "contains:AND-2", limit: 1 }); - const seqIs = await browse(ctx, "seq is 100", "list", "metrics.readings", { filter_seq: "is:100" }); - const seqContains = await browse(ctx, "seq contains 12", "list", "metrics.readings", { filter_seq: "contains:12", limit: 200 }); - const unknownMode = await browse(ctx, "an unknown mode", "list", "metrics.readings", { filter_band: "starts:band", limit: 1 }); - const empty = await browse(ctx, "an empty filter", "list", "metrics.readings", { filter_band: "", limit: 1 }); - const colon = await browse(ctx, "contains with a colon", "list", "metrics.readings", { filter_band: "contains:band-1:x", limit: 1 }); - const search = await browse(ctx, "search BAND-3", "list", "metrics.readings", { search: "BAND-3", limit: 1 }); - const searchId = await browse(ctx, "search an id", "list", "metrics.readings", { search: "R_0042" }); - const searchNumber = await browse(ctx, "search a number", "list", "metrics.readings", { search: "1250", limit: 5 }); - const both = await browse(ctx, "search and filter", "list", "metrics.readings", { search: "band-1", filter_seq: "contains:6", limit: 5 }); - const bothApart = await browse(ctx, "a search and a filter no row satisfies together", "list", "metrics.readings", { search: "band-2", filter_seq: "contains:6", limit: 5 }); - const twoFilters = await browse(ctx, "two filters", "list", "metrics.readings", { filter_band: "is:band-1", filter_seq: "is:1", limit: 5 }); - const sortedFiltered = await browse(ctx, "a filter sorted descending", "list", "metrics.readings", { filter_band: "is:band-2", sortKey: "seq", sortDirection: "desc", limit: 2 }); - const none = await browse(ctx, "no match", "list", "metrics.readings", { search: "zzz-no-such-text" }); - await ctx.verify("the filter grammar", [ - check("is:band-1 matches 250 rows, all of band-1", pick(is.body, "total") === 250 && rowsOf(is).length === 200 && rowsOf(is).every((row) => row.band === "band-1"), [pick(is.body, "total"), rowsOf(is).length]), - check("a bare value is an exact match", pick(bare.body, "total") === 250, pick(bare.body, "total")), - check("is: is case-sensitive: BAND-1 matches nothing", pick(upperIs.body, "total") === 0, pick(upperIs.body, "total")), - check("contains: ignores case: AND-2 matches the 250 rows of band-2", pick(contains.body, "total") === 250, pick(contains.body, "total")), - check("a number cell is compared as a whole value: is:100 finds one row", pick(seqIs.body, "total") === 1 && rowsOf(seqIs)[0]?.seq === 100, [pick(seqIs.body, "total"), rowsOf(seqIs)[0]?.seq]), - check("contains: on a number column compares the whole value: contains:12 finds seq 12, not 120 or 1200", pick(seqContains.body, "total") === 1 && rowsOf(seqContains)[0]?.seq === 12, [pick(seqContains.body, "total"), rowsOf(seqContains).map((row) => row.seq)]), - check("an unknown mode filters nothing", pick(unknownMode.body, "total") === 1250, pick(unknownMode.body, "total")), - check("an empty value filters nothing", pick(empty.body, "total") === 1250, pick(empty.body, "total")), - check("only the first colon splits the mode: contains:band-1:x matches nothing", pick(colon.body, "total") === 0, pick(colon.body, "total")), - check("search ignores case and counts 250 rows", pick(search.body, "total") === 250, pick(search.body, "total")), - check("search reads the id cell too: R_0042 finds r_0042", pick(searchId.body, "total") === 1 && rowsOf(searchId)[0]?._id === "r_0042", [pick(searchId.body, "total"), rowsOf(searchId)[0]?._id]), - check("search compares a number cell as a whole value: 1250 finds the seq 1250 row", rowsOf(searchNumber).some((row) => row.seq === 1250), ids(rowsOf(searchNumber))), - check("search and a filter combine: band-1 and contains:6 find seq 6, band-2 and contains:6 find nothing", pick(both.body, "total") === 1 && rowsOf(both)[0]?.seq === 6 && pick(bothApart.body, "total") === 0, [pick(both.body, "total"), rowsOf(both).map((row) => row.seq), pick(bothApart.body, "total")]), - check("two filters both apply", pick(twoFilters.body, "total") === 1 && rowsOf(twoFilters)[0]?.seq === 1, [pick(twoFilters.body, "total"), rowsOf(twoFilters).map((row) => row.seq)]), - check("a filtered page sorts descending by seq", show(rowsOf(sortedFiltered).map((row) => row.seq)) === "[1247,1242]", rowsOf(sortedFiltered).map((row) => row.seq)), - check("no match answers no row and a total of 0", rowsOf(none).length === 0 && pick(none.body, "total") === 0, [rowsOf(none).length, pick(none.body, "total")]), - ]); - }, -}; - -/** @type {{ id: string, title: string, entryPoint: string, run: (ctx: Ctx) => Promise }} */ -const selectionDecoding = { - id: "the-selection-decodes-schema-table-and-instance", - title: "filter_schema, filter_table and filter_instance take is: or a bare value; a missing one answers 400, an unknown schema or table 404; the instance is the default one when absent or empty, a named one, or every instance for the cross-instance token, and any other mode is the default instance", - entryPoint: "GET /api/database/browse/count, columns, tables, get", - async run(/** @type {Ctx} */ ctx) { - const defaultCount = await browse(ctx, "customers in the default instance", "count", "shop.customers"); - const euCount = await browse(ctx, "customers in eu", "count", "shop.customers", { filter_instance: "is:eu" }); - const usCount = await browse(ctx, "customers in us", "count", "shop.customers", { filter_instance: "is:us" }); - const allCount = await browse(ctx, "customers in every instance", "count", "shop.customers", { filter_instance: `is:${ALL}` }); - const emptyInstance = await browse(ctx, "an empty instance", "count", "shop.customers", { filter_instance: "is:" }); - const containsInstance = await browse(ctx, "a contains instance", "count", "shop.customers", { filter_instance: "contains:eu" }); - const bareInstance = await browse(ctx, "a bare instance", "count", "shop.customers", { filter_instance: "eu" }); - const unknownInstance = await browse(ctx, "an unknown instance", "count", "shop.customers", { filter_instance: "is:nowhere" }); - const noSchema = await db(ctx, "no schema", "GET", "/browse/count?filter_table=is:customers"); - const noTable = await db(ctx, "no table", "GET", "/browse/count?filter_schema=is:shop"); - const containsSchema = await db(ctx, "schema in contains mode", "GET", "/browse/count?filter_schema=contains:shop&filter_table=is:customers"); - const bareSchema = await db(ctx, "schema without a mode", "GET", "/browse/count?filter_schema=shop&filter_table=customers&filter_instance=is:eu"); - const unknownSchema = await browse(ctx, "an unknown schema", "count", "nowhere.customers"); - const unknownTable = await browse(ctx, "an unknown table", "count", "shop.nowhere"); - const allRows = await browse(ctx, "every instance's customers", "list", "shop.customers", { filter_instance: `is:${ALL}`, limit: 200, sortKey: "_id" }); - const euRows = await browse(ctx, "eu's customers", "list", "shop.customers", { filter_instance: "is:eu", limit: 3, sortKey: "_id" }); - const instancesOfAll = new Set(rowsOf(allRows).map((row) => row._instance)); - await ctx.verify("the selection", [ - check("the default instance holds no customer", pick(defaultCount.body, "total") === 0, defaultCount.body), - check("eu holds 24 and us holds 24", pick(euCount.body, "total") === 24 && pick(usCount.body, "total") === 24, [euCount.body, usCount.body]), - check("the cross-instance token counts 48", pick(allCount.body, "total") === 48, allCount.body), - check("an empty instance is the default instance", pick(emptyInstance.body, "total") === 0, emptyInstance.body), - check("only is: selects an instance: contains:eu reads the default one", pick(containsInstance.body, "total") === 0, containsInstance.body), - check("a bare instance value is exact", pick(bareInstance.body, "total") === 24, bareInstance.body), - check("an unknown instance is refused or empty, never another instance's rows", unknownInstance.status !== 200 || pick(unknownInstance.body, "total") === 0, [unknownInstance.status, unknownInstance.body]), - check("a missing schema is 400 and a missing table is 400", noSchema.status === 400 && noTable.status === 400, [noSchema.status, msg(noSchema), noTable.status, msg(noTable)]), - check("the 400 names the missing filter", /schema/i.test(msg(noSchema)) && /table/i.test(msg(noTable)), [noSchema.body, noTable.body]), - check("a schema in contains mode is missing: 400", containsSchema.status === 400, containsSchema.status), - check("a bare schema and table are accepted", bareSchema.status === 200 && pick(bareSchema.body, "total") === 24, [bareSchema.status, bareSchema.body]), - check("an unknown schema is 404", unknownSchema.status === 404 && /Unknown schema: nowhere/.test(msg(unknownSchema)), [unknownSchema.status, unknownSchema.body]), - check("an unknown table is 404", unknownTable.status === 404 && /Unknown table: nowhere/.test(msg(unknownTable)), [unknownTable.status, unknownTable.body]), - check("the cross-instance rows are the rows of eu and of us, tagged with _instance", rowsOf(allRows).length === 48 && instancesOfAll.size === 2 && instancesOfAll.has("eu") && instancesOfAll.has("us"), [rowsOf(allRows).length, [...instancesOfAll]]), - check("a single instance's rows are tagged with that instance", rowsOf(euRows).length === 3 && rowsOf(euRows).every((row) => row._instance === "eu") && show(ids(rowsOf(euRows))) === '["eu_cus_000","eu_cus_001","eu_cus_002"]', ids(rowsOf(euRows))), - ]); - }, -}; - -export const browseApiJourneys = [instancesRoute, listClampsLimitAndOffset, listFiltersAndSearch, selectionDecoding, columnsGetAndTables, referencesCount, ownerOnly]; diff --git a/e2e/journeys/parts/browse.mjs b/e2e/journeys/parts/browse.mjs index 690793f..5c0237e 100644 --- a/e2e/journeys/parts/browse.mjs +++ b/e2e/journeys/parts/browse.mjs @@ -10,9 +10,6 @@ import { db, isRow, list } from "../../database.mjs"; /** The data browser page. */ export const DATA_PAGE = "/modules/database/data"; -/** The wire token of the cross-instance selection. */ -export const ALL = "__CROSS_INSTANCE__"; - /** * The query string of a browse request. * diff --git a/src/test/data-reads.journeys.test.ts b/src/test/data-reads.journeys.test.ts new file mode 100644 index 0000000..9793c6c --- /dev/null +++ b/src/test/data-reads.journeys.test.ts @@ -0,0 +1,354 @@ +import { strict as assert } from "node:assert"; +import { + ALL, + column, + CUSTOMERS, + type DataApi, + DEMO, + message, + METRICS, + rowsOf, + SHOP, + withDataFixture, +} from "./dataJourneys"; +import { objectsAt, pick, text } from "./helpers/pick"; +import type { HttpAnswer } from "./helpers/http"; + +async function assertSelectionDecoding(api: DataApi): Promise { + const count = async (params: Record) => + pick((await api.browse("count", CUSTOMERS, params)).body, "total"); + assert.deepEqual( + { + default: await count({}), + eu: await count({ filter_instance: "is:eu" }), + us: await count({ filter_instance: "is:us" }), + all: await count({ filter_instance: `is:${ALL}` }), + empty: await count({ filter_instance: "is:" }), + contains: await count({ filter_instance: "contains:eu" }), + bare: await count({ filter_instance: "eu" }), + }, + { + default: 0, + eu: 24, + us: 24, + all: 48, + empty: 0, + contains: 0, + bare: 24, + }, + "the instance is the default one when absent, empty or not is:, a named one, or every one for the cross-instance token", + ); + const unknownInstance = await api.browse("count", CUSTOMERS, { + filter_instance: "is:nowhere", + }); + assert.ok( + unknownInstance.status !== 200 || pick(unknownInstance.body, "total") === 0, + `an unknown instance is refused or empty, never another instance's rows: ${unknownInstance.text}`, + ); + const noSchema = await api.get("/browse/count?filter_table=is:customers"); + const noTable = await api.get(`/browse/count?filter_schema=is:${SHOP}`); + assert.deepEqual( + [noSchema.status, noTable.status], + [400, 400], + "a missing schema or table is 400", + ); + assert.match(message(noSchema), /schema/i, "the 400 names the schema"); + assert.match(message(noTable), /table/i, "the 400 names the table"); + const containsSchema = await api.get( + `/browse/count?filter_schema=contains:${SHOP}&filter_table=is:customers`, + ); + assert.equal(containsSchema.status, 400, "a contains: schema is missing"); + const bare = await api.get( + `/browse/count?filter_schema=${SHOP}&filter_table=customers&filter_instance=is:eu`, + ); + assert.deepEqual( + [bare.status, pick(bare.body, "total")], + [200, 24], + "a bare schema and table are accepted", + ); + const unknownSchema = await api.browse("count", "nowhere.customers"); + const unknownTable = await api.browse("count", `${SHOP}.nowhere`); + assert.deepEqual( + [ + [unknownSchema.status, message(unknownSchema)], + [unknownTable.status, message(unknownTable)], + ], + [ + [404, "Unknown schema: nowhere"], + [404, "Unknown table: nowhere"], + ], + "an unknown schema or table is 404", + ); + const allRows = await api.browse("list", CUSTOMERS, { + filter_instance: `is:${ALL}`, + limit: 200, + sortKey: "_id", + }); + assert.deepEqual( + { + rows: rowsOf(allRows).length, + instances: new Set(column(allRows, "_instance")), + }, + { rows: 48, instances: new Set(["eu", "us"]) }, + "the cross-instance rows are those of eu and us, tagged with _instance", + ); + const euRows = await api.browse("list", CUSTOMERS, { + filter_instance: "is:eu", + limit: 3, + sortKey: "_id", + }); + assert.deepEqual( + { + ids: column(euRows, "_id"), + instances: column(euRows, "_instance"), + }, + { + ids: ["eu_cus_000", "eu_cus_001", "eu_cus_002"], + instances: ["eu", "eu", "eu"], + }, + "a single instance's rows are tagged with that instance", + ); +} + +async function assertColumnsAndTypes(api: DataApi): Promise { + const columns = await api.browse("columns", `${SHOP}.orders`, { + filter_instance: "is:eu", + }); + assert.deepEqual( + pick(columns.body, "columns"), + [ + "_id", + "number", + "customer_id", + "status", + "created_at", + "channel", + "total", + "currency", + "coupon_id", + "shipping", + "_instance", + ], + "a column list in sample order, or with the instance tag among the declared columns", + ); + const types = pick(columns.body, "types"); + assert.deepEqual( + { + primaryKey: pick(columns.body, "primaryKey"), + total: pick(types, "total"), + status: pick(types, "status"), + shipping: pick(types, "shipping"), + created_at: pick(types, "created_at"), + coupon_id: pick(types, "coupon_id"), + }, + { + primaryKey: "_id", + total: "number", + status: "string", + shipping: "object", + created_at: "date", + coupon_id: "string", + }, + "the types name each column's runtime type, and a null cell takes the type of a later row", + ); + const customers = await api.browse("columns", CUSTOMERS, { + filter_instance: "is:eu", + }); + assert.deepEqual( + [ + pick(customers.body, "types", "vip"), + pick(customers.body, "types", "credit_limit"), + ], + ["boolean", "number"], + "customers: a boolean and a number column", + ); + const empty = await api.browse("columns", `${METRICS}.empty_log`); + assert.deepEqual( + pick(empty.body, "columns"), + [], + "an empty table has no sampled column", + ); +} + +async function assertRowsAndTables(api: DataApi): Promise { + const ORDERS = `${SHOP}.orders`; + const row = await api.browse("get", ORDERS, { + filter_instance: "is:eu", + id: "eu_ord_10400", + }); + assert.deepEqual( + { + _id: pick(row.body, "_id"), + number: pick(row.body, "number"), + customer_id: pick(row.body, "customer_id"), + carrier: pick(row.body, "shipping", "carrier"), + }, + { + _id: "eu_ord_10400", + number: "#10400", + customer_id: "eu_cus_000", + carrier: "DHL", + }, + "get answers the stored row", + ); + const otherInstance = await api.browse("get", ORDERS, { + filter_instance: "is:us", + id: "eu_ord_10400", + }); + assert.deepEqual( + [otherInstance.status, message(otherInstance)], + [404, "Row not found"], + "get reads the instance asked: the id of eu is not in us", + ); + assert.deepEqual( + [ + ( + await api.browse("get", ORDERS, { + filter_instance: "is:eu", + id: "nope", + }) + ).status, + (await api.browse("get", ORDERS, { filter_instance: "is:eu" })).status, + ], + [404, 400], + "get of a missing id is 404, without an id 400", + ); + const counts = async (query: string) => + Object.fromEntries( + objectsAt((await api.get(`/browse/tables?${query}`)).body, "items").map( + (item) => [text(item.name), item.elementCount ?? null], + ), + ); + assert.deepEqual( + { + eu: await counts(`filter_schema=is:${SHOP}&filter_instance=is:eu`), + default: await counts(`filter_schema=is:${SHOP}`), + all: await counts(`filter_schema=is:${SHOP}&filter_instance=is:${ALL}`), + metrics: await counts(`filter_schema=is:${METRICS}`), + }, + { + eu: { customers: 24, products: 6, orders: 80, order_items: 160 }, + default: { customers: 0, products: 6, orders: 0, order_items: 0 }, + all: { customers: 48, products: 18, orders: 160, order_items: 320 }, + metrics: { readings: 1250, empty_log: 0 }, + }, + "tables count the rows of the picked instance, or of every instance for the cross-instance token", + ); + const noSchema = await api.get("/browse/tables"); + const unknown = await api.get("/browse/tables?filter_schema=is:nowhere"); + assert.deepEqual( + [noSchema.status, unknown.status, message(unknown)], + [400, 404, "Unknown schema: nowhere"], + "tables without a schema is 400, an unknown schema 404", + ); +} + +async function assertReferencesCount(api: DataApi): Promise { + const references = ( + target: string, + params: Record, + ): Promise => api.browse("references", target, params); + const summary = (answer: HttpAnswer) => + Object.fromEntries( + objectsAt(answer.body, "items").map((item) => [ + `${text(item.table)}.${text(item.field)}`, + item.count ?? null, + ]), + ); + const order = await references(`${SHOP}.orders`, { + filter_instance: "is:eu", + id: "eu_ord_10400", + }); + assert.deepEqual( + [summary(order), pick(order.body, "items", 0, "many")], + [{ "order_items.order_id": 2 }, false], + "an order is pointed at by two order_items.order_id, not many", + ); + assert.deepEqual( + { + customer: summary( + await references(CUSTOMERS, { + filter_instance: "is:eu", + id: "eu_cus_000", + }), + ), + customerUs: summary( + await references(CUSTOMERS, { + filter_instance: "is:us", + id: "us_cus_001", + }), + ), + product: summary( + await references(`${SHOP}.products`, { + filter_instance: "is:eu", + id: "eu_sku_desk", + }), + ), + defaultProduct: summary( + await references(`${SHOP}.products`, { id: "sku_desk" }), + ), + items: pick( + ( + await references(`${SHOP}.order_items`, { + filter_instance: "is:eu", + id: "eu_itm_0", + }) + ).body, + "items", + ), + }, + { + customer: { "orders.customer_id": 4 }, + customerUs: { "orders.customer_id": 4 }, + product: { "order_items.product_id": 27 }, + defaultProduct: { "order_items.product_id": 0 }, + items: [], + }, + "references count the rows of the same instance only, and a table nothing points to answers an empty list", + ); + const everywhere = await references(`${SHOP}.orders`, { + filter_instance: `is:${ALL}`, + id: "eu_ord_10400", + }); + assert.equal(everywhere.status, 400, "every instance is refused"); + assert.match(message(everywhere), /Pick one instance/); + assert.deepEqual( + [ + (await references(`${SHOP}.orders`, { filter_instance: "is:eu" })).status, + ( + await references(`${SHOP}.orders`, { + filter_instance: "is:eu", + id: "nope", + }) + ).status, + (await references(`${DEMO}.tags`, { id: "none" })).status, + (await references(`${DEMO}.posts`, { id: "none" })).status, + ], + [400, 404, 404, 404], + "a missing id is 400, a missing row 404", + ); + const tagRefs = await references(`${DEMO}.tags`, { id: "follow-up" }); + assert.deepEqual( + [summary(tagRefs), pick(tagRefs.body, "items", 0, "many")], + [{ "posts.tag_ids": 0 }, true], + "a many relation (posts.tag_ids -> tags) is counted with includes", + ); + assert.ok( + "comments.post" in + summary(await references(`${DEMO}.posts`, { id: "first-post" })), + "a post is pointed at by comments.post", + ); +} + +describe("[integration] data journeys: reads", () => { + const api = withDataFixture("data-reads-journeys-owner@example.test"); + + it("the-selection-decodes-schema-table-and-instance", () => + assertSelectionDecoding(api())); + it("columns-get-and-tables-answer-what-the-grid-needs", async () => { + await assertColumnsAndTypes(api()); + await assertRowsAndTables(api()); + }); + it("references-count-the-rows-pointing-at-a-row", () => + assertReferencesCount(api())); +}); diff --git a/src/test/data.journeys.test.ts b/src/test/data.journeys.test.ts new file mode 100644 index 0000000..153e66c --- /dev/null +++ b/src/test/data.journeys.test.ts @@ -0,0 +1,337 @@ +import { strict as assert } from "node:assert"; +import { + column, + type DataApi, + METRICS, + READINGS, + rowsOf, + SHOP, + withDataFixture, +} from "./dataJourneys"; +import { callDatabase } from "./helpers/http"; +import { pick } from "./helpers/pick"; +import { createMemberSession } from "./ownerSession"; + +async function assertInstancePicker(api: DataApi): Promise { + const instances = async (query: string) => { + const answer = await api.get(`/tables/instances?${query}`); + return { + status: answer.status, + instances: pick(answer.body, "instances"), + total: pick(answer.body, "total"), + }; + }; + assert.deepEqual( + { + all: await instances(`schema=${SHOP}`), + searched: await instances(`schema=${SHOP}&search=US`), + both: await instances(`schema=${SHOP}&search=u`), + none: await instances(`schema=${SHOP}&search=zzz`), + limited: await instances(`schema=${SHOP}&limit=1`), + zero: await instances(`schema=${SHOP}&limit=0`), + metrics: await instances(`schema=${METRICS}`), + }, + { + all: { status: 200, instances: ["eu", "us"], total: 2 }, + searched: { status: 200, instances: ["us"], total: 1 }, + both: { status: 200, instances: ["eu", "us"], total: 2 }, + none: { status: 200, instances: [], total: 0 }, + limited: { status: 200, instances: ["eu"], total: 2 }, + zero: { status: 200, instances: ["eu"], total: 2 }, + metrics: { status: 200, instances: [], total: 0 }, + }, + "a case-sensitive search, a limit that also cuts the total, an unsorted list or a limit of 0 kept at 0", + ); + assert.deepEqual( + [ + (await api.get("/tables/instances")).status, + (await api.get("/tables/instances?schema=nowhere")).status, + ], + [400, 404], + "a missing schema answered 200, or an unknown one read as empty", + ); +} + +async function assertListClamps(api: DataApi): Promise { + const page = async (params: Record) => { + const answer = await api.browse("list", READINGS, params); + return { + rows: rowsOf(answer).length, + limit: pick(answer.body, "limit"), + }; + }; + const base = await api.browse("list", READINGS); + assert.deepEqual( + { + rows: rowsOf(base).length, + limit: pick(base.body, "limit"), + offset: pick(base.body, "offset"), + total: pick(base.body, "total"), + primaryKey: pick(base.body, "primaryKey"), + }, + { rows: 25, limit: 25, offset: 0, total: 1250, primaryKey: "_id" }, + "no limit answers 25 rows, offset 0, the exact total and the primary key", + ); + assert.deepEqual( + { + 500: await page({ limit: 500 }), + 200: await page({ limit: 200 }), + 199: await page({ limit: 199 }), + 201: await page({ limit: 201 }), + 0: await page({ limit: 0 }), + "-7": await page({ limit: -7 }), + abc: await page({ limit: "abc" }), + }, + { + 500: { rows: 200, limit: 200 }, + 200: { rows: 200, limit: 200 }, + 199: { rows: 199, limit: 199 }, + 201: { rows: 200, limit: 200 }, + 0: { rows: 1, limit: 1 }, + "-7": { rows: 1, limit: 1 }, + abc: { rows: 25, limit: 25 }, + }, + "limit is clamped to 1..200 and falls back to 25 when it is no number", + ); + const negativeOffset = await api.browse("list", READINGS, { + offset: -3, + limit: 5, + sortKey: "seq", + }); + assert.deepEqual( + { + offset: pick(negativeOffset.body, "offset"), + seqs: column(negativeOffset, "seq"), + }, + { offset: 0, seqs: [1, 2, 3, 4, 5] }, + "a negative offset starts at the first row", + ); + const last = await api.browse("list", READINGS, { + offset: 1200, + limit: 200, + sortKey: "seq", + }); + const lastSeqs = column(last, "seq"); + assert.deepEqual( + { + rows: lastSeqs.length, + first: lastSeqs[0], + last: lastSeqs.at(-1), + total: pick(last.body, "total"), + }, + { rows: 50, first: 1201, last: 1250, total: 1250 }, + "offset 1200 at 200 rows answers the last 50 rows", + ); + const past = await api.browse("list", READINGS, { + offset: 1250, + limit: 25, + sortKey: "seq", + }); + assert.deepEqual( + { rows: rowsOf(past).length, total: pick(past.body, "total") }, + { rows: 0, total: 1250 }, + "an offset past the end answers no row and the total", + ); + const seqs = async (sortDirection: string) => + column( + await api.browse("list", READINGS, { + sortKey: "seq", + limit: 3, + sortDirection, + }), + "seq", + ); + assert.deepEqual( + { + asc: column( + await api.browse("list", READINGS, { sortKey: "seq", limit: 3 }), + "seq", + ), + desc: await seqs("desc"), + DESC: await seqs("DESC"), + up: await seqs("up"), + }, + { + asc: [1, 2, 3], + desc: [1250, 1249, 1248], + DESC: [1, 2, 3], + up: [1, 2, 3], + }, + "only the word desc sorts descending", + ); + const noKey = await api.browse("list", READINGS, { + sortDirection: "desc", + limit: 2, + }); + assert.deepEqual( + column(noKey, "_id"), + column(base, "_id").slice(0, 2), + "a direction without a sort key keeps the stored order", + ); +} + +async function assertListFilters(api: DataApi): Promise { + const total = async (params: Record) => + pick((await api.browse("list", READINGS, params)).body, "total"); + const band1 = await api.browse("list", READINGS, { + filter_band: "is:band-1", + limit: 200, + sortKey: "seq", + }); + assert.deepEqual( + { + total: pick(band1.body, "total"), + rows: rowsOf(band1).length, + bands: [...new Set(column(band1, "band"))], + }, + { total: 250, rows: 200, bands: ["band-1"] }, + "is:band-1 matches the 250 rows of band-1", + ); + assert.deepEqual( + { + bare: await total({ filter_band: "band-1", limit: 1 }), + upperIs: await total({ filter_band: "is:BAND-1", limit: 1 }), + contains: await total({ filter_band: "contains:AND-2", limit: 1 }), + unknownMode: await total({ filter_band: "starts:band", limit: 1 }), + empty: await total({ filter_band: "", limit: 1 }), + colon: await total({ filter_band: "contains:band-1:x", limit: 1 }), + search: await total({ search: "BAND-3", limit: 1 }), + none: await total({ search: "zzz-no-such-text" }), + }, + { + bare: 250, + upperIs: 0, + contains: 250, + unknownMode: 1250, + empty: 1250, + colon: 0, + search: 250, + none: 0, + }, + "a bare value is exact, is: is case-sensitive, contains: is not, an unknown mode or empty value filters nothing, only the first colon splits, search ignores case", + ); + const seqIs = await api.browse("list", READINGS, { filter_seq: "is:100" }); + const seqContains = await api.browse("list", READINGS, { + filter_seq: "contains:12", + limit: 200, + }); + assert.deepEqual( + { + is: [pick(seqIs.body, "total"), column(seqIs, "seq")], + contains: [pick(seqContains.body, "total"), column(seqContains, "seq")], + }, + { is: [1, [100]], contains: [1, [12]] }, + "a number cell is compared as a whole value: contains:12 finds 12, not 120 or 1200", + ); + const searchId = await api.browse("list", READINGS, { search: "R_0042" }); + assert.deepEqual( + [pick(searchId.body, "total"), column(searchId, "_id")], + [1, ["r_0042"]], + "search reads the id cell, ignoring case", + ); + const searchNumber = await api.browse("list", READINGS, { + search: "1250", + limit: 5, + }); + assert.ok( + column(searchNumber, "seq").includes(1250), + `search compares a number cell as a whole value: ${searchNumber.text}`, + ); + const both = await api.browse("list", READINGS, { + search: "band-1", + filter_seq: "contains:6", + limit: 5, + }); + const twoFilters = await api.browse("list", READINGS, { + filter_band: "is:band-1", + filter_seq: "is:1", + limit: 5, + }); + assert.deepEqual( + { + both: [pick(both.body, "total"), column(both, "seq")], + apart: await total({ + search: "band-2", + filter_seq: "contains:6", + limit: 5, + }), + twoFilters: [pick(twoFilters.body, "total"), column(twoFilters, "seq")], + }, + { both: [1, [6]], apart: 0, twoFilters: [1, [1]] }, + "a search and filters combine, and the total counts the rows they all match", + ); + assert.deepEqual( + column( + await api.browse("list", READINGS, { + filter_band: "is:band-2", + sortKey: "seq", + sortDirection: "desc", + limit: 2, + }), + "seq", + ), + [1247, 1242], + "a filtered page sorts descending by seq", + ); +} + +async function assertOwnerOnly(api: DataApi): Promise { + const reader = await createMemberSession("data-journeys-reader@example.test"); + try { + const selection = `filter_schema=is:${SHOP}&filter_table=is:products`; + const paths = [ + `/browse/list?${selection}`, + `/browse/count?${selection}`, + `/browse/columns?${selection}`, + `/browse/tables?filter_schema=is:${SHOP}`, + `/browse/get?${selection}&id=sku_desk`, + `/browse/references?${selection}&id=sku_desk`, + `/tables/instances?schema=${SHOP}`, + ]; + const anonymous: number[] = []; + const member: number[] = []; + for (const path of paths) { + anonymous.push((await callDatabase(null, "GET", path)).status); + member.push((await callDatabase(reader, "GET", path)).status); + } + assert.deepEqual( + { anonymous, member }, + { + anonymous: paths.map(() => 401), + member: paths.map(() => 403), + }, + "a browse route that skips the owner gate answers a visitor or a member", + ); + const edit = `/browse/edit?${selection}&id=sku_desk`; + assert.deepEqual( + [ + (await callDatabase(null, "PUT", edit, { name: "Hacked" })).status, + (await callDatabase(reader, "PUT", edit, { name: "Hacked" })).status, + ], + [401, 403], + "an edit by a visitor or a member is refused", + ); + assert.equal( + pick( + (await api.browse("get", `${SHOP}.products`, { id: "sku_desk" })).body, + "name", + ), + "Standing desk", + "a refused edit still wrote the row", + ); + } finally { + await reader.remove(); + } +} + +describe("[integration] data journeys", () => { + const api = withDataFixture("data-journeys-owner@example.test"); + + it("the-instance-picker-lists-named-instances-with-a-search-and-a-limit", () => + assertInstancePicker(api())); + it("list-clamps-the-page-and-orders-the-rows", () => assertListClamps(api())); + it("list-filters-search-and-counts-follow-the-wire-tokens", () => + assertListFilters(api())); + it("the-browse-api-answers-the-platform-owner-only", () => + assertOwnerOnly(api())); +}); diff --git a/src/test/dataJourneys.ts b/src/test/dataJourneys.ts new file mode 100644 index 0000000..374d219 --- /dev/null +++ b/src/test/dataJourneys.ts @@ -0,0 +1,328 @@ +import { strict as assert } from "node:assert"; +import { Schema } from "@antelopejs/interface-database"; +import { + Field, + Index, + RegisterSchema, + RegisterTable, + Relation, + Table, +} from "@antelopejs/interface-database-decorators"; +import type { JsonObject, JsonValue } from "../types/json"; +import { isString } from "../utils/guards"; +import { callDatabase, type HttpAnswer } from "./helpers/http"; +import { objectsAt, pick } from "./helpers/pick"; +import { createOwnerSession, type OwnerSession } from "./ownerSession"; + +/** + * The data the data journeys read, as the e2e playground's `shop`, `metrics` and `demo` schemas hold it: a shop with + * an `eu` and a `us` instance and products in its default one, 1,250 readings and an empty table, and posts whose + * tags and comments point at them. + */ +export const SHOP = "data-journeys-shop"; +export const METRICS = "data-journeys-metrics"; +export const DEMO = "data-journeys-demo"; +export const ALL = "__CROSS_INSTANCE__"; +export const READINGS = `${METRICS}.readings`; +export const CUSTOMERS = `${SHOP}.customers`; +const REGIONS = ["eu", "us"] as const; +const CUSTOMERS_PER_REGION = 24; +const ORDERS_PER_REGION = 80; +const READING_COUNT = 1250; +const STATUSES = ["pending", "paid", "refunded", "failed"] as const; +const CHANNELS = ["web", "marketplace", "email", "phone"] as const; +const CARRIERS = ["DHL", "UPS", "La Poste"] as const; +const COMPANIES = ["Northwind Traders", "Contoso", "Fabrikam", "Globex"]; +const DAY_MS = 86_400_000; +const PRODUCTS = [ + ["sku_desk", "Standing desk", 640], + ["sku_chair", "Task chair", 320], + ["sku_lamp", "Desk lamp", 48], + ["sku_monitor", "27-inch monitor", 289], + ["sku_keyboard", "Mechanical keyboard", 129], + ["sku_dock", "USB-C dock", 179], +] as const; + +@RegisterTable("customers", SHOP) +class DataJourneysCustomer extends Table { + declare _id: string; + @Index() declare email: string; + declare company: string; + declare credit_limit: number; + declare vip: boolean; +} + +@RegisterTable("products", SHOP) +class DataJourneysProduct extends Table { + declare _id: string; + @Index() declare name: string; + declare price: number; + declare tags: string[]; +} + +@RegisterTable("orders", SHOP) +class DataJourneysOrder extends Table { + declare _id: string; + @Index() declare number: string; + @Index() + @Relation({ to: () => DataJourneysCustomer }) + declare customer_id: string; + @Index({ group: "status_created" }) declare status: string; + declare channel: string; + declare total: number; + declare currency: string; + declare coupon_id: string | null; + declare shipping: Record; + @Index({ group: "status_created" }) declare created_at: Date; +} + +@RegisterTable("order_items", SHOP) +class DataJourneysOrderItem extends Table { + declare _id: string; + @Index() @Relation({ to: () => DataJourneysOrder }) declare order_id: string; + @Relation({ to: () => DataJourneysProduct }) declare product_id: string; + declare quantity: number; + declare unit_price: number; +} + +@RegisterTable("readings", METRICS) +class DataJourneysReading extends Table { + @Field("string") declare _id: string; + @Index() @Field("number") declare seq: number; + @Field("string") declare band: string; + @Field("number") declare value: number; +} + +@RegisterTable("empty_log", METRICS) +class DataJourneysEmptyLog extends Table { + @Field("string") declare _id: string; + @Field("string") declare message: string; +} + +@RegisterTable("tags", DEMO) +class DataJourneysTag extends Table { + declare _id: string; + @Index() declare name: string; +} + +@RegisterTable("posts", DEMO) +class DataJourneysPost extends Table { + declare _id: string; + @Index() declare title: string; + @Relation({ to: () => DataJourneysTag, many: true }) + declare tag_ids: string[]; +} + +@RegisterTable("comments", DEMO) +class DataJourneysComment extends Table { + declare _id: string; + @Index() @Relation({ to: () => DataJourneysPost }) declare post: string; + declare body: string; +} + +/** Keeps the decorated classes referenced: the decorators register them. */ +const TABLES = [ + DataJourneysCustomer, + DataJourneysProduct, + DataJourneysOrder, + DataJourneysOrderItem, + DataJourneysReading, + DataJourneysEmptyLog, + DataJourneysTag, + DataJourneysPost, + DataJourneysComment, +]; + +function cycle(values: readonly T[], index: number): T { + const value = values[index % values.length]; + assert.ok(value !== undefined); + return value; +} + +function customerId(region: string, index: number): string { + return `${region}_cus_${String(index % CUSTOMERS_PER_REGION).padStart(3, "0")}`; +} + +function productId(region: string | undefined, sku: string): string { + return region ? `${region}_${sku}` : sku; +} + +function products(region?: string) { + return PRODUCTS.map(([sku, name, price], index) => ({ + _id: productId(region, sku), + name, + price, + tags: index % 2 === 0 ? ["office", "bestseller"] : ["office"], + })); +} + +/** The rows of one region of the shop: every order has two items, the n-th customer every 24th order. */ +function region(name: string, now: number) { + return { + customers: Array.from({ length: CUSTOMERS_PER_REGION }, (_, index) => ({ + _id: customerId(name, index), + email: `buyer${index}@shop.test`, + company: cycle(COMPANIES, index), + credit_limit: 1000 + (index % 5) * 500, + vip: index % 7 === 0, + })), + products: products(name), + orders: Array.from({ length: ORDERS_PER_REGION }, (_, index) => ({ + _id: `${name}_ord_${10400 + index}`, + number: `#${10400 + index}`, + customer_id: customerId(name, index), + status: cycle(STATUSES, index * 3), + channel: cycle(CHANNELS, index), + total: 50 + ((index * 137) % 3000), + currency: name === "eu" ? "EUR" : "USD", + coupon_id: index % 9 === 0 ? "cpn_AUTUMN10" : null, + shipping: { carrier: cycle(CARRIERS, index) }, + created_at: new Date(now - index * DAY_MS), + })), + order_items: Array.from({ length: ORDERS_PER_REGION * 2 }, (_, index) => { + const [sku, , price] = cycle(PRODUCTS, index); + return { + _id: `${name}_itm_${index}`, + order_id: `${name}_ord_${10400 + Math.floor(index / 2)}`, + product_id: productId(name, sku), + quantity: 1 + (index % 3), + unit_price: price, + }; + }), + }; +} + +function registered(id: string) { + const schema = Schema.get(id); + assert.ok(schema, `${id} is registered`); + return schema; +} + +async function seed(): Promise { + assert.equal(TABLES.length, 9); + for (const id of [SHOP, METRICS, DEMO]) await RegisterSchema(id); + const shop = registered(SHOP); + const now = Date.now(); + for (const name of REGIONS) { + await shop + .createInstance(name) + .run() + .catch(() => undefined); + for (const [table, rows] of Object.entries(region(name, now))) { + await shop.instance(name).table(table).insert(rows).run(); + } + } + await shop.instance().table("products").insert(products()).run(); + await registered(METRICS) + .instance() + .table("readings") + .insert( + Array.from({ length: READING_COUNT }, (_, index) => ({ + _id: `r_${String(index + 1).padStart(4, "0")}`, + seq: index + 1, + band: `band-${(index % 5) + 1}`, + value: (index * 7) % 101, + })), + ) + .run(); + const demo = registered(DEMO).instance(); + await demo + .table("tags") + .insert(["intro", "follow-up", "rant"].map((name) => ({ _id: name, name }))) + .run(); + await demo + .table("posts") + .insert([ + { _id: "first-post", title: "First post", tag_ids: [] }, + { _id: "second-post", title: "Second post", tag_ids: [] }, + ]) + .run(); + await demo + .table("comments") + .insert([ + { _id: "c1", post: "first-post", body: "Nice!" }, + { _id: "c2", post: "first-post", body: "Agreed." }, + ]) + .run(); +} + +async function unseed(): Promise { + const shop = registered(SHOP); + for (const name of REGIONS) await shop.destroyInstance(name).run(); + for (const [id, tables] of [ + [SHOP, ["customers", "products", "orders", "order_items"]], + [METRICS, ["readings", "empty_log"]], + [DEMO, ["tags", "posts", "comments"]], + ] as const) { + for (const table of tables) { + await registered(id).instance().table(table).delete().run(); + } + } +} + +/** The browse API as the owner of a seeded data fixture calls it. */ +export interface DataApi { + /** Calls a browse route on `schema.table` (or `schema`), with `params` after the selection. */ + browse( + route: string, + target: string, + params?: Record, + ): Promise; + /** Calls `path` under `/api/database`. */ + get(path: string): Promise; +} + +/** + * Seeds the fixture before the suite it is called in and removes it after, and gives its journeys the browse API + * as an owner signed in for the suite. + */ +export function withDataFixture(email: string): () => DataApi { + let owner: OwnerSession | undefined; + before(async () => { + await seed(); + owner = await createOwnerSession(email); + }); + after(async () => { + await owner?.remove(); + await unseed(); + }); + return () => { + const session = owner; + assert.ok(session, "the suite's before hook signed the owner in"); + return { + browse(route, target, params = {}) { + const [schema = "", table] = target.split("."); + const query = new URLSearchParams({ filter_schema: `is:${schema}` }); + if (table !== undefined) query.set("filter_table", `is:${table}`); + for (const [key, value] of Object.entries(params)) { + query.set(key, String(value)); + } + return callDatabase( + session, + "GET", + `/browse/${route}?${query.toString()}`, + ); + }, + get(path) { + return callDatabase(session, "GET", path); + }, + }; + }; +} + +/** The rows a list route answered. */ +export function rowsOf(answer: HttpAnswer): JsonObject[] { + return objectsAt(answer.body, "results"); +} + +/** One cell of each row a list route answered, `null` where the row has none. */ +export function column(answer: HttpAnswer, name: string): JsonValue[] { + return rowsOf(answer).map((row) => row[name] ?? null); +} + +/** The message of a refusal: its text body, or the `message` of its JSON body. */ +export function message(answer: HttpAnswer): string { + if (isString(answer.body)) return answer.body; + const field = pick(answer.body, "message"); + return isString(field) ? field : answer.text; +} From d6f8b9aae9ebd1fd0d8fafeee177c9f8cf60ef7f Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 08:46:45 +0000 Subject: [PATCH 09/12] test(editing): port the HTTP journey to an integration test the-edit-route-writes-typed-values-and-refuses-the-rest leaves the Playwright suite for src/test/editing.journeys.test.ts. --- .../verify-dms-database/features/README.md | 2 +- .../verify-dms-database/features/editing.md | 8 +- e2e/journeys/parts/edit-store.mjs | 74 +------ src/test/editing.journeys.test.ts | 206 ++++++++++++++++++ 4 files changed, 216 insertions(+), 74 deletions(-) create mode 100644 src/test/editing.journeys.test.ts diff --git a/.agents/skills/verify-dms-database/features/README.md b/.agents/skills/verify-dms-database/features/README.md index d3caf8c..f1275f9 100644 --- a/.agents/skills/verify-dms-database/features/README.md +++ b/.agents/skills/verify-dms-database/features/README.md @@ -11,7 +11,7 @@ One file per feature. `covers:` lists the source globs it owns, `docs:` the page | [schemas](schemas.md) | # Schemas | the-source-counts-rows-columns-indexes-relations-and-modifiers-of-each-table, schema-instance-search-and-structure-filters-narrow-the-source-and-combine, rows-are-counted-in-the-picked-instance-default-named-or-all, the-instances-route-searches-sorts-and-limits-the-named-instances-of-a-schema, a-table-is-read-by-its-schema-and-name-id, columns-are-declared-in-code-and-inferred-from-sampled-rows, the-tables-and-schemas-routes-answer-the-platform-owner-only, each-filter-of-the-bar-narrows-the-list-and-sets-its-own-url-key, the-url-restores-every-filter-after-a-reload-and-clear-removes-them, slash-focuses-the-search-field-but-not-while-typing-or-with-a-modifier, a-filter-that-matches-nothing-says-no-result-and-clear-filters-restores-the-list, each-of-the-five-sortable-columns-sorts-both-ways-and-the-third-click-restores-the-default-order, the-relations-and-modifiers-columns-name-the-tables-and-the-flags, a-row-click-opens-the-inspector-and-previous-next-j-and-k-step-through-the-list, dragging-the-drawer-edge-resizes-it-and-it-opens-at-the-width-you-left-it, the-inspector-states-the-counts-and-lists-each-column-with-its-type-null-and-notes, a-column-named-constructor-is-listed-like-any-other-column, the-indexes-and-relations-tabs-list-what-the-table-declares-and-a-relation-opens-the-other-table, the-sample-row-tab-shows-one-row-and-another-row-pages-through-the-table, browse-query-and-diagram-actions-open-the-other-pages-on-the-same-table | | [diagram](diagram.md) | # Diagram | the-layout-api-stores-one-layout-per-schema-and-refuses-bad-positions, the-notes-api-creates-lists-updates-and-deletes-notes-per-schema, the-notes-api-refuses-missing-numbers-with-400-and-unknown-notes-with-404, every-diagram-route-answers-the-platform-owner-only, tables-list-their-columns-with-types-and-icons-and-relations-are-arrows, an-encrypted-column-carries-the-lock-icon-of-the-legend, a-table-of-more-than-twelve-columns-comes-folded-and-folding-is-not-saved, folding-is-a-setting-of-your-own-view-and-is-not-saved-with-the-team-layout, finding-a-column-a-folded-table-hides-unfolds-that-table, the-fold-keeps-the-twelve-column-boundary-and-every-column-an-arrow-ends-on, a-large-schema-opens-at-forty-percent-on-its-top-left-and-fit-view-shows-it-whole, a-relation-to-a-table-not-drawn-ends-on-a-dashed-chip-that-opens-that-table, a-relation-to-another-schema-ends-on-a-chip-that-opens-that-table, the-url-picks-the-schema-and-the-table-and-names-what-it-cannot-find, a-schema-without-a-table-says-so-and-offers-no-note-or-auto-layout, dragging-a-table-saves-the-layout-and-everyone-reads-it, a-table-not-placed-yet-takes-its-automatic-place-and-placed-tables-stay, auto-layout-previews-the-arrangement-and-keep-or-discard-decides, auto-layout-keeps-groups-together-and-clear-of-notes-that-never-move, n-and-the-note-button-drop-a-note-ready-to-write-and-it-is-saved-with-the-schema, a-double-click-edits-a-note-and-the-trash-button-and-delete-remove-it, notes-belong-to-their-schema-and-everyone-reads-them, undo-and-redo-cover-every-move-and-note-and-are-saved, escape-leaves-the-find-field-then-lifts-the-focus-then-clears-the-selection | | [data](data.md) | # Data | the-sidebar-counts-each-table-in-the-picked-instance, tables-open-as-preview-tabs-and-are-kept-on-demand, links-open-the-table-in-the-instance-they-name, search-filters-and-sort-narrow-and-order-the-rows, the-footer-pages-1250-rows-with-exact-ranges-at-every-size, r-refreshes-the-rows-and-the-search-shortcut-works-from-the-grid, the-row-drawer-steps-through-the-page-with-j-and-k, the-row-drawer-shows-fields-json-and-the-rows-pointing-at-it, the-fields-tab-widens-long-values-and-sets-null-with-the-dashed-circle, all-instances-is-a-read-only-view-with-the-instance-column, recently-opened-tables-are-offered-when-no-tab-is-open, no-match-and-empty-tables-say-so, a-refused-read-shows-the-error-and-try-again-reads-it-again | -| [editing](editing.md) | # Editing | edits-are-staged-then-reviewed-then-written-one-put-per-row, invalid-drafts-are-refused-esc-cancels-and-a-click-away-decides, null-empties-a-cell-and-backslash-null-is-the-text-null, object-and-array-cells-open-the-json-editor-in-a-side-drawer, the-json-editor-is-as-tall-as-the-drawer, discard-and-closing-a-tab-with-staged-changes-ask-first, undo-writes-the-previous-values-back-within-the-window, undo-is-offered-for-ten-seconds-then-the-values-stay, a-row-deleted-meanwhile-drops-its-changes-and-the-rest-is-saved, a-failed-write-stops-the-save-and-the-rows-left-stay-staged, a-saved-row-shows-in-place-unless-the-save-may-move-rows, a-save-under-a-search-or-a-filter-reads-the-page-again, an-edit-and-its-undo-land-in-the-instance-of-the-tab-only, saved-cells-keep-their-type-numbers-booleans-dates-and-objects, the-edit-route-writes-typed-values-and-refuses-the-rest, hashed-encrypted-and-localized-columns-are-written-as-typed, the-row-drawer-stages-edits-like-the-cells-do, an-undo-whose-write-fails-keeps-the-saved-values-and-offers-undo-again | +| [editing](editing.md) | # Editing | edits-are-staged-then-reviewed-then-written-one-put-per-row, invalid-drafts-are-refused-esc-cancels-and-a-click-away-decides, null-empties-a-cell-and-backslash-null-is-the-text-null, object-and-array-cells-open-the-json-editor-in-a-side-drawer, the-json-editor-is-as-tall-as-the-drawer, discard-and-closing-a-tab-with-staged-changes-ask-first, undo-writes-the-previous-values-back-within-the-window, undo-is-offered-for-ten-seconds-then-the-values-stay, a-row-deleted-meanwhile-drops-its-changes-and-the-rest-is-saved, a-failed-write-stops-the-save-and-the-rows-left-stay-staged, a-saved-row-shows-in-place-unless-the-save-may-move-rows, a-save-under-a-search-or-a-filter-reads-the-page-again, an-edit-and-its-undo-land-in-the-instance-of-the-tab-only, saved-cells-keep-their-type-numbers-booleans-dates-and-objects, hashed-encrypted-and-localized-columns-are-written-as-typed, the-row-drawer-stages-edits-like-the-cells-do, an-undo-whose-write-fails-keeps-the-saved-values-and-offers-undo-again | | [query](query.md) | # Query | a-query-returns-its-rows-in-the-order-it-asks, an-instance-and-every-instance-are-targeted, a-failed-query-says-what-failed-and-offers-the-nearest-name, the-insert-chips-add-their-operation, ctrl-space-completes-schemas-and-tables-from-the-workspace, an-empty-console-offers-examples-built-on-your-own-tables, results-over-1000-rows-are-cut-at-1000, the-table-view-shows-every-returned-row, an-export-of-uneven-rows-keeps-every-key-in-csv-and-json, csv-quotes-a-comma-a-quote-and-a-line-break-so-the-cell-reads-back, format-strips-trailing-spaces-and-blank-lines, ctrl-space-inside-a-filter-completes-the-columns-of-the-table, the-chart-plots-the-first-numeric-column-with-pickers-for-both-axes, open-in-data-browser-opens-the-target-table-or-the-row, copy-as-json-puts-the-returned-rows-on-the-clipboard, a-link-opens-the-console-on-the-table-in-the-instance-it-names | | [guard](guard.md) | # Guard | a-delete-names-its-operation-target-and-rows-and-waits-for-the-table-name, every-write-names-its-operation-and-counts-the-rows-it-would-touch, confirming-a-single-row-update-needs-the-table-name-as-the-docs-say, a-confirmed-write-acts-on-the-data-of-that-moment, a-read-query-runs-straight-away | | [library](library.md) | # Library | history-keeps-your-last-500-runs-newest-first, history-records-failures-and-writes-with-their-status, history-is-searchable-and-clearing-it-keeps-the-saved-queries, a-saved-query-needs-a-name-and-can-be-edited-and-deleted, a-shared-query-reaches-the-team-and-only-its-author-changes-it, history-belongs-to-its-user-and-a-link-restores-a-run, the-library-survives-a-backend-restart, history-groups-runs-by-day-with-yesterday-and-older-dates, a-history-row-without-a-status-reads-as-ok | diff --git a/.agents/skills/verify-dms-database/features/editing.md b/.agents/skills/verify-dms-database/features/editing.md index 5fcc851..7296465 100644 --- a/.agents/skills/verify-dms-database/features/editing.md +++ b/.agents/skills/verify-dms-database/features/editing.md @@ -36,7 +36,7 @@ Staged edits of the Data browser: a cell or a drawer field is staged with the ol - `a-save-under-a-search-or-a-filter-reads-the-page-again`: a filtered field and a search read the page again, another field of a filter does not. - `an-edit-and-its-undo-land-in-the-instance-of-the-tab-only`: a row with one id in the default, eu and us instances. - `saved-cells-keep-their-type-numbers-booleans-dates-and-objects`: the column types the API infers from the stored rows after a typed edit. -- `the-edit-route-writes-typed-values-and-refuses-the-rest`: the PUT's rules, read from `rowEdit.ts`. +- `the-edit-route-writes-typed-values-and-refuses-the-rest`: the PUT's rules, read from `rowEdit.ts`. Integration test in `src/test/editing.journeys.test.ts`. - `hashed-encrypted-and-localized-columns-are-written-as-typed`: the warning, driven on `vault.accounts`. - `the-row-drawer-stages-edits-like-the-cells-do`: the drawer's fields stage with the same messages, and its footer and the bar count the same changes. - `discard-drops-the-changes-of-every-staged-row`: Discard with changes on three rows empties the bar, restores every cell and writes nothing. @@ -52,6 +52,12 @@ Staged edits of the Data browser: a cell or a drawer field is staged with the ol pnpm e2e:run specs/editing.spec.ts ``` +The journeys marked integration test run in `pnpm test`; one file alone after `pnpm run build`: + +```bash +pnpm exec ajs module test . -f dist/test/editing.journeys.test.js +``` + ## Gotchas - The bar's status line names the changed fields (`Unsaved changes · name, price`); the count is on the **Review and save N changes** button, the tab dot and the drawer's footer. diff --git a/e2e/journeys/parts/edit-store.mjs b/e2e/journeys/parts/edit-store.mjs index a450a1a..1e585e9 100644 --- a/e2e/journeys/parts/edit-store.mjs +++ b/e2e/journeys/parts/edit-store.mjs @@ -1,4 +1,4 @@ -import { check, db, pick, show } from "../../database.mjs"; +import { check, pick } from "../../database.mjs"; import { browse, openTable, rowsOf, settle } from "./browse.mjs"; import { cellOf, cellState, saveStaged, savedNotice, storedRow, typeInto } from "./edit.mjs"; @@ -116,74 +116,4 @@ const typedValues = { }, }; -/** - * PUTs to the edit route for eu's orders. - * - * @param {Ctx} ctx The journey - * @param {string} label What the call does - * @param {string} id The row, empty to send none - * @param {unknown} body The JSON body - * @returns {Promise} The answer - */ -function putOrder(ctx, label, id, body) { - const selection = "filter_schema=is:shop&filter_table=is:orders&filter_instance=is:eu&connection=own"; - return db(ctx, label, "PUT", `/browse/edit?${selection}${id ? `&id=${id}` : ""}`, { body }); -} - -/** - * The writes the edit route refuses. - * - * @param {Ctx} ctx The journey - * @returns {Promise} - */ -async function refusals(ctx) { - const id = "eu_ord_10405"; - const everywhere = await db(ctx, "across every instance", "PUT", `/browse/edit?filter_schema=is:shop&filter_table=is:orders&filter_instance=is:__CROSS_INSTANCE__&id=${id}&connection=own`, { body: { channel: "everywhere" } }); - const noId = await putOrder(ctx, "no id", "", { total: 1 }); - const array = await putOrder(ctx, "an array body", id, [1, 2]); - const missing = await putOrder(ctx, "a missing row", "nope", { total: 1 }); - const stored = await storedRow(ctx, "orders", id, "eu"); - await ctx.verify("the refusals", [ - check("across all instances the edit is refused 400 and writes nothing", everywhere.status === 400 && /Editing is disabled when browsing across all instances/.test(String(everywhere.body)) && stored.channel !== "everywhere", [everywhere.status, everywhere.body, stored.channel]), - check("a missing id is 400, an array body is 400, a missing row is 404", noId.status === 400 && array.status === 400 && missing.status === 404 && /Row not found/.test(String(missing.body)), [noId.status, array.status, missing.status]), - ]); -} - -/** @type {{ id: string, title: string, entryPoint: string, run: (ctx: Ctx) => Promise }} */ -const editRoute = { - id: "the-edit-route-writes-typed-values-and-refuses-the-rest", - title: "PUT /browse/edit writes the fields it is given as typed, keeps a date a date and refuses a value that is no date with 400, never rewrites the primary key or _instance, replaces an object whole, clears with null, answers the merged row, and refuses a missing id, a non-object body and a missing row", - entryPoint: "PUT /api/database/browse/edit", - async run(/** @type {Ctx} */ ctx) { - const put = (/** @type {string} */ label, /** @type {string} */ id, /** @type {unknown} */ body) => putOrder(ctx, label, id, body); - const id = "eu_ord_10405"; - const number = await put("a number", id, { total: 12.5 }); - const textOverNumber = await put("a text over a number", id, { channel: "kiosk", currency: "GBP" }); - const dateText = await put("a date as text", id, { created_at: "2026-10-09" }); - const badDate = await put("no date", id, { created_at: "not a date" }); - const boolDate = await put("a boolean over a date", id, { created_at: true }); - const key = await put("the primary key", id, { _id: "hacked", _instance: "us" }); - const object = await put("an object", id, { shipping: { carrier: "X" } }); - const cleared = await put("null", id, { coupon_id: null, channel: null }); - const added = await put("a new field", id, { gift: true, note: "hello" }); - const same = await put("an unchanged echo", id, { currency: "GBP", gift: true }); - const stored = await storedRow(ctx, "orders", id, "eu"); - const hacked = await browse(ctx, "the hacked id", "get", "shop.orders", { filter_instance: "is:eu", id: "hacked" }); - const types = await browse(ctx, "order column types", "columns", "shop.orders", { filter_instance: "is:eu" }); - await ctx.verify("the writes", [ - check("a number is stored as a number and answered merged", number.status === 200 && pick(number.body, "total") === 12.5 && pick(number.body, "number") === "#10405", number.body), - check("two text fields are written in one call", textOverNumber.status === 200 && pick(textOverNumber.body, "currency") === "GBP", textOverNumber.body), - check("a date cell takes a date text and stays a date: the column type is date", dateText.status === 200 && stored.created_at === "2026-10-09T00:00:00.000Z" && pick(types.body, "types", "created_at") === "date", [stored.created_at, pick(types.body, "types", "created_at")]), - check("a text that is no date is refused 400 naming the field", badDate.status === 400 && /Invalid date for 'created_at'/.test(String(badDate.body)), [badDate.status, badDate.body]), - check("a boolean over a date is refused 400", boolDate.status === 400, boolDate.status), - check("the primary key and _instance are never rewritten: the answer is the same row", key.status === 200 && stored._id === id && stored._instance === "eu" && hacked.status === 404, [key.status, stored._id, stored._instance, hacked.status]), - check("an object replaces the stored one whole", object.status === 200 && show(stored.shipping) === '{"carrier":"X"}', stored.shipping), - check("null clears a cell: coupon_id and channel are null", cleared.status === 200 && stored.coupon_id === null && stored.channel === null, [stored.coupon_id, stored.channel]), - check("a field the row never had is added, as typed", added.status === 200 && stored.gift === true && stored.note === "hello", [stored.gift, stored.note]), - check("an unchanged echo is accepted and changes nothing", same.status === 200 && stored.currency === "GBP", same.status), - ]); - await refusals(ctx); - }, -}; - -export const storeJourneys = [instances, typedValues, editRoute]; +export const storeJourneys = [instances, typedValues]; diff --git a/src/test/editing.journeys.test.ts b/src/test/editing.journeys.test.ts new file mode 100644 index 0000000..1463196 --- /dev/null +++ b/src/test/editing.journeys.test.ts @@ -0,0 +1,206 @@ +import { strict as assert } from "node:assert"; +import { Schema } from "@antelopejs/interface-database"; +import { + Index, + RegisterSchema, + RegisterTable, + Table, +} from "@antelopejs/interface-database-decorators"; +import { + isJsonObjectValue, + type JsonObject, + type JsonValue, +} from "../types/json"; +import { callDatabase, type HttpAnswer } from "./helpers/http"; +import { pick } from "./helpers/pick"; +import { createOwnerSession, type OwnerSession } from "./ownerSession"; + +const SHOP = "editing-journeys-shop"; +const ID = "eu_ord_10405"; +const ORDERS = `filter_schema=is:${SHOP}&filter_table=is:orders`; + +@RegisterTable("orders", SHOP) +class EditingJourneysOrder extends Table { + declare _id: string; + @Index() declare number: string; + @Index() declare status: string; + declare channel: string | null; + declare total: number; + declare currency: string; + declare coupon_id: string | null; + declare shipping: Record; + @Index() declare created_at: Date; +} + +/** Keeps the decorated class referenced: the decorator registers it. */ +const TABLES = [EditingJourneysOrder]; + +function order(index: number) { + return { + _id: `eu_ord_${10400 + index}`, + number: `#${10400 + index}`, + status: "paid", + channel: "web", + total: 100 + index, + currency: "EUR", + coupon_id: "cpn_AUTUMN10", + shipping: { carrier: "UPS", eta: "2026-10-12" }, + created_at: new Date("2026-10-01T00:00:00.000Z"), + }; +} + +function shop() { + const schema = Schema.get(SHOP); + assert.ok(schema, `${SHOP} is registered`); + return schema; +} + +function put( + session: OwnerSession, + id: string, + body: JsonValue, +): Promise { + const query = `${ORDERS}&filter_instance=is:eu&connection=own${id ? `&id=${id}` : ""}`; + return callDatabase(session, "PUT", `/browse/edit?${query}`, body); +} + +async function stored(session: OwnerSession): Promise { + const answer = await callDatabase( + session, + "GET", + `/browse/get?${ORDERS}&filter_instance=is:eu&id=${ID}`, + ); + assert.equal(answer.status, 200, answer.text); + const { body } = answer; + assert.ok(isJsonObjectValue(body), answer.text); + return body; +} + +async function assertTypedWrites(session: OwnerSession): Promise { + const number = await put(session, ID, { total: 12.5 }); + assert.deepEqual( + [number.status, pick(number.body, "total"), pick(number.body, "number")], + [200, 12.5, "#10405"], + "a number is stored as a number and the answer is the merged row", + ); + const twoTexts = await put(session, ID, { + channel: "kiosk", + currency: "GBP", + }); + assert.deepEqual( + [twoTexts.status, pick(twoTexts.body, "currency")], + [200, "GBP"], + "two text fields are written in one call", + ); + const dateText = await put(session, ID, { created_at: "2026-10-09" }); + const badDate = await put(session, ID, { created_at: "not a date" }); + const boolDate = await put(session, ID, { created_at: true }); + const key = await put(session, ID, { _id: "hacked", _instance: "us" }); + const object = await put(session, ID, { shipping: { carrier: "X" } }); + const cleared = await put(session, ID, { coupon_id: null, channel: null }); + const added = await put(session, ID, { gift: true, note: "hello" }); + const same = await put(session, ID, { currency: "GBP", gift: true }); + const row = await stored(session); + const hacked = await callDatabase( + session, + "GET", + `/browse/get?${ORDERS}&filter_instance=is:eu&id=hacked`, + ); + const types = await callDatabase( + session, + "GET", + `/browse/columns?${ORDERS}&filter_instance=is:eu`, + ); + assert.deepEqual( + [dateText.status, row.created_at, pick(types.body, "types", "created_at")], + [200, "2026-10-09T00:00:00.000Z", "date"], + "a date cell takes a date text and stays a date", + ); + assert.equal(badDate.status, 400, "a text that is no date is refused"); + assert.match(badDate.text, /Invalid date for 'created_at'/); + assert.equal(boolDate.status, 400, "a boolean over a date is refused"); + assert.deepEqual( + [key.status, row._id, row._instance, hacked.status], + [200, ID, "eu", 404], + "the primary key and _instance are never rewritten", + ); + assert.deepEqual( + [object.status, row.shipping], + [200, { carrier: "X" }], + "an object replaces the stored one whole, not merged into it", + ); + assert.deepEqual( + [cleared.status, row.coupon_id, row.channel], + [200, null, null], + "null clears a cell", + ); + assert.deepEqual( + [added.status, row.gift, row.note], + [200, true, "hello"], + "a field the row never had is added, as typed", + ); + assert.deepEqual( + [same.status, row.currency], + [200, "GBP"], + "an unchanged echo is accepted and changes nothing", + ); +} + +async function assertRefusals(session: OwnerSession): Promise { + const everywhere = await callDatabase( + session, + "PUT", + `/browse/edit?${ORDERS}&filter_instance=is:__CROSS_INSTANCE__&id=${ID}&connection=own`, + { channel: "everywhere" }, + ); + assert.equal(everywhere.status, 400, "an edit across instances is refused"); + assert.match( + everywhere.text, + /Editing is disabled when browsing across all instances/, + ); + assert.notEqual( + (await stored(session)).channel, + "everywhere", + "a refused cross-instance edit still wrote the row", + ); + const missing = await put(session, "nope", { total: 1 }); + assert.deepEqual( + [ + (await put(session, "", { total: 1 })).status, + (await put(session, ID, [1, 2])).status, + missing.status, + ], + [400, 400, 404], + "a missing id is 400, an array body 400, a missing row 404", + ); + assert.match(missing.text, /Row not found/); +} + +describe("[integration] editing journeys", () => { + let owner: OwnerSession; + + before(async () => { + assert.equal(TABLES.length, 1); + await RegisterSchema(SHOP); + await shop() + .createInstance("eu") + .run() + .catch(() => undefined); + await shop() + .instance("eu") + .table("orders") + .insert(Array.from({ length: 8 }, (_, index) => order(index))) + .run(); + owner = await createOwnerSession("editing-journeys-owner@example.test"); + }); + + after(async () => { + await owner.remove(); + await shop().destroyInstance("eu").run(); + }); + + it("the-edit-route-writes-typed-values-and-refuses-the-rest", async () => { + await assertTypedWrites(owner); + await assertRefusals(owner); + }); +}); From 4b8d1fdc40a4324063c7393973148a22a246c7af Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 09:00:05 +0000 Subject: [PATCH 10/12] test: make the refused writes of the ported journeys able to fail --- .../verify-dms-database/features/access.md | 2 +- src/test/access.journeys.test.ts | 107 +++++++++++++----- src/test/data.journeys.test.ts | 10 +- src/test/dataJourneys.ts | 3 + src/test/diagram.journeys.test.ts | 5 +- src/test/extending.journeys.test.ts | 2 +- src/test/helpers/http.ts | 7 +- src/test/helpers/jsonAt.ts | 30 ----- src/test/helpers/pick.ts | 24 ++++ src/test/library.journeys.test.ts | 2 +- src/test/schemas.journeys.test.ts | 15 ++- 11 files changed, 134 insertions(+), 73 deletions(-) delete mode 100644 src/test/helpers/jsonAt.ts diff --git a/.agents/skills/verify-dms-database/features/access.md b/.agents/skills/verify-dms-database/features/access.md index 55c30f7..4454b58 100644 --- a/.agents/skills/verify-dms-database/features/access.md +++ b/.agents/skills/verify-dms-database/features/access.md @@ -22,7 +22,7 @@ The pages and the module's API answer to the platform owner only, and the module - `a-member-gets-403-from-every-route-and-writes-nothing`: a member with the module's permissions gets 403 from every route and changes nothing. Integration test in `src/test/access.journeys.test.ts`. - `a-member-sees-neither-the-pages-nor-the-catalog-tile`: no tile and no page for a member; the owner sees the tile. - `the-catalog-tile-reads-the-database`: the tile's two readout lines, version and category. -- `the-owner-only-gate-is-logged-at-start`: the five 'gated owner-only' log lines. Integration test in `src/test/access.journeys.test.ts`. +- `the-owner-only-gate-is-logged-at-start`: the owner-only gate the start log reports, each of the five pages' layout routes answering the owner and refusing a member with the module's permissions. Integration test in `src/test/access.journeys.test.ts`. ## How to get to it (user POV) diff --git a/src/test/access.journeys.test.ts b/src/test/access.journeys.test.ts index 1eaafa8..044d908 100644 --- a/src/test/access.journeys.test.ts +++ b/src/test/access.journeys.test.ts @@ -1,9 +1,11 @@ import { strict as assert } from "node:assert"; import { Schema } from "@antelopejs/interface-database"; import { pageRoutePath } from "@antelopejs/interface-dms/page"; +import { SCHEMA_NAME } from "../types/constants"; import type { JsonObject, JsonValue } from "../types/json"; import { callBackend, callDatabase, type HttpAnswer } from "./helpers/http"; import { pick } from "./helpers/pick"; +import { withOwnDatabase } from "./ownDatabase"; import { createMemberWithRole, createOwnerSession, @@ -56,14 +58,34 @@ const READS = [ "/query/history/none", ]; -/** Every write route of the module, with a body it would accept from the owner. */ -const WRITES: readonly [string, string, JsonValue | undefined][] = [ - ["PUT", "/browse/edit", { schema: SCHEMA, table: "products", updates: [] }], - [ - "POST", - "/query/execute", - { query: tableQuery("products"), source: "x", language: "aql" }, - ], +/** The source of the run the member sends, which only a run that went through records in the history table. */ +const MEMBER_SOURCE = "access-journeys-member-run"; + +type Write = readonly [string, string, JsonValue | undefined]; + +const EDIT: Write = [ + "PUT", + `/browse/edit?${SELECTION}&id=sku_desk&connection=own`, + { name: "Member edit" }, +]; +const EXECUTE: Write = [ + "POST", + "/query/execute", + { query: tableQuery("products"), source: MEMBER_SOURCE, language: "aql" }, +]; +const ADD_NOTE: Write = [ + "POST", + "/diagram/notes?connection=own", + { schemaName: SCHEMA, text: "x", x: 0, y: 0, width: 100, height: 50 }, +]; + +/** The writes whose effect the member test reads back, which the owner's own call must carry out. */ +const OWNER_ACCEPTS: readonly Write[] = [EXECUTE, ADD_NOTE]; + +/** Every write route of the module; the edit, the run and the note carry a body the owner's call would carry out. */ +const WRITES: readonly Write[] = [ + EDIT, + EXECUTE, ["POST", "/query/dry-run", { query: tableQuery("products") }], [ "POST", @@ -84,7 +106,7 @@ const WRITES: readonly [string, string, JsonValue | undefined][] = [ ["DELETE", "/query/saved/none", undefined], ["DELETE", "/query/history", undefined], ["PUT", `/diagram/layout/${SCHEMA}`, { positions: {} }], - ["POST", "/diagram/notes", { schema: SCHEMA, text: "x", x: 0, y: 0 }], + ADD_NOTE, ["PUT", "/diagram/notes/none", { text: "x" }], ["DELETE", "/diagram/notes/none", undefined], ]; @@ -114,10 +136,19 @@ function everyRouteAnswers(status: number): Record { ); } -/** The length of the list `field` of an answer, or -1 when it holds none. */ +/** The length of the list `field` of a 200 answer. */ function listLength(answer: HttpAnswer, field: string): number { + assert.equal(answer.status, 200, answer.text); const items = pick(answer.body, field); - return Array.isArray(items) ? items.length : -1; + assert.ok(Array.isArray(items), answer.text); + return items.length; +} + +/** The rows of the module's history table that a run of `source` recorded, read by a client of its own. */ +function historyRowsOf(source: string): Promise { + return withOwnDatabase((db) => + db.collection(`${SCHEMA_NAME}__query_history`).countDocuments({ source }), + ); } describe("[integration] access journeys", () => { @@ -142,6 +173,12 @@ describe("[integration] access journeys", () => { }); after(async () => { + await callDatabase(owner, "DELETE", "/query/history"); + await withOwnDatabase((db) => + db + .collection(`${SCHEMA_NAME}__diagram_notes`) + .deleteMany({ schemaName: SCHEMA }), + ); await owner.remove(); await granted.remove(); await schema.instance().table("products").delete().run(); @@ -162,21 +199,12 @@ describe("[integration] access journeys", () => { }); it("a-member-gets-403-from-every-route-and-writes-nothing", async () => { - const run = await callDatabase(owner, "POST", "/query/execute", { - query: tableQuery("products"), - source: `schemas["${SCHEMA}"].instance().table("products")`, - language: "aql", - }); - assert.equal(run.status, 200, run.text); const notesPath = `/diagram/notes?schema=${SCHEMA}`; + const productPath = `/browse/get?${SELECTION}&id=sku_desk`; const notesBefore = listLength( await callDatabase(owner, "GET", notesPath), "items", ); - const historyBefore = listLength( - await callDatabase(owner, "GET", "/query/history"), - "items", - ); assert.deepEqual( await statusOfEveryRoute(granted), @@ -188,13 +216,36 @@ describe("[integration] access journeys", () => { notesBefore, "the member's POST /diagram/notes added a note", ); - assert.deepEqual( - [ - historyBefore, - listLength(await callDatabase(owner, "GET", "/query/history"), "items"), - ], - [1, 1], - "the member's DELETE /query/history cleared the owner's history", + const product = await callDatabase(owner, "GET", productPath); + assert.equal(product.status, 200, product.text); + assert.equal( + pick(product.body, "name"), + "Standing desk", + "the member's PUT /browse/edit rewrote the row", + ); + assert.equal( + await historyRowsOf(MEMBER_SOURCE), + 0, + "the member's POST /query/execute ran and recorded a history row", + ); + + for (const [method, path, body] of OWNER_ACCEPTS) { + const answer = await callDatabase(owner, method, path, body); + assert.equal( + answer.status, + 200, + `the owner's ${method} ${path} is refused, so the member's 403 proves nothing: ${answer.text}`, + ); + } + assert.equal( + listLength(await callDatabase(owner, "GET", notesPath), "items"), + notesBefore + 1, + "the member's note body would not store a note even from the owner", + ); + assert.equal( + await historyRowsOf(MEMBER_SOURCE), + 1, + "the member's run would not record a history row even from the owner", ); }); diff --git a/src/test/data.journeys.test.ts b/src/test/data.journeys.test.ts index 153e66c..17c80b6 100644 --- a/src/test/data.journeys.test.ts +++ b/src/test/data.journeys.test.ts @@ -302,7 +302,7 @@ async function assertOwnerOnly(api: DataApi): Promise { }, "a browse route that skips the owner gate answers a visitor or a member", ); - const edit = `/browse/edit?${selection}&id=sku_desk`; + const edit = `/browse/edit?${selection}&id=sku_desk&connection=own`; assert.deepEqual( [ (await callDatabase(null, "PUT", edit, { name: "Hacked" })).status, @@ -319,6 +319,14 @@ async function assertOwnerOnly(api: DataApi): Promise { "Standing desk", "a refused edit still wrote the row", ); + const same = await callDatabase(api.owner, "PUT", edit, { + name: "Standing desk", + }); + assert.equal( + same.status, + 200, + `the owner's edit is refused, so the refusals above prove nothing: ${same.text}`, + ); } finally { await reader.remove(); } diff --git a/src/test/dataJourneys.ts b/src/test/dataJourneys.ts index 374d219..cd8ef32 100644 --- a/src/test/dataJourneys.ts +++ b/src/test/dataJourneys.ts @@ -270,6 +270,8 @@ export interface DataApi { ): Promise; /** Calls `path` under `/api/database`. */ get(path: string): Promise; + /** The owner the suite signed in. */ + readonly owner: OwnerSession; } /** @@ -290,6 +292,7 @@ export function withDataFixture(email: string): () => DataApi { const session = owner; assert.ok(session, "the suite's before hook signed the owner in"); return { + owner: session, browse(route, target, params = {}) { const [schema = "", table] = target.split("."); const query = new URLSearchParams({ filter_schema: `is:${schema}` }); diff --git a/src/test/diagram.journeys.test.ts b/src/test/diagram.journeys.test.ts index 0ee038e..2a15804 100644 --- a/src/test/diagram.journeys.test.ts +++ b/src/test/diagram.journeys.test.ts @@ -4,7 +4,7 @@ import { DiagramLayoutModel, DiagramNoteModel } from "../db"; import { OWN_CONNECTION } from "../types/constants"; import type { JsonObject, JsonValue } from "../types/json"; import { call } from "./helpers/http"; -import { at, itemsAt, textAt } from "./helpers/jsonAt"; +import { at, itemsAt, textAt } from "./helpers/pick"; import { createMemberSession, createOwnerSession, @@ -54,6 +54,7 @@ function saveLayout(schema: string, body: JsonObject) { async function notesOf(schema: string): Promise { const answer = await call(owner, "GET", `${NOTES}?schema=${schema}`); + assert.equal(answer.status, 200, answer.text); return itemsAt(answer.body, "items"); } @@ -228,7 +229,7 @@ async function ownerOnly(): Promise { body: { positions: {} }, }, { method: "GET", path: `${NOTES}?schema=${SHOP}` }, - { method: "POST", path: NOTES, body: NOTE }, + { method: "POST", path: `${NOTES}?connection=own`, body: NOTE }, { method: "PUT", path: `${NOTES}/x`, body: { text: "y" } }, { method: "DELETE", path: `${NOTES}/x` }, ]; diff --git a/src/test/extending.journeys.test.ts b/src/test/extending.journeys.test.ts index ce7e986..46dd2b8 100644 --- a/src/test/extending.journeys.test.ts +++ b/src/test/extending.journeys.test.ts @@ -17,7 +17,7 @@ import { } from "@antelopejs/interface-database-decorators"; import { isJsonValue, type JsonObject, type JsonValue } from "../types/json"; import { call } from "./helpers/http"; -import { at, itemsAt, keysAt, textAt } from "./helpers/jsonAt"; +import { at, itemsAt, keysAt, textAt } from "./helpers/pick"; import { createOwnerSession, type OwnerSession } from "./ownerSession"; import { encode } from "./stagedWire"; diff --git a/src/test/helpers/http.ts b/src/test/helpers/http.ts index d7fe810..25dd56a 100644 --- a/src/test/helpers/http.ts +++ b/src/test/helpers/http.ts @@ -2,10 +2,7 @@ import { isJsonValue, type JsonValue } from "../../types/json"; import type { OwnerSession } from "../ownerSession"; /** The test DMS's backend, served by the harness's `api` module. */ -export const BACKEND_ROOT = "http://127.0.0.1:5023"; - -/** The root of the modules' API routes on {@link BACKEND_ROOT}. */ -export const API_ROOT = `${BACKEND_ROOT}/api`; +const BACKEND_ROOT = "http://127.0.0.1:5023"; /** What the backend answered: its status, its body as JSON (`null` when it is not JSON), and its raw text. */ export interface HttpAnswer { @@ -24,7 +21,7 @@ function parsed(text: string): JsonValue { } /** - * Calls `path` under {@link API_ROOT} as `session`, or with no session when it is `null`, the way the dashboard + * Calls `path` under `/api` on {@link BACKEND_ROOT} as `session`, or with no session when it is `null`, the way the dashboard * does: a bearer token and the default namespace. Never throws on a status. */ export function call( diff --git a/src/test/helpers/jsonAt.ts b/src/test/helpers/jsonAt.ts deleted file mode 100644 index ff6e3e2..0000000 --- a/src/test/helpers/jsonAt.ts +++ /dev/null @@ -1,30 +0,0 @@ -import { isJsonObjectValue, type JsonValue } from "../../types/json"; -import { isString } from "../../utils/guards"; - -/** The value at `path` inside `value`, or `null` when a step is not an object or lacks the key. */ -export function at(value: JsonValue, ...path: string[]): JsonValue { - let current = value; - for (const key of path) { - if (!isJsonObjectValue(current)) return null; - current = current[key] ?? null; - } - return current; -} - -/** The array at `path` inside `value`, or an empty one when it is not an array. */ -export function itemsAt(value: JsonValue, ...path: string[]): JsonValue[] { - const found = at(value, ...path); - return Array.isArray(found) ? found : []; -} - -/** The string at `path` inside `value`, or `""` when it is not a string. */ -export function textAt(value: JsonValue, ...path: string[]): string { - const found = at(value, ...path); - return isString(found) ? found : ""; -} - -/** The member names of the object at `path` inside `value`, in order, or none when it is not an object. */ -export function keysAt(value: JsonValue, ...path: string[]): string[] { - const found = at(value, ...path); - return isJsonObjectValue(found) ? Object.keys(found) : []; -} diff --git a/src/test/helpers/pick.ts b/src/test/helpers/pick.ts index 25c57d5..3862356 100644 --- a/src/test/helpers/pick.ts +++ b/src/test/helpers/pick.ts @@ -40,3 +40,27 @@ export function objectsAt( const items = pick(value, ...path); return Array.isArray(items) ? items.filter(isJsonObjectValue) : []; } + +/** The value at `path` in `value`, or `null` when a step is missing. */ +export function at(value: JsonValue, ...path: string[]): JsonValue { + return pick(value, ...path) ?? null; +} + +/** The array at `path` in `value`, or an empty one when it is not an array. */ +export function itemsAt(value: JsonValue, ...path: string[]): JsonValue[] { + const found = pick(value, ...path); + return Array.isArray(found) ? found : []; +} + +/** The string at `path` in `value`, or `""` when it is not a string. */ +export function textAt(value: JsonValue, ...path: string[]): string { + return text(pick(value, ...path)); +} + +/** The member names of the object at `path` in `value`, in order, or none when it is not an object. */ +export function keysAt(value: JsonValue, ...path: string[]): string[] { + const found = pick(value, ...path); + return found !== undefined && isJsonObjectValue(found) + ? Object.keys(found) + : []; +} diff --git a/src/test/library.journeys.test.ts b/src/test/library.journeys.test.ts index 352aac2..a7b3f89 100644 --- a/src/test/library.journeys.test.ts +++ b/src/test/library.journeys.test.ts @@ -2,7 +2,7 @@ import { strict as assert } from "node:assert"; import { Schema } from "@antelopejs/interface-database"; import { SCHEMA_NAME } from "../types/constants"; import { call } from "./helpers/http"; -import { at, itemsAt, textAt } from "./helpers/jsonAt"; +import { at, itemsAt, textAt } from "./helpers/pick"; import { withOwnDatabase } from "./ownDatabase"; import { createOwnerSession, type OwnerSession } from "./ownerSession"; import { encode } from "./stagedWire"; diff --git a/src/test/schemas.journeys.test.ts b/src/test/schemas.journeys.test.ts index 870dfb4..9c0c689 100644 --- a/src/test/schemas.journeys.test.ts +++ b/src/test/schemas.journeys.test.ts @@ -1,7 +1,7 @@ import { strict as assert } from "node:assert"; import type { JsonValue } from "../types/json"; import { call } from "./helpers/http"; -import { at, itemsAt, keysAt, textAt } from "./helpers/jsonAt"; +import { at, itemsAt, keysAt, textAt } from "./helpers/pick"; import { CUSTOMERS_PER_REGION, DEMO, @@ -60,7 +60,13 @@ async function source(bar: Bar = {}): Promise { } async function listed(bar: Bar): Promise { - return ids((await source(bar)).rows).sort(); + const listing = await source(bar); + assert.equal( + listing.status, + 200, + `the source refused ${JSON.stringify(bar)}`, + ); + return ids(listing.rows).sort(); } async function schemas(): Promise { @@ -259,8 +265,9 @@ async function instanceCounts(): Promise { }, "all counts every instance at once", ); - assert.ok( - Object.values(await shopCounts("atlantis")).every((count) => count === 0), + assert.deepEqual( + await shopCounts("atlantis"), + { customers: 0, products: 0, orders: 0, order_items: 0 }, "an instance that does not exist counts nothing", ); const emptyIn = async (instance: string) => From 211bf79b1a0dde1c3255fd567614c8e6f1f20103 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 09:00:36 +0000 Subject: [PATCH 11/12] test(data): give the data fixture's seeding its own timeout --- src/test/dataJourneys.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/test/dataJourneys.ts b/src/test/dataJourneys.ts index cd8ef32..9847c18 100644 --- a/src/test/dataJourneys.ts +++ b/src/test/dataJourneys.ts @@ -260,6 +260,8 @@ async function unseed(): Promise { } } +const SEED_TIMEOUT_MS = 60_000; + /** The browse API as the owner of a seeded data fixture calls it. */ export interface DataApi { /** Calls a browse route on `schema.table` (or `schema`), with `params` after the selection. */ @@ -280,7 +282,8 @@ export interface DataApi { */ export function withDataFixture(email: string): () => DataApi { let owner: OwnerSession | undefined; - before(async () => { + before(async function () { + this.timeout(SEED_TIMEOUT_MS); await seed(); owner = await createOwnerSession(email); }); From 03c1092791b8152ca95fff160f77256023eb1db9 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 09:00:42 +0000 Subject: [PATCH 12/12] ci: start the checks on the ready pull request