@camunda/e2e-test-suite 0.0.1242 → 0.0.1244

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

@@ -0,0 +1,103 @@
+/**
+ * Environment configuration for the Orchestration Cluster REST v2 API suite.
+ *
+ * The variable names mirror those the legacy `resources/test-api-v2-complete.sh`
+ * consumed, so the CI workflows that export them keep working unchanged.
+ */
+export type AuthMethod = 'oauth2' | 'basic';
+export interface OAuthConfig {
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    audience: string;
+    scope: string;
+}
+export interface BasicAuthConfig {
+    username: string;
+    password: string;
+}
+export interface ApiConfig {
+    baseUrl: string;
+    authMethod: AuthMethod;
+    oauth: OAuthConfig;
+    basic: BasicAuthConfig;
+    /** Multi-tenancy enabled on the cluster under test (the `MT` env var). */
+    multiTenancy: boolean;
+    /** Tenant applied to every tenant-aware request when `multiTenancy` is on. */
+    tenantId: string;
+    /** Minor version under test, e.g. `8.8`. Gates version-specific expectations. */
+    zeebeVersion: string;
+    /**
+     * Whether the cluster serves `/v2/users/**` at all.
+     *
+     * In OIDC mode the identity provider owns the user registry, so the
+     * orchestration cluster registers a filter that answers every request under
+     * `/v2/users/**` with 403 and the detail "Users API is disabled because the
+     * application is configured in OIDC mode" — see `ApiFiltersConfiguration` in
+     * camunda/camunda, gated on `@ConditionalOnAuthenticationMethod(OIDC)`.
+     * There is no local user to create, so a spec that needs one cannot run.
+     *
+     * This is read from configuration rather than inferred from a 403 at
+     * runtime, deliberately: sniffing the status would also swallow a genuine
+     * permission regression, which is the failure this suite exists to catch.
+     */
+    usersApiEnabled: boolean;
+    /**
+     * Whether the cluster checks permissions at all (`AUTHORIZATIONS_ENABLED`).
+     *
+     * An unprivileged principal proves nothing on a cluster that permits
+     * everyone: the enforcement tests would fail with "expected 403, got 200",
+     * which is the regression they exist to detect rather than a real one. So
+     * the gate needs this as well as a principal.
+     *
+     * Defaults to `true` — assume a cluster enforces unless its workflow says
+     * otherwise. The opposite default would silently drop enforcement coverage
+     * on every deployment that never sets the variable, and quietly losing the
+     * security tests is worse than a loud failure. A deployment that is known
+     * not to enforce declares it: `c8Run` serves its whole v2 API
+     * unauthenticated, which `tests/c8Run-8.10/api-tests-v2.spec.ts` relies on.
+     *
+     * `readAuthorizationsEnabled` in `capabilities.ts` reports what the cluster
+     * actually answers, so a wrong value here shows up in the run rather than
+     * hiding.
+     */
+    authorizationsEnabled: boolean;
+    /**
+     * Whether the cluster requires authentication at all
+     * (`AUTHENTICATION_REQUIRED`).
+     *
+     * Distinct from `authorizationsEnabled`, which is about what a *known*
+     * principal may do. This is about whether a caller has to be one: c8Run
+     * answers its whole `/v2` tree without credentials, which
+     * `tests/c8Run-8.10/api-tests-v2.spec.ts` relies on, so a request sent with
+     * no `Authorization` header is served normally and the 401 the suite
+     * asserts cannot happen.
+     *
+     * Defaults to `true`, for the same reason as `authorizationsEnabled`: a
+     * deployment that authenticates should not have to declare it, and the
+     * opposite default would silently drop every unauthenticated-rejection test
+     * wherever the variable is unset.
+     */
+    authenticationRequired: boolean;
+    /**
+     * A second OAuth2 client used as the *unprivileged* principal by the
+     * authorization enforcement tests.
+     *
+     * Enforcement can only be observed with a principal other than the suite's
+     * own admin. Where local users exist the tests create one; in OIDC mode
+     * they cannot, and the cluster's principals are identity-provider clients
+     * that this suite has no way to provision. Supplying one here is what lets
+     * enforcement run on an OIDC cluster.
+     */
+    secondaryClient: {
+        clientId: string;
+        clientSecret: string;
+    };
+}
+export declare function loadApiConfig(): ApiConfig;
+export declare const apiConfig: ApiConfig;
+/**
+ * True when the cluster runs at or above `minor`, e.g. `atLeastVersion('8.9')`.
+ * Used to gate expectations for endpoints that only exist from a given release.
+ */
+export declare function atLeastVersion(minor: string): boolean;

