@camunda/e2e-test-suite 0.0.1242 → 0.0.1243

package/dist/utils/api/bpmn.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * Minimal BPMN/DMN builders for API-level tests.
+ *
+ * The legacy shell suite pasted 18 near-identical BPMN documents inline as
+ * heredocs, several of them interpolating a process id. Building the XML gives
+ * every test a unique process id without a new file per shape, which is what
+ * the suite's isolation rules require — reused ids collide across parallel
+ * workers and produce cross-test flakiness.
+ *
+ * Only the shapes the API tests need are modelled. Anything requiring real
+ * diagram semantics belongs in `resources/` as a checked-in file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simpleForm = exports.simpleDecision = exports.startFormProcess = exports.emptyProcess = exports.linearProcess = exports.element = exports.uniqueId = void 0;
+const node_crypto_1 = require("node:crypto");
+/** A process/decision id that cannot collide with another worker's. */
+function uniqueId(prefix) {
+    return `${prefix}-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`;
+}
+exports.uniqueId = uniqueId;
+const NS = [
+    'xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"',
+    'xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"',
+    'xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"',
+    'xmlns:di="http://www.omg.org/spec/DD/20100524/DI"',
+    'xmlns:zeebe="http://camunda.org/schema/zeebe/1.0"',
+    'xmlns:modeler="http://camunda.org/schema/modeler/1.0"',
+].join(' ');
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+exports.element = {
+    serviceTask(jobType, id = 'task') {
+        return {
+            id,
+            xml: `<bpmn:serviceTask id="${id}" name="Service Task">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="${escapeXml(jobType)}" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>flow_in</bpmn:incoming>
+      <bpmn:outgoing>flow_out</bpmn:outgoing>
+    </bpmn:serviceTask>`,
+        };
+    },
+    userTask(id = 'task', formId) {
+        const form = formId
+            ? `<zeebe:formDefinition formId="${escapeXml(formId)}" />`
+            : '';
+        return {
+            id,
+            xml: `<bpmn:userTask id="${id}" name="User Task">
+      <bpmn:extensionElements>
+        <zeebe:userTask />
+        ${form}
+      </bpmn:extensionElements>
+      <bpmn:incoming>flow_in</bpmn:incoming>
+      <bpmn:outgoing>flow_out</bpmn:outgoing>
+    </bpmn:userTask>`,
+        };
+    },
+    messageCatch(messageName, correlationKey = '=msgCorrelationKey', id = 'task') {
+        return {
+            id,
+            xml: `<bpmn:intermediateCatchEvent id="${id}" name="Wait for message">
+      <bpmn:incoming>flow_in</bpmn:incoming>
+      <bpmn:outgoing>flow_out</bpmn:outgoing>
+      <bpmn:messageEventDefinition messageRef="message_def" />
+    </bpmn:intermediateCatchEvent>`,
+            definitionsFragment: `<bpmn:message id="message_def" name="${escapeXml(messageName)}">
+    <bpmn:extensionElements>
+      <zeebe:subscription correlationKey="${escapeXml(correlationKey)}" />
+    </bpmn:extensionElements>
+  </bpmn:message>`,
+        };
+    },
+    businessRuleTask(decisionId, id = 'task') {
+        return {
+            id,
+            xml: `<bpmn:businessRuleTask id="${id}" name="Business Rule Task">
+      <bpmn:extensionElements>
+        <zeebe:calledDecision decisionId="${escapeXml(decisionId)}" resultVariable="decisionResult" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>flow_in</bpmn:incoming>
+      <bpmn:outgoing>flow_out</bpmn:outgoing>
+    </bpmn:businessRuleTask>`,
+        };
+    },
+    callActivity(calledProcessId, id = 'task') {
+        return {
+            id,
+            xml: `<bpmn:callActivity id="${id}" name="Call Activity">
+      <bpmn:extensionElements>
+        <zeebe:calledElement processId="${escapeXml(calledProcessId)}" propagateAllChildVariables="false" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>flow_in</bpmn:incoming>
+      <bpmn:outgoing>flow_out</bpmn:outgoing>
+    </bpmn:callActivity>`,
+        };
+    },
+};
+/**
+ * A single-path process: start event -> the given element -> end event.
+ * No DI is emitted; the engine does not require it and no test reads it.
+ */
+function linearProcess(processId, body, options = {}) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions ${NS} id="definitions_${escapeXml(processId)}" targetNamespace="http://camunda.org/schema/1.0/bpmn" modeler:executionPlatform="Camunda Cloud" modeler:executionPlatformVersion="8.8.0">
+  <bpmn:process id="${escapeXml(processId)}" name="${escapeXml(options.name ?? processId)}" isExecutable="true">
+    <bpmn:startEvent id="start">
+      <bpmn:outgoing>flow_in</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:sequenceFlow id="flow_in" sourceRef="start" targetRef="${body.id}" />
+    ${body.xml}
+    <bpmn:sequenceFlow id="flow_out" sourceRef="${body.id}" targetRef="end" />
+    <bpmn:endEvent id="end">
+      <bpmn:incoming>flow_out</bpmn:incoming>
+    </bpmn:endEvent>
+  </bpmn:process>
+  ${body.definitionsFragment ?? ''}
+</bpmn:definitions>`;
+}
+exports.linearProcess = linearProcess;
+/** A process whose only content is a start and end event. */
+function emptyProcess(processId) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions ${NS} id="definitions_${escapeXml(processId)}" targetNamespace="http://camunda.org/schema/1.0/bpmn">
+  <bpmn:process id="${escapeXml(processId)}" name="${escapeXml(processId)}" isExecutable="true">
+    <bpmn:startEvent id="start">
+      <bpmn:outgoing>flow_out</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:sequenceFlow id="flow_out" sourceRef="start" targetRef="end" />
+    <bpmn:endEvent id="end">
+      <bpmn:incoming>flow_out</bpmn:incoming>
+    </bpmn:endEvent>
+  </bpmn:process>
+</bpmn:definitions>`;
+}
+exports.emptyProcess = emptyProcess;
+/**
+ * A process whose start event links a deployed form, so that
+ * `GET /v2/process-definitions/{key}/form` has something to return. The form
+ * must already be deployed (or ride in the same deployment), otherwise the
+ * broker rejects the reference.
+ */
+function startFormProcess(processId, formId) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions ${NS} id="definitions_${escapeXml(processId)}" targetNamespace="http://camunda.org/schema/1.0/bpmn">
+  <bpmn:process id="${escapeXml(processId)}" name="${escapeXml(processId)}" isExecutable="true">
+    <bpmn:startEvent id="start">
+      <bpmn:extensionElements>
+        <zeebe:formDefinition formId="${escapeXml(formId)}" />
+      </bpmn:extensionElements>
+      <bpmn:outgoing>flow_out</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:sequenceFlow id="flow_out" sourceRef="start" targetRef="end" />
+    <bpmn:endEvent id="end">
+      <bpmn:incoming>flow_out</bpmn:incoming>
+    </bpmn:endEvent>
+  </bpmn:process>
+</bpmn:definitions>`;
+}
+exports.startFormProcess = startFormProcess;
+/** A one-rule DMN decision that echoes its input, for evaluation tests. */
+function simpleDecision(decisionId, definitionsId = `definitions_${decisionId}`) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/" xmlns:camunda="http://camunda.org/schema/1.0/dmn" id="${escapeXml(definitionsId)}" name="${escapeXml(decisionId)}" namespace="http://camunda.org/schema/1.0/dmn">
+  <decision id="${escapeXml(decisionId)}" name="${escapeXml(decisionId)}">
+    <decisionTable id="decisionTable_${escapeXml(decisionId)}" hitPolicy="FIRST">
+      <input id="input_1" label="Input">
+        <inputExpression id="inputExpression_1" typeRef="string">
+          <text>inputVariable</text>
+        </inputExpression>
+      </input>
+      <output id="output_1" label="Output" name="result" typeRef="string" />
+      <rule id="rule_match">
+        <inputEntry id="inputEntry_match"><text>"match"</text></inputEntry>
+        <outputEntry id="outputEntry_match"><text>"matched"</text></outputEntry>
+      </rule>
+      <rule id="rule_default">
+        <inputEntry id="inputEntry_default"><text></text></inputEntry>
+        <outputEntry id="outputEntry_default"><text>"default"</text></outputEntry>
+      </rule>
+    </decisionTable>
+  </decision>
+</definitions>`;
+}
+exports.simpleDecision = simpleDecision;
+/** A minimal Camunda form with two text fields, for form submission tests. */
+function simpleForm(formId) {
+    return JSON.stringify({
+        components: [
+            {
+                label: 'Field one',
+                type: 'textfield',
+                id: 'field_one',
+                key: 'fieldOne',
+            },
+            {
+                label: 'Field two',
+                type: 'textfield',
+                id: 'field_two',
+                key: 'fieldTwo',
+            },
+        ],
+        type: 'default',
+        id: formId,
+        schemaVersion: 16,
+        executionPlatform: 'Camunda Cloud',
+        executionPlatformVersion: '8.8.0',
+    });
+}
+exports.simpleForm = simpleForm;