package/dist/utils/api/config.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Environment configuration for the Orchestration Cluster REST v2 API suite.
+ *
+ * The variable names mirror those the legacy `resources/test-api-v2-complete.sh`
+ * consumed, so the CI workflows that export them keep working unchanged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.atLeastVersion = exports.apiConfig = exports.loadApiConfig = void 0;
+function env(name, fallback = '') {
+    const value = process.env[name];
+    return value === undefined || value === '' ? fallback : value;
+}
+function loadApiConfig() {
+    const hostPrefix = env('HOST_PREFIX', 'qa-update-mt');
+    const clientId = env('CLIENT_ID', 'demo');
+    const authMethod = env('AUTH_METHOD', 'oauth2');
+    return {
+        baseUrl: env('BASE_URL', `https://${hostPrefix}.ci.distro.ultrawombat.com/orchestration`).replace(/\/+$/, ''),
+        authMethod,
+        oauth: {
+            tokenUrl: env('TOKEN_URL', `https://${hostPrefix}.ci.distro.ultrawombat.com/auth/realms/camunda-platform/protocol/openid-connect/token`),
+            clientId,
+            clientSecret: env('CLIENT_SECRET', clientId),
+            audience: env('AUDIENCE', 'orchestration-api'),
+            scope: env('SCOPE'),
+        },
+        basic: {
+            username: env('BASIC_AUTH_USER'),
+            password: env('BASIC_AUTH_PASSWORD'),
+        },
+        multiTenancy: env('MT', 'true') === 'true',
+        tenantId: env('TENANT_ID', '<default>'),
+        zeebeVersion: env('ZEEBE_VERSION', '8.8'),
+        // The SM Helm flows this suite runs in deploy Keycloak and drive the API
+        // with client credentials, so `oauth2` means the cluster is in OIDC mode.
+        // `USERS_API_ENABLED` overrides that for a deployment where the two come
+        // apart, rather than leaving the suite to guess.
+        usersApiEnabled: env('USERS_API_ENABLED', String(authMethod !== 'oauth2')) === 'true',
+        authorizationsEnabled: env('AUTHORIZATIONS_ENABLED', 'true') === 'true',
+        authenticationRequired: env('AUTHENTICATION_REQUIRED', 'true') === 'true',
+        secondaryClient: {
+            clientId: env('SECONDARY_CLIENT_ID'),
+            clientSecret: env('SECONDARY_CLIENT_SECRET'),
+        },
+    };
+}
+exports.loadApiConfig = loadApiConfig;
+exports.apiConfig = loadApiConfig();
+/**
+ * True when the cluster runs at or above `minor`, e.g. `atLeastVersion('8.9')`.
+ * Used to gate expectations for endpoints that only exist from a given release.
+ */
+function atLeastVersion(minor) {
+    const parse = (v) => v.split('.').map((part) => parseInt(part, 10));
+    const [major, minorPart] = parse(exports.apiConfig.zeebeVersion);
+    const [reqMajor, reqMinor] = parse(minor);
+    if (Number.isNaN(major) || Number.isNaN(minorPart))
+        return true;
+    return major > reqMajor || (major === reqMajor && minorPart >= reqMinor);
+}
+exports.atLeastVersion = atLeastVersion;

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