package/dist/utils/api/capabilities.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Cluster capabilities that decide whether a spec *can* run at all.
+ *
+ * A capability gate is not a way to quieten a failing test. It marks the one
+ * case the suite cannot otherwise express: the endpoint under test is absent
+ * by configuration, so there is nothing to assert and a red result would say
+ * nothing about the cluster's health.
+ *
+ * Two rules keep that distinction honest:
+ *
+ *  - The gate reads *configuration*, never a response. Deciding from a live
+ *    403 would also absorb a genuine permission regression, which is the
+ *    failure this suite exists to catch.
+ *  - Every gate is paired with a test that asserts the endpoint really is
+ *    absent for that configuration (see `system-api-tests.spec.ts`). Without
+ *    it, a gate that silently became wrong would remove coverage and nothing
+ *    would report it.
+ *
+ * Anything else — a token that could not be minted, a fixture that failed, a
+ * role that was not granted — is a failure, not a capability, and must stay
+ * red.
+ */
+import type { ApiClient } from './http';
+/**
+ * Reason text for the `/v2/users/**` gate, or `false` when the tree is served.
+ *
+ * Playwright prints this next to the skipped test, so a reader of the report
+ * sees why the tests did not run without opening the source.
+ */
+export declare const usersApiUnavailable: string | false;
+/**
+ * Reason text for the unauthenticated-rejection gate, or `false` where a
+ * missing `Authorization` header really is refused.
+ *
+ * Every `assertUnauthorized` test sends a request with no credentials and
+ * expects 401. That asserts a property of the *deployment*, not of the
+ * endpoint: c8Run answers its whole `/v2` tree without credentials — which
+ * `tests/c8Run-8.10/api-tests-v2.spec.ts` depends on, calling
+ * `/v2/process-definitions/search` unauthenticated and asserting 200 — so
+ * there the same requests return the normal response and the tests report
+ * "expected 401, got 200" against a cluster that never authenticated.
+ *
+ * It also takes `/v2/authentication/me` with it: an open cluster has no
+ * authenticated principal to describe, and it answers 401 even when the
+ * suite does send credentials.
+ *
+ * This is the third capability of the same shape as the two around it, and
+ * the distinction between them is worth keeping straight — whether a caller
+ * must be a principal at all (here), what a known principal may do
+ * (`authorizationsEnabled`), and whether the cluster keeps its own user
+ * registry (`usersApiEnabled`). A deployment can differ on each
+ * independently, and c8Run differs on all three.
+ */
+export declare const unauthenticatedAccessAllowed: string | false;
+export declare const enforcementPrincipalUnavailable: string | false;
+/**
+ * What `PUT /{roles,groups,tenants}/{id}/users/{username}` does when the
+ * username belongs to nobody.
+ *
+ * The engine guards membership with
+ * `case USER -> !localUserEnabled || userState.getUser(entityId).isPresent()`
+ * (`RoleAddEntityProcessor`, `GroupAddEntityProcessor`,
+ * `TenantAddEntityProcessor` in camunda/camunda). With local users disabled
+ * the left side short-circuits, so the membership is written against the bare
+ * username and the command is accepted.
+ *
+ * That is deliberate — in OIDC mode the cluster has no registry to check a
+ * username against, and refusing would make it impossible to grant a role to
+ * an identity-provider user before their first sign-in. So the two modes
+ * genuinely differ, and the assertion has to follow the mode rather than pick
+ * one and call the other a bug.
+ */
+export declare const absentUserMembership: {
+    status: number;
+    reason: string;
+};
+/**
+ * Whether the cluster enforces authorization, straight from the cluster.
+ *
+ * `POST /v2/authentication/me/authorizations/search` carries
+ * `authorizationsEnabled` as a required field, so this is the cluster's own
+ * answer rather than an inference from the chart values. Added in 8.10.
+ *
+ * `undefined` means only the two cases above. Every other status throws
+ * instead: this reading is the safety net under the enforcement gap recorded
+ * in `tests/api/README.md`, and treating a 403, a 500 or a 503 as "unknown"
+ * would let the very regression it guards remove it. A 500 from this endpoint
+ * is a finding, not a reason to stop looking.
+ */
+export declare function readAuthorizationsEnabled(api: ApiClient): Promise<boolean | undefined>;

package/dist/utils/api/capabilities.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * Cluster capabilities that decide whether a spec *can* run at all.
+ *
+ * A capability gate is not a way to quieten a failing test. It marks the one
+ * case the suite cannot otherwise express: the endpoint under test is absent
+ * by configuration, so there is nothing to assert and a red result would say
+ * nothing about the cluster's health.
+ *
+ * Two rules keep that distinction honest:
+ *
+ *  - The gate reads *configuration*, never a response. Deciding from a live
+ *    403 would also absorb a genuine permission regression, which is the
+ *    failure this suite exists to catch.
+ *  - Every gate is paired with a test that asserts the endpoint really is
+ *    absent for that configuration (see `system-api-tests.spec.ts`). Without
+ *    it, a gate that silently became wrong would remove coverage and nothing
+ *    would report it.
+ *
+ * Anything else — a token that could not be minted, a fixture that failed, a
+ * role that was not granted — is a failure, not a capability, and must stay
+ * red.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAuthorizationsEnabled = exports.absentUserMembership = exports.enforcementPrincipalUnavailable = exports.unauthenticatedAccessAllowed = exports.usersApiUnavailable = void 0;
+const config_1 = require("./config");
+/**
+ * Reason text for the `/v2/users/**` gate, or `false` when the tree is served.
+ *
+ * Playwright prints this next to the skipped test, so a reader of the report
+ * sees why the tests did not run without opening the source.
+ */
+exports.usersApiUnavailable = config_1.apiConfig.usersApiEnabled
+    ? false
+    : 'the cluster is in OIDC mode, where the identity provider owns the user ' +
+        'registry and /v2/users/** answers 403 — there is no local user to create';
+/**
+ * Reason text for the unauthenticated-rejection gate, or `false` where a
+ * missing `Authorization` header really is refused.
+ *
+ * Every `assertUnauthorized` test sends a request with no credentials and
+ * expects 401. That asserts a property of the *deployment*, not of the
+ * endpoint: c8Run answers its whole `/v2` tree without credentials — which
+ * `tests/c8Run-8.10/api-tests-v2.spec.ts` depends on, calling
+ * `/v2/process-definitions/search` unauthenticated and asserting 200 — so
+ * there the same requests return the normal response and the tests report
+ * "expected 401, got 200" against a cluster that never authenticated.
+ *
+ * It also takes `/v2/authentication/me` with it: an open cluster has no
+ * authenticated principal to describe, and it answers 401 even when the
+ * suite does send credentials.
+ *
+ * This is the third capability of the same shape as the two around it, and
+ * the distinction between them is worth keeping straight — whether a caller
+ * must be a principal at all (here), what a known principal may do
+ * (`authorizationsEnabled`), and whether the cluster keeps its own user
+ * registry (`usersApiEnabled`). A deployment can differ on each
+ * independently, and c8Run differs on all three.
+ */
+exports.unauthenticatedAccessAllowed = config_1.apiConfig.authenticationRequired
+    ? false
+    : 'this cluster serves /v2 without authentication (AUTHENTICATION_REQUIRED ' +
+        'is false), so a request carrying no credentials is answered normally ' +
+        'and the 401 this test asserts cannot occur — see tests/api/README.md';
+/**
+ * Whether the enforcement tests can obtain a second, unprivileged principal.
+ *
+ * Enforcement is only observable against a principal that is *not* the
+ * suite's admin. Two ways exist and neither is universal:
+ *
+ *  - Where local users are served, the spec creates one. Simple and
+ *    self-contained, but impossible in OIDC mode.
+ *  - In OIDC mode the cluster's principals are identity-provider clients,
+ *    which this suite cannot provision. `SECONDARY_CLIENT_ID` and
+ *    `SECONDARY_CLIENT_SECRET` name one that already exists.
+ *
+ * With neither available the tests cannot run, and the reason below says
+ * exactly what to configure. This is a real coverage gap on OIDC clusters
+ * until a second client is wired into the SM workflows — not a defect in the
+ * tests, but not something to leave unstated either.
+ *
+ * A second principal is necessary but NOT sufficient. The QA clusters do not
+ * enforce authorization at all: `.github/actions/template-helm-chart-values`
+ * initialises the admin role from three mappings only — `demo`
+ * (preferred_username), `venom` and `connectors` (client_id) — and the client
+ * this suite authenticates as, `test`, is not among them, yet it creates
+ * roles, tenants and authorizations without being refused. Nothing sets
+ * `CAMUNDA_SECURITY_AUTHORIZATIONS_ENABLED`.
+ *
+ * So wiring a client alone would not restore this coverage: the tests would
+ * fail with "expected 403, got 200", which is exactly the regression they
+ * exist to detect. Enabling enforcement on those clusters is a deliberate
+ * environment change with a blast radius beyond this suite, so it is not done
+ * here — `readAuthorizationsEnabled` reports the cluster's actual state
+ * instead, and `tests/api/README.md` records what closing the gap requires.
+ */
+function enforcementUnavailableReason() {
+    // Necessary condition one: a principal that is not the suite's admin.
+    const havePrincipal = config_1.apiConfig.usersApiEnabled ||
+        (config_1.apiConfig.secondaryClient.clientId !== '' &&
+            config_1.apiConfig.secondaryClient.clientSecret !== '');
+    if (!havePrincipal) {
+        return ('this cluster serves no local users, so an unprivileged principal must ' +
+            'be an existing identity-provider client — set SECONDARY_CLIENT_ID and ' +
+            'SECONDARY_CLIENT_SECRET to one that holds no roles');
+    }
+    // Necessary condition two, and the one this file used to state in prose
+    // without encoding: the cluster has to actually check permissions. Where it
+    // does not, every principal is permitted and these tests fail with
+    // "expected 403, got 200" — the regression they exist to catch, reported
+    // against a cluster that never had enforcement rather than against a
+    // product that lost it. c8Run is exactly that case: it serves its whole v2
+    // API unauthenticated, so a freshly created local user satisfies the
+    // principal condition while proving nothing.
+    if (!config_1.apiConfig.authorizationsEnabled) {
+        return ('this cluster does not check permissions (AUTHORIZATIONS_ENABLED is ' +
+            'false), so an unprivileged principal is permitted like any other and ' +
+            'a refusal cannot be observed — see tests/api/README.md');
+    }
+    return false;
+}
+exports.enforcementPrincipalUnavailable = enforcementUnavailableReason();
+/**
+ * What `PUT /{roles,groups,tenants}/{id}/users/{username}` does when the
+ * username belongs to nobody.
+ *
+ * The engine guards membership with
+ * `case USER -> !localUserEnabled || userState.getUser(entityId).isPresent()`
+ * (`RoleAddEntityProcessor`, `GroupAddEntityProcessor`,
+ * `TenantAddEntityProcessor` in camunda/camunda). With local users disabled
+ * the left side short-circuits, so the membership is written against the bare
+ * username and the command is accepted.
+ *
+ * That is deliberate — in OIDC mode the cluster has no registry to check a
+ * username against, and refusing would make it impossible to grant a role to
+ * an identity-provider user before their first sign-in. So the two modes
+ * genuinely differ, and the assertion has to follow the mode rather than pick
+ * one and call the other a bug.
+ */
+exports.absentUserMembership = config_1.apiConfig.usersApiEnabled
+    ? {
+        status: 404,
+        reason: 'local users are enabled, so the engine checks the username against ' +
+            'its user state and rejects an unknown one',
+    }
+    : {
+        status: 204,
+        reason: 'the cluster is in OIDC mode: with local users disabled the engine ' +
+            'skips the existence check and stores the membership by username, so ' +
+            'that a role can be granted before the user first signs in',
+    };
+/**
+ * Statuses that mean "this cluster cannot answer the question", as opposed to
+ * "something is wrong".
+ *
+ *  - 404: the endpoint is not published (before 8.10 the path is unrouted).
+ *  - 401: it answers for the *calling principal*, so a deployment that serves
+ *    /v2 without credentials has no principal for it to answer for.
+ */
+const ENFORCEMENT_UNREADABLE = new Set([401, 404]);
+/**
+ * Whether the cluster enforces authorization, straight from the cluster.
+ *
+ * `POST /v2/authentication/me/authorizations/search` carries
+ * `authorizationsEnabled` as a required field, so this is the cluster's own
+ * answer rather than an inference from the chart values. Added in 8.10.
+ *
+ * `undefined` means only the two cases above. Every other status throws
+ * instead: this reading is the safety net under the enforcement gap recorded
+ * in `tests/api/README.md`, and treating a 403, a 500 or a 503 as "unknown"
+ * would let the very regression it guards remove it. A 500 from this endpoint
+ * is a finding, not a reason to stop looking.
+ */
+async function readAuthorizationsEnabled(api) {
+    const response = await api.post('/authentication/me/authorizations/search', {
+        body: { page: { limit: 1 } },
+        tenant: 'none',
+    });
+    if (ENFORCEMENT_UNREADABLE.has(response.status()))
+        return undefined;
+    if (response.status() !== 200) {
+        throw new Error(`/v2/authentication/me/authorizations/search answered ` +
+            `${response.status()}, which is neither the enforcement state nor one ` +
+            `of the two statuses that mean this cluster cannot report it ` +
+            `(401, 404). Body: ${await response.text()}`);
+    }
+    const json = (await response.json());
+    // The field is required by the schema, so a 200 without a boolean is a
+    // contract break rather than an unreadable cluster. The caller asserts the
+    // type as well; failing here names the endpoint that broke it.
+    if (typeof json.authorizationsEnabled !== 'boolean') {
+        throw new Error(`/v2/authentication/me/authorizations/search answered 200 without a ` +
+            `boolean authorizationsEnabled, which the v2 schema marks required: ` +
+            `${JSON.stringify(json)}`);
+    }
+    return json.authorizationsEnabled;
+}
+exports.readAuthorizationsEnabled = readAuthorizationsEnabled;