@@ -0,0 +1,45 @@
+/**
+ * Deployment helpers.
+ *
+ * Deployment is the setup step for most of this suite, so it asserts hard: a
+ * silent deployment failure in the shell suite left every downstream assertion
+ * comparing against an empty key, which then "passed" against a 404-tolerant
+ * expectation.
+ */
+import { type APIResponse } from '@playwright/test';
+import type { ApiClient } from './http';
+import type { ResourceTracker } from './cleanup';
+export interface DeployedProcess {
+    processDefinitionKey: string;
+    processDefinitionId: string;
+    version: number;
+    deploymentKey: string;
+}
+export interface DeployedDecision {
+    decisionDefinitionKey: string;
+    decisionDefinitionId: string;
+    decisionRequirementsKey: string;
+}
+interface DeploymentResource {
+    name: string;
+    content: string;
+    mimeType?: string;
+}
+/**
+ * Uploads resources to `/v2/deployments` as multipart form data, and tracks
+ * whatever they deployed for cleanup.
+ *
+ * On a multi-tenant cluster the tenant is a form field rather than a query
+ * parameter. The shell suite wrote the tenant to a temp file and used curl's
+ * `-F name=<file` syntax, because the default tenant id `<default>` starts with
+ * `<` and curl would otherwise read it as a filename; Playwright takes the
+ * value directly, so that whole dance disappears.
+ *
+ * `resources` is the spec's `ResourceTracker` fixture and is required rather
+ * than optional on purpose: an optional tracker is one a new spec forgets, and
+ * nothing in the run would report the leak.
+ */
+export declare function deployResources(api: ApiClient, resources: ResourceTracker, files: DeploymentResource[]): Promise<APIResponse>;
+export declare function deployProcess(api: ApiClient, resources: ResourceTracker, processId: string, xml: string): Promise<DeployedProcess>;
+export declare function deployDecision(api: ApiClient, resources: ResourceTracker, decisionId: string, dmn: string): Promise<DeployedDecision>;
+export {};

package/dist/utils/api/deployments.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Deployment helpers.
+ *
+ * Deployment is the setup step for most of this suite, so it asserts hard: a
+ * silent deployment failure in the shell suite left every downstream assertion
+ * comparing against an empty key, which then "passed" against a 404-tolerant
+ * expectation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deployDecision = exports.deployProcess = exports.deployResources = void 0;
+const test_1 = require("@playwright/test");
+const config_1 = require("./config");
+const assertions_1 = require("./assertions");
+/**
+ * Registers every definition a deployment created so the spec's tracker
+ * deletes it.
+ *
+ * A definition is durable: it stays on the cluster and in its indices until
+ * something removes it, so an untracked deployment survives the run and the
+ * next nightly adds its own on top.
+ *
+ * Which key addresses the deletable resource differs by type. For a process it
+ * is the definition key. For a decision it is the *requirements* key: one DMN
+ * file deploys as a single DRD resource that may carry several decisions, and
+ * `/resources/{resourceKey}/deletion` addresses the resource, not a decision
+ * inside it — so tracking the decision keys instead would ask the cluster to
+ * delete the same resource once per decision.
+ */
+async function trackDeployment(resources, response) {
+    // Deployment failures are asserted on by their own tests; there is nothing
+    // to clean up when nothing was created.
+    if (response.status() !== 200)
+        return;
+    const json = (await response.json());
+    for (const entry of json.deployments ?? []) {
+        resources.track('resource', entry.processDefinition?.processDefinitionKey ??
+            entry.decisionRequirements?.decisionRequirementsKey ??
+            entry.form?.formKey);
+    }
+}
+/**
+ * Uploads resources to `/v2/deployments` as multipart form data, and tracks
+ * whatever they deployed for cleanup.
+ *
+ * On a multi-tenant cluster the tenant is a form field rather than a query
+ * parameter. The shell suite wrote the tenant to a temp file and used curl's
+ * `-F name=<file` syntax, because the default tenant id `<default>` starts with
+ * `<` and curl would otherwise read it as a filename; Playwright takes the
+ * value directly, so that whole dance disappears.
+ *
+ * `resources` is the spec's `ResourceTracker` fixture and is required rather
+ * than optional on purpose: an optional tracker is one a new spec forgets, and
+ * nothing in the run would report the leak.
+ */
+async function deployResources(api, resources, files) {
+    // Every file must be sent under the same field name: the endpoint binds
+    // `@RequestPart("resources") List<MultipartFile>` (`ResourceController` in
+    // camunda/camunda), so Spring collects the parts literally named
+    // `resources` and ignores any other name.
+    //
+    // Playwright's object form of `multipart` is keyed, so it cannot repeat a
+    // name — an earlier attempt to work around that by numbering the extra
+    // parts (`resources1`, `resources2`, …) did not fail, it silently deployed
+    // only the first file. `FormData` can repeat the name, so use it.
+    const form = new FormData();
+    for (const file of files) {
+        form.append('resources', new Blob([file.content], {
+            type: file.mimeType ?? 'application/xml',
+        }), file.name);
+    }
+    if (config_1.apiConfig.multiTenancy) {
+        form.append('tenantId', config_1.apiConfig.tenantId);
+    }
+    const response = await api.post('/deployments', {
+        multipart: form,
+        tenant: 'none',
+    });
+    await trackDeployment(resources, response);
+    return response;
+}
+exports.deployResources = deployResources;
+async function deployProcess(api, resources, processId, xml) {
+    const response = await deployResources(api, resources, [
+        { name: `${processId}.bpmn`, content: xml },
+    ]);
+    await (0, assertions_1.assertStatus)(response, 200);
+    const json = await response.json();
+    const deployment = (json.deployments ?? []).find((entry) => entry.processDefinition !== undefined);
+    (0, test_1.expect)(deployment, `deployment response carried no processDefinition: ${JSON.stringify(json)}`).toBeTruthy();
+    const definition = deployment.processDefinition;
+    return {
+        processDefinitionKey: String(definition.processDefinitionKey),
+        processDefinitionId: String(definition.processDefinitionId),
+        // The deployment result names this `processDefinitionVersion`, while the
+        // search and get-by-key results name the same number `version`. The two
+        // schemas genuinely differ (`DeploymentProcessResult` vs
+        // `ProcessDefinitionResult` in camunda/camunda), and reading `version`
+        // here yielded NaN, which then compared unequal to every real version.
+        version: Number(definition.processDefinitionVersion),
+        deploymentKey: String(json.deploymentKey),
+    };
+}
+exports.deployProcess = deployProcess;
+async function deployDecision(api, resources, decisionId, dmn) {
+    const response = await deployResources(api, resources, [
+        { name: `${decisionId}.dmn`, content: dmn },
+    ]);
+    await (0, assertions_1.assertStatus)(response, 200);
+    const json = await response.json();
+    const deployment = (json.deployments ?? []).find((entry) => entry.decisionDefinition !== undefined);
+    (0, test_1.expect)(deployment, `deployment response carried no decisionDefinition: ${JSON.stringify(json)}`).toBeTruthy();
+    const definition = deployment.decisionDefinition;
+    return {
+        decisionDefinitionKey: String(definition.decisionDefinitionKey),
+        decisionDefinitionId: String(definition.decisionDefinitionId),
+        decisionRequirementsKey: String(definition.decisionRequirementsKey),
+    };
+}
+exports.deployDecision = deployDecision;

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