package/dist/utils/api/cleanup.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Tracked-resource cleanup.
+ *
+ * The legacy shell suite cleaned up from a single EXIT trap that also computed
+ * the process exit code and ran a final batch of clock assertions — so those
+ * assertions could not fail the run, and one slow delete delayed every other.
+ * Here each test tracks what it created and the `resources` fixture deletes it
+ * when that test ends, in parallel, with failures reported but never masking a
+ * test result.
+ */
+import type { ApiClient } from './http';
+export type ResourceKind = 'user' | 'role' | 'group' | 'tenant' | 'mappingRule' | 'authorization' | 'document' | 'processInstance' | 'resource';
+export declare class ResourceTracker {
+    private readonly tracked;
+    track(kind: ResourceKind, id: string | number | undefined | null): void;
+    forget(kind: ResourceKind, id: string | number): void;
+    /**
+     * Deletes everything tracked, most-dependent kinds first so a membership does
+     * not outlive its owner. Never throws: a cleanup failure is logged, because
+     * failing here would mask the result of the test that just ran.
+     */
+    cleanup(api: ApiClient): Promise<void>;
+    private remove;
+}

package/dist/utils/api/cleanup.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Tracked-resource cleanup.
+ *
+ * The legacy shell suite cleaned up from a single EXIT trap that also computed
+ * the process exit code and ran a final batch of clock assertions — so those
+ * assertions could not fail the run, and one slow delete delayed every other.
+ * Here each test tracks what it created and the `resources` fixture deletes it
+ * when that test ends, in parallel, with failures reported but never masking a
+ * test result.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceTracker = void 0;
+const DELETE_PATHS = {
+    user: '/users/{username}',
+    role: '/roles/{roleId}',
+    group: '/groups/{groupId}',
+    tenant: '/tenants/{tenantId}',
+    mappingRule: '/mapping-rules/{mappingRuleId}',
+    authorization: '/authorizations/{authorizationKey}',
+    document: '/documents/{documentId}',
+};
+const PARAM_NAMES = {
+    user: 'username',
+    role: 'roleId',
+    group: 'groupId',
+    tenant: 'tenantId',
+    mappingRule: 'mappingRuleId',
+    authorization: 'authorizationKey',
+    document: 'documentId',
+};
+/** Statuses that mean "the resource is gone", which is all cleanup needs. */
+const GONE = new Set([200, 202, 204, 404]);
+class ResourceTracker {
+    tracked = new Map();
+    track(kind, id) {
+        if (id === undefined || id === null || id === '')
+            return;
+        const set = this.tracked.get(kind) ?? new Set();
+        set.add(String(id));
+        this.tracked.set(kind, set);
+    }
+    forget(kind, id) {
+        this.tracked.get(kind)?.delete(String(id));
+    }
+    /**
+     * Deletes everything tracked, most-dependent kinds first so a membership does
+     * not outlive its owner. Never throws: a cleanup failure is logged, because
+     * failing here would mask the result of the test that just ran.
+     */
+    async cleanup(api) {
+        const order = [
+            'processInstance',
+            'authorization',
+            'document',
+            'mappingRule',
+            'user',
+            'group',
+            'role',
+            'tenant',
+            // Last, and after `processInstance` deliberately — but the engine does
+            // not need it to be, and cleanup does not wait for the cancellations to
+            // land before getting here.
+            //
+            // `ResourceDeletionDeleteProcessor.deleteProcess` accepts the deletion
+            // either way. It writes `ProcessIntent.DRAINING`, then finalises at once
+            // when `hasActiveProcessInstances` is false and otherwise leaves the
+            // definition draining until its instances end. Identical on stable/8.8,
+            // 8.9 and 8.10.
+            //
+            // So cancelling first is an optimisation, not a precondition: it makes
+            // the common case finalise immediately instead of draining. Cancellation
+            // is asynchronous and a 204 only means the command was written, so a
+            // definition can still reach deletion with a live instance — that costs
+            // a short DRAINING window which resolves itself when the cancellation
+            // takes effect, and nothing is left behind either way. Waiting for
+            // TERMINATED here would buy that window back at the price of an
+            // exporter-lag poll in every test's teardown.
+            'resource',
+        ];
+        for (const kind of order) {
+            const ids = this.tracked.get(kind);
+            if (!ids || ids.size === 0)
+                continue;
+            const results = await Promise.allSettled([...ids].map((id) => this.remove(api, kind, id)));
+            const failed = results.filter((r) => r.status === 'rejected').length;
+            if (failed > 0) {
+                console.warn(`Cleanup: ${failed}/${ids.size} ${kind}(s) not removed`);
+            }
+            ids.clear();
+        }
+    }
+    async remove(api, kind, id) {
+        try {
+            const response = kind === 'processInstance'
+                ? await api.post('/process-instances/{processInstanceKey}/cancellation', {
+                    params: { processInstanceKey: id },
+                    body: {},
+                    tenant: 'none',
+                })
+                : kind === 'resource'
+                    ? await api.post('/resources/{resourceKey}/deletion', {
+                        params: { resourceKey: id },
+                        body: {},
+                        tenant: 'none',
+                    })
+                    : await api.delete(DELETE_PATHS[kind], {
+                        params: { [PARAM_NAMES[kind]]: id },
+                        tenant: 'none',
+                    });
+            if (!GONE.has(response.status())) {
+                console.warn(`Cleanup: ${kind} ${id} returned ${response.status()}`);
+            }
+        }
+        catch (error) {
+            console.warn(`Cleanup: ${kind} ${id} threw`, error);
+        }
+    }
+}
+exports.ResourceTracker = ResourceTracker;