@@ -0,0 +1,36 @@
+/**
+ * Waiting helpers for the search index's eventual consistency.
+ *
+ * Writes go to the engine, reads come from the search store, and the exporter
+ * between them lags. The legacy shell suite bridged that with 81 fixed `sleep`
+ * calls totalling 181 seconds — which both slowed every green run and still
+ * flaked whenever the exporter was slower than the guess. These poll instead,
+ * so a fast cluster returns immediately and a slow one still passes.
+ */
+/**
+ * Generous enough for exporter lag on a loaded Helm cluster, bounded enough
+ * that a genuinely missing record fails the test rather than the suite timeout.
+ */
+export declare const SEARCH_TIMEOUT_MS = 60000;
+export declare const SEARCH_INTERVALS_MS: number[];
+export declare const searchAssertionOptions: {
+    timeout: number;
+    intervals: number[];
+};
+/**
+ * Retries `assertion` until it stops throwing. Use for any read-back of
+ * something just written through the engine.
+ */
+export declare function eventually(assertion: () => Promise<void> | void, options?: {
+    timeout?: number;
+    intervals?: number[];
+}): Promise<void>;
+/**
+ * Polls `produce` until `predicate` accepts its result, then returns it.
+ * Use when the test needs the value, not just the fact that it appeared.
+ */
+export declare function eventuallyGet<T>(produce: () => Promise<T>, predicate: (value: T) => boolean, options?: {
+    timeout?: number;
+    intervals?: number[];
+    description?: string;
+}): Promise<T>;

package/dist/utils/api/eventually.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Waiting helpers for the search index's eventual consistency.
+ *
+ * Writes go to the engine, reads come from the search store, and the exporter
+ * between them lags. The legacy shell suite bridged that with 81 fixed `sleep`
+ * calls totalling 181 seconds — which both slowed every green run and still
+ * flaked whenever the exporter was slower than the guess. These poll instead,
+ * so a fast cluster returns immediately and a slow one still passes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventuallyGet = exports.eventually = exports.searchAssertionOptions = exports.SEARCH_INTERVALS_MS = exports.SEARCH_TIMEOUT_MS = void 0;
+const test_1 = require("@playwright/test");
+/**
+ * Generous enough for exporter lag on a loaded Helm cluster, bounded enough
+ * that a genuinely missing record fails the test rather than the suite timeout.
+ */
+exports.SEARCH_TIMEOUT_MS = 60000;
+exports.SEARCH_INTERVALS_MS = [500, 1000, 2000, 2000, 5000];
+exports.searchAssertionOptions = {
+    timeout: exports.SEARCH_TIMEOUT_MS,
+    intervals: exports.SEARCH_INTERVALS_MS,
+};
+/**
+ * Retries `assertion` until it stops throwing. Use for any read-back of
+ * something just written through the engine.
+ */
+async function eventually(assertion, options = {}) {
+    await (0, test_1.expect)(async () => {
+        await assertion();
+    }).toPass({
+        timeout: options.timeout ?? exports.SEARCH_TIMEOUT_MS,
+        intervals: options.intervals ?? exports.SEARCH_INTERVALS_MS,
+    });
+}
+exports.eventually = eventually;
+/**
+ * Polls `produce` until `predicate` accepts its result, then returns it.
+ * Use when the test needs the value, not just the fact that it appeared.
+ */
+async function eventuallyGet(produce, predicate, options = {}) {
+    let last;
+    await (0, test_1.expect)(async () => {
+        last = await produce();
+        if (!predicate(last)) {
+            throw new Error(`${options.description ?? 'Value'} not ready yet: ${JSON.stringify(last)?.slice(0, 500)}`);
+        }
+    }).toPass({
+        timeout: options.timeout ?? exports.SEARCH_TIMEOUT_MS,
+        intervals: options.intervals ?? exports.SEARCH_INTERVALS_MS,
+    });
+    return last;
+}
+exports.eventuallyGet = eventuallyGet;

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

@@ -0,0 +1,56 @@
+/**
+ * HTTP client for the Orchestration Cluster REST v2 API.
+ *
+ * Wraps Playwright's `APIRequestContext` with the three things a Helm-deployed
+ * cluster needs and a localhost one does not: pluggable auth (see `auth.ts`),
+ * tenant propagation (see `tenancy.ts`), and tolerance of the ingress dropping
+ * requests while orchestration pods roll during an upgrade.
+ */
+import type { APIRequestContext, APIResponse } from '@playwright/test';
+import { type ApiConfig } from './config';
+import type { ApiPath } from './paths';
+import { type TenantMode } from './tenancy';
+export type { ApiPath, TenantMode };
+type QueryValue = string | number | boolean | undefined;
+export interface RequestOptions {
+    /** Values for `{placeholder}` segments of the path template. */
+    params?: Record<string, string | number>;
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    /** Where the tenant goes for this endpoint. Defaults to `auto`. */
+    tenant?: TenantMode;
+    /**
+     * Overrides the suite principal's `Authorization` header. Pass `null` to send
+     * no credentials at all, which the unauthenticated assertions rely on.
+     */
+    authorization?: string | null;
+    headers?: Record<string, string>;
+    /**
+     * Multipart body for deployment uploads. `FormData` rather than a plain
+     * object where a field name repeats — `/v2/deployments` takes every file
+     * under the single name `resources`, which a keyed object cannot express.
+     */
+    multipart?: FormData | Record<string, unknown>;
+}
+export declare class ApiClient {
+    private readonly request;
+    private readonly config;
+    constructor(request: APIRequestContext, config?: ApiConfig);
+    /**
+     * Expands a path template against the shared `/v2` prefix.
+     *
+     * Throws on a missing placeholder rather than emitting a literal `{key}` in
+     * the URL: the gateway answers such a path with a plausible 404, so a test
+     * asserting 404 would pass without exercising anything.
+     */
+    buildUrl(path: ApiPath, params?: Record<string, string | number>, query?: Record<string, QueryValue>): string;
+    private headersFor;
+    private send;
+    get(path: ApiPath, options?: RequestOptions): Promise<APIResponse>;
+    post(path: ApiPath, options?: RequestOptions): Promise<APIResponse>;
+    put(path: ApiPath, options?: RequestOptions): Promise<APIResponse>;
+    patch(path: ApiPath, options?: RequestOptions): Promise<APIResponse>;
+    delete(path: ApiPath, options?: RequestOptions): Promise<APIResponse>;
+    /** Raw request for the handful of cases needing a non-JSON content type. */
+    raw(method: 'get' | 'post' | 'put' | 'patch' | 'delete', path: ApiPath, options?: RequestOptions): Promise<APIResponse>;
+}