chore: rehaul DevX (#10571)

# Which Problems Are Solved Replaces Turbo by Nx and lays the foundation for the next CI improvements. It enables using Nx Cloud to speed the up the pipelines that affect any node package. It streamlines the dev experience for frontend and backend developers by providing the following commands: | Task | Command | Notes | |------|---------|--------| | **Production** | `nx run PROJECT:prod` | Production server | | **Develop** | `nx run PROJECT:dev` | Hot reloading development server | | **Test** | `nx run PROJECT:test` | Run all tests | | **Lint** | `nx run PROJECT:lint` | Check code style | | **Lint Fix** | `nx run PROJECT:lint-fix` | Auto-fix style issues | The following values can be used for PROJECT: - @zitadel/zitadel (root commands) - @zitadel/api, - @zitadel/login, - @zitadel/console, - @zitadel/docs, - @zitadel/client - @zitadel/proto The project names and folders are streamlined: | Old Folder | New Folder | | --- | --- | | ./e2e | ./tests/functional-ui | | ./load-test | ./benchmark | | ./build/zitadel | ./apps/api | | ./console | ./apps/console (postponed so the PR is reviewable) | Also, all references to the TypeScript repo are removed so we can archive it. # How the Problems Are Solved - Ran `npx nx@latest init` - Replaced all turbo.json by project.json and fixed the target configs - Removed Turbo dependency - All JavaScript related code affected by a PRs changes is quality-checked using the `nx affected` command - We move PR checks that are runnable using Nx into the `check` workflow. For workflows where we don't use Nx, yet, we restore previously built dependency artifacts from Nx. - We only use a single and easy to understand dev container - The CONTRIBUTING.md is streamlined - The setup with a generated client pat is orchestrated with Nx - Everything related to the TypeScript repo is updated or removed. A **Deploy with Vercel** button is added to the docs and the CONTRIBUTING.md. # Additional Changes - NPM package names have a consistent pattern. - Docker bake is removed. The login container is built and released like the core container. - The integration tests build the login container before running, so they don't rely on the login container action anymore. This fixes consistently failing checks on PRs from forks. - The docs build in GitHub actions is removed, as we already build on Vercel. # Additional Context - Internal discussion: https://zitadel.slack.com/archives/C087ADF8LRX/p1756277884928169 - Workflow dispatch test: https://github.com/zitadel/zitadel/actions/runs/17760122959 --------- Co-authored-by: Florian Forster <[email protected]> Co-authored-by: Tim Möhlmann <[email protected]> Co-authored-by: Copilot <[email protected]>
2026-11-09 23:55:12 +00:00 · 2025-10-08 10:27:02 +02:00
parent e47acaeef2
commit f69a6ed4f3
236 changed files with 5708 additions and 6549 deletions
@@ -0,0 +1,39 @@
+import { login, User } from 'support/login/users';
+import { API, SystemAPI, Token } from './types';
+
+const authHeaderKey = 'Authorization',
+  orgIdHeaderKey = 'x-zitadel-orgid',
+  backendUrl = Cypress.env('BACKEND_URL');
+
+export function apiAuth(): Cypress.Chainable<API> {
+  return login(User.IAMAdminUser, 'Password1!', false, true).then((token) => {
+    return <API>{
+      token: token,
+      mgmtBaseURL: `${backendUrl}/management/v1`,
+      adminBaseURL: `${backendUrl}/admin/v1`,
+      authBaseURL: `${backendUrl}/auth/v1`,
+      assetsBaseURL: `${backendUrl}/assets/v1`,
+      oauthBaseURL: `${backendUrl}/oauth/v2`,
+      oidcBaseURL: `${backendUrl}/oidc/v1`,
+      samlBaseURL: `${backendUrl}/saml/v2`,
+      featuresBaseURL: `${backendUrl}/v2/features`,
+    };
+  });
+}
+
+export function systemAuth(): Cypress.Chainable<SystemAPI> {
+  return cy.task('systemToken').then((token) => {
+    return <SystemAPI>{
+      token: token,
+      baseURL: `${backendUrl}/system/v1`,
+    };
+  });
+}
+
+export function requestHeaders(token: Token, orgId?: string): object {
+  const headers = { [authHeaderKey]: `Bearer ${token.token}` };
+  if (orgId) {
+    headers[orgIdHeaderKey] = orgId;
+  }
+  return headers;
+}
@@ -0,0 +1,124 @@
+import { requestHeaders } from './apiauth';
+import { findFromList as mapFromList, searchSomething } from './search';
+import { API, Entity, SearchResult, Token } from './types';
+
+export function ensureItemExists(
+  token: Token,
+  searchPath: string,
+  findInList: (entity: Entity) => boolean,
+  createPath: string,
+  body: Entity,
+  orgId?: string,
+  newItemIdField: string = 'id',
+  searchItemIdField?: string,
+) {
+  return ensureSomething(
+    token,
+    () => searchSomething(token, searchPath, 'POST', mapFromList(findInList, searchItemIdField), orgId),
+    () => createPath,
+    'POST',
+    body,
+    (entity) => !!entity,
+    (body) => body[newItemIdField],
+    orgId,
+  );
+}
+
+export function ensureItemDoesntExist(
+  token: Token,
+  searchPath: string,
+  findInList: (entity: Entity) => boolean,
+  deletePath: (entity: Entity) => string,
+  orgId?: string,
+): Cypress.Chainable<null> {
+  return ensureSomething(
+    token,
+    () => searchSomething(token, searchPath, 'POST', mapFromList(findInList), orgId),
+    deletePath,
+    'DELETE',
+    null,
+    (entity) => !entity,
+  ).then(() => null);
+}
+
+export function ensureSetting(
+  api: API,
+  path: string,
+  mapResult: (entity: any) => SearchResult,
+  createPath: string,
+  body: any,
+  orgId?: string,
+): Cypress.Chainable<string> {
+  return ensureSomething(
+    api,
+    () => searchSomething(api, path, 'GET', mapResult, orgId),
+    () => createPath,
+    'PUT',
+    body,
+    (entity) => !!entity,
+  );
+}
+
+function awaitDesired(
+  trials: number,
+  expectEntity: (entity: Entity) => boolean,
+  search: () => Cypress.Chainable<SearchResult>,
+  initialSequence?: number,
+) {
+  return search().then((resp) => {
+    const foundExpectedEntity = expectEntity(resp.entity);
+    const foundExpectedSequence = !initialSequence || resp.sequence >= initialSequence;
+
+    const check = !foundExpectedEntity || !foundExpectedSequence;
+    if (check) {
+      expect(trials, `trying ${trials} more times`).to.be.greaterThan(0);
+      cy.wait(1000);
+      return awaitDesired(trials - 1, expectEntity, search, initialSequence);
+    }
+  });
+}
+
+interface EnsuredResult {
+  id: string;
+  sequence: number;
+}
+
+export function ensureSomething(
+  token: Token,
+  search: () => Cypress.Chainable<SearchResult>,
+  apiPath: (entity: Entity) => string,
+  ensureMethod: string,
+  body: Entity,
+  expectEntity: (entity: Entity) => boolean,
+  mapId?: (body: any) => string,
+  orgId?: string,
+): Cypress.Chainable<string> {
+  return search()
+    .then((sRes) => {
+      if (expectEntity(sRes.entity)) {
+        return cy.wrap(<EnsuredResult>{ id: sRes.id, sequence: sRes.sequence });
+      }
+
+      return cy
+        .request({
+          method: ensureMethod,
+          url: apiPath(sRes.entity),
+          headers: requestHeaders(token, orgId),
+          body: body,
+          failOnStatusCode: false,
+          followRedirect: false,
+        })
+        .then((cRes) => {
+          expect(cRes.status).to.equal(200);
+          return <EnsuredResult>{
+            id: mapId ? mapId(cRes.body) : undefined,
+            sequence: sRes.sequence,
+          };
+        });
+    })
+    .then((data) => {
+      return awaitDesired(90, expectEntity, search, data.sequence).then(() => {
+        return cy.wrap(data.id);
+      });
+    });
+}
@@ -0,0 +1,31 @@
+import { ensureSetting } from './ensure';
+import { API } from './types';
+
+export function ensureExternalLinksSettingsSet(api: API, tosLink: string, privacyPolicyLink: string, docsLink: string) {
+  return ensureSetting(
+    api,
+    `${api.adminBaseURL}/policies/privacy`,
+    (body: any) => {
+      const result = {
+        sequence: body.policy?.details?.sequence,
+        id: body.policy.id,
+        entity: null,
+      };
+      if (
+        body.policy &&
+        (body.policy.tosLink || '') === tosLink &&
+        (body.policy.privacyLink || '') === privacyPolicyLink &&
+        (body.policy.docsLink || '') === docsLink
+      ) {
+        return { ...result, entity: body.policy };
+      }
+      return result;
+    },
+    `${api.adminBaseURL}/policies/privacy`,
+    {
+      tosLink,
+      privacyLink: privacyPolicyLink,
+      docsLink,
+    },
+  );
+}
@@ -0,0 +1,59 @@
+import { API } from './types';
+
+export function getInstanceFeatures(api: API) {
+  return cy.request({
+    method: 'GET',
+    url: `${api.featuresBaseURL}/instance`,
+    headers: {
+      authorization: `Bearer ${api.token}`,
+    },
+    body: {},
+  });
+}
+
+export function setInstanceFeature(api: API, feature: string, enabled: boolean, additionalConfig?: Record<string, any>) {
+  const body: Record<string, any> = {
+    [feature]: enabled,
+    ...additionalConfig,
+  };
+
+  return cy.request({
+    method: 'PUT',
+    url: `${api.featuresBaseURL}/instance`,
+    headers: {
+      authorization: `Bearer ${api.token}`,
+    },
+    body,
+  });
+}
+
+export function resetInstanceFeatures(api: API) {
+  return cy.request({
+    method: 'DELETE',
+    url: `${api.featuresBaseURL}/instance`,
+    headers: {
+      authorization: `Bearer ${api.token}`,
+    },
+  });
+}
+
+export function ensureFeatureState(api: API, feature: string, enabled: boolean, additionalConfig?: Record<string, any>) {
+  return getInstanceFeatures(api).then((response) => {
+    const currentState = response.body?.[feature]?.enabled;
+
+    if (currentState !== enabled) {
+      return setInstanceFeature(api, feature, enabled, additionalConfig);
+    }
+
+    return cy.wrap(response);
+  });
+}
+
+export function ensureLoginV2FeatureState(api: API, required: boolean, baseUri?: string) {
+  return setInstanceFeature(api, 'loginV2', required, {
+    loginV2: {
+      required,
+      baseUri: baseUri || '',
+    },
+  });
+}
@@ -0,0 +1,32 @@
+import { Context } from 'support/commands';
+import { ensureItemDoesntExist, ensureItemExists } from './ensure';
+import { getOrgUnderTest } from './orgs';
+import { API, Entity } from './types';
+
+export function ensureProjectGrantExists(ctx: Context, foreignOrgId: string, foreignProjectId: string) {
+  return getOrgUnderTest(ctx).then((orgUnderTest) => {
+    return ensureItemExists(
+      ctx.api,
+      `${ctx.api.mgmtBaseURL}/projectgrants/_search`,
+      (grant: any) => grant.grantedOrgId == orgUnderTest && grant.projectId == foreignProjectId,
+      `${ctx.api.mgmtBaseURL}/projects/${foreignProjectId}/grants`,
+      { granted_org_id: orgUnderTest },
+      foreignOrgId,
+      'grantId',
+      'grantId',
+    );
+  });
+}
+
+export function ensureProjectGrantDoesntExist(ctx: Context, projectId: number, foreignOrgId: string) {
+  return getOrgUnderTest(ctx).then((orgUnderTest) => {
+    console.log('removing grant to foreignOrgId', foreignOrgId, 'in orgUnderTest', orgUnderTest, 'projectId', projectId);
+    return ensureItemDoesntExist(
+      ctx.api,
+      `${ctx.api.mgmtBaseURL}/projectgrants/_search`,
+      (grant: any) => grant.grantedOrgId == foreignOrgId && grant.projectId == projectId,
+      (grant: any) => `${ctx.api.mgmtBaseURL}/projects/${projectId}/grants/${grant.grantId}`,
+      orgUnderTest.toString(),
+    );
+  });
+}
@@ -0,0 +1,31 @@
+import { SystemAPI } from './types';
+
+export function instanceUnderTest(api: SystemAPI): Cypress.Chainable<string> {
+  return cy
+    .request({
+      method: 'POST',
+      url: `${api.baseURL}/instances/_search`,
+      auth: {
+        bearer: api.token,
+      },
+    })
+    .then((res) => {
+      const instances = <Array<any>>res.body.result;
+      expect(instances.length).to.equal(
+        1,
+        'instanceUnderTest just supports running against an API with exactly one instance, yet',
+      );
+      return instances[0].id;
+    });
+}
+
+export function getInstance(api: SystemAPI, instanceId: string, failOnStatusCode = true) {
+  return cy.request({
+    method: 'GET',
+    url: `${api.baseURL}/instances/${instanceId}`,
+    auth: {
+      bearer: api.token,
+    },
+    failOnStatusCode: failOnStatusCode,
+  });
+}
@@ -0,0 +1,76 @@
+import { ensureItemDoesntExist, ensureItemExists } from './ensure';
+import { findFromList, searchSomething } from './search';
+import { API } from './types';
+
+export function ensureHumanIsNotOrgMember(api: API, username: string) {
+  return ensureItemDoesntExist(
+    api,
+    `${api.mgmtBaseURL}/orgs/me/members/_search`,
+    (member: any) => (<string>member.preferredLoginName).startsWith(username),
+    (member) => `${api.mgmtBaseURL}/orgs/me/members/${member.userId}`,
+  );
+}
+
+export function ensureHumanIsOrgMember(api: API, username: string, roles: string[]) {
+  return searchSomething(
+    api,
+    `${api.mgmtBaseURL}/users/_search`,
+    'POST',
+    findFromList((user) => {
+      return user.userName == username;
+    }),
+  ).then((user) => {
+    return ensureItemExists(
+      api,
+      `${api.mgmtBaseURL}/orgs/me/members/_search`,
+      (member: any) => member.userId == user.entity.id,
+      `${api.mgmtBaseURL}/orgs/me/members`,
+      {
+        userId: user.entity.id,
+        roles: roles,
+      },
+    );
+  });
+}
+
+export function ensureHumanIsNotProjectMember(
+  api: API,
+  projectId: string,
+  username: string,
+  grantId?: string,
+): Cypress.Chainable<string> {
+  return ensureItemDoesntExist(
+    api,
+    `${api.mgmtBaseURL}/projects/${projectId}/${grantId ? `grants/${grantId}/` : ''}members/_search`,
+    (member: any) => (<string>member.preferredLoginName).startsWith(username),
+    (member) => `${api.mgmtBaseURL}/projects/${projectId}/${grantId ? `grants/${grantId}/` : ''}members/${member.userId}`,
+  );
+}
+
+export function ensureHumanIsProjectMember(
+  api: API,
+  projectId: string,
+  username: string,
+  roles: string[],
+  grantId?: string,
+): Cypress.Chainable<string> {
+  return searchSomething(
+    api,
+    `${api.mgmtBaseURL}/users/_search`,
+    'POST',
+    findFromList((user) => {
+      return user.userName == username;
+    }),
+  ).then((user) => {
+    return ensureItemExists(
+      api,
+      `${api.mgmtBaseURL}/projects/${projectId}/${grantId ? `grants/${grantId}/` : ''}members/_search`,
+      (member: any) => member.userId == user.entity.id,
+      `${api.mgmtBaseURL}/projects/${projectId}/${grantId ? `grants/${grantId}/` : ''}members`,
+      {
+        userId: user.entity.id,
+        roles: roles,
+      },
+    );
+  });
+}
@@ -0,0 +1,47 @@
+import { ensureSetting } from './ensure';
+import { API } from './types';
+
+export function ensureOIDCSettingsSet(
+  api: API,
+  accessTokenLifetime: number,
+  idTokenLifetime: number,
+  refreshTokenExpiration: number,
+  refreshTokenIdleExpiration: number,
+) {
+  return ensureSetting(
+    api,
+    `${api.adminBaseURL}/settings/oidc`,
+    (body: any) => {
+      const result = {
+        sequence: body.settings?.details?.sequence,
+        id: body.settings.id,
+        entity: null,
+      };
+
+      if (
+        body.settings &&
+        body.settings.accessTokenLifetime === hoursToDuration(accessTokenLifetime) &&
+        body.settings.idTokenLifetime === hoursToDuration(idTokenLifetime) &&
+        body.settings.refreshTokenExpiration === daysToDuration(refreshTokenExpiration) &&
+        body.settings.refreshTokenIdleExpiration === daysToDuration(refreshTokenIdleExpiration)
+      ) {
+        return { ...result, entity: body.settings };
+      }
+      return result;
+    },
+    `${api.adminBaseURL}/settings/oidc`,
+    {
+      accessTokenLifetime: hoursToDuration(accessTokenLifetime),
+      idTokenLifetime: hoursToDuration(idTokenLifetime),
+      refreshTokenExpiration: daysToDuration(refreshTokenExpiration),
+      refreshTokenIdleExpiration: daysToDuration(refreshTokenIdleExpiration),
+    },
+  );
+}
+
+function hoursToDuration(hours: number): string {
+  return (hours * 3600).toString() + 's';
+}
+function daysToDuration(days: number): string {
+  return hoursToDuration(24 * days);
+}
@@ -0,0 +1,76 @@
+import { ensureSomething } from './ensure';
+import { searchSomething } from './search';
+import { API } from './types';
+import { host } from '../login/users';
+import { requestHeaders } from './apiauth';
+import { Context } from 'support/commands';
+
+export function ensureOrgExists(ctx: Context, name: string) {
+  return ensureSomething(
+    ctx.api,
+    () =>
+      searchSomething(
+        ctx.api,
+        encodeURI(`${ctx.api.mgmtBaseURL}/global/orgs/_by_domain?domain=${name}.${host(Cypress.config('baseUrl'))}`),
+        'GET',
+        (res) => {
+          return { entity: res.org, id: res.org?.id, sequence: parseInt(<string>res.org?.details?.sequence) };
+        },
+      ),
+    () => `${ctx.api.mgmtBaseURL}/orgs`,
+    'POST',
+    { name: name },
+    (org) => org?.name === name,
+    (res) => res.id,
+  );
+}
+
+export function isDefaultOrg(ctx: Context, orgId: string): Cypress.Chainable<boolean> {
+  return cy
+    .request({
+      method: 'GET',
+      url: encodeURI(`${ctx.api.mgmtBaseURL}/iam`),
+      headers: requestHeaders(ctx.api, orgId),
+    })
+    .then((res) => {
+      const { defaultOrgId } = res.body;
+      expect(defaultOrgId).to.equal(orgId);
+      return defaultOrgId === orgId;
+    });
+}
+
+export function ensureOrgIsDefault(ctx: Context, orgId: string): Cypress.Chainable<boolean> {
+  return cy
+    .request({
+      method: 'GET',
+      url: encodeURI(`${ctx.api.mgmtBaseURL}/iam`),
+      headers: requestHeaders(ctx.api, orgId),
+    })
+    .then((res) => {
+      return res.body;
+    })
+    .then(({ defaultOrgId }) => {
+      if (defaultOrgId === orgId) {
+        return true;
+      } else {
+        return cy
+          .request({
+            method: 'PUT',
+            url: `${ctx.api.adminBaseURL}/orgs/default/${orgId}`,
+            headers: requestHeaders(ctx.api, orgId),
+            failOnStatusCode: true,
+            followRedirect: false,
+          })
+          .then((cRes) => {
+            expect(cRes.status).to.equal(200);
+            return !!cRes.body;
+          });
+      }
+    });
+}
+
+export function getOrgUnderTest(ctx: Context): Cypress.Chainable<number> {
+  return searchSomething(ctx.api, `${ctx.api.mgmtBaseURL}/orgs/me`, 'GET', (res) => {
+    return { entity: res.org, id: res.org.id, sequence: parseInt(<string>res.org.details.sequence) };
+  }).then((res) => res.entity.id);
+}
@@ -0,0 +1,53 @@
+import { requestHeaders } from './apiauth';
+import { API } from './types';
+import { ensureSetting } from './ensure';
+
+export enum Policy {
+  Label = 'label',
+}
+
+export function resetPolicy(api: API, policy: Policy) {
+  cy.request({
+    method: 'DELETE',
+    url: `${api.mgmtBaseURL}/policies/${policy}`,
+    headers: requestHeaders(api),
+  }).then((res) => {
+    expect(res.status).to.equal(200);
+    return null;
+  });
+}
+
+export function ensureDomainPolicy(
+  api: API,
+  userLoginMustBeDomain: boolean,
+  validateOrgDomains: boolean,
+  smtpSenderAddressMatchesInstanceDomain: boolean,
+) {
+  return ensureSetting(
+    api,
+    `${api.adminBaseURL}/policies/domain`,
+    (body: any) => {
+      const result = {
+        sequence: parseInt(<string>body.policy?.details?.sequence),
+        id: body.policy?.details?.resourceOwner,
+        entity: null,
+      };
+      if (
+        body.policy &&
+        (body.policy.userLoginMustBeDomain ? body.policy.userLoginMustBeDomain : false) == userLoginMustBeDomain &&
+        (body.policy.validateOrgDomains ? body.policy.validateOrgDomains : false) == validateOrgDomains &&
+        (body.policy.smtpSenderAddressMatchesInstanceDomain ? body.policy.smtpSenderAddressMatchesInstanceDomain : false) ==
+          smtpSenderAddressMatchesInstanceDomain
+      ) {
+        return { ...result, entity: body.policy };
+      }
+      return result;
+    },
+    `${api.adminBaseURL}/policies/domain`,
+    {
+      userLoginMustBeDomain: userLoginMustBeDomain,
+      validateOrgDomains: validateOrgDomains,
+      smtpSenderAddressMatchesInstanceDomain: smtpSenderAddressMatchesInstanceDomain,
+    },
+  );
+}
@@ -0,0 +1,66 @@
+import { ensureItemDoesntExist, ensureItemExists } from './ensure';
+import { API, Entity } from './types';
+
+export function ensureProjectExists(api: API, projectName: string, orgId?: string) {
+  return ensureItemExists(
+    api,
+    `${api.mgmtBaseURL}/projects/_search`,
+    (project: any) => project.name === projectName,
+    `${api.mgmtBaseURL}/projects`,
+    { name: projectName },
+    orgId,
+  );
+}
+
+export function ensureProjectDoesntExist(api: API, projectName: string, orgId?: string) {
+  return ensureItemDoesntExist(
+    api,
+    `${api.mgmtBaseURL}/projects/_search`,
+    (project: any) => project.name === projectName,
+    (project) => `${api.mgmtBaseURL}/projects/${project.id}`,
+    orgId,
+  );
+}
+
+class ResourceType {
+  constructor(
+    public resourcePath: string,
+    public compareProperty: string,
+    public identifierProperty: string,
+  ) {}
+}
+
+export const Apps = new ResourceType('apps', 'name', 'id');
+export const Roles = new ResourceType('roles', 'key', 'key');
+//export const Grants = new ResourceType('apps', 'name')
+
+export function ensureProjectResourceDoesntExist(
+  api: API,
+  projectId: string,
+  resourceType: ResourceType,
+  resourceName: string,
+  orgId?: string,
+): Cypress.Chainable<null> {
+  return ensureItemDoesntExist(
+    api,
+    `${api.mgmtBaseURL}/projects/${projectId}/${resourceType.resourcePath}/_search`,
+    (resource: Entity) => resource[resourceType.compareProperty] === resourceName,
+    (resource: Entity) =>
+      `${api.mgmtBaseURL}/projects/${projectId}/${resourceType.resourcePath}/${resource[resourceType.identifierProperty]}`,
+    orgId,
+  );
+}
+
+export function ensureRoleExists(api: API, projectId: number, roleName: string) {
+  return ensureItemExists(
+    api,
+    `${api.mgmtBaseURL}/projects/${projectId}/${Roles.resourcePath}/_search`,
+    (resource: any) => resource.key === roleName,
+    `${api.mgmtBaseURL}/projects/${projectId}/${Roles.resourcePath}`,
+    {
+      name: roleName,
+      roleKey: roleName,
+      displayName: roleName,
+    },
+  );
+}
@@ -0,0 +1,84 @@
+import { Context } from 'support/commands';
+
+export enum Unit {
+  Unimplemented,
+  AuthenticatedRequests,
+  ExecutionSeconds,
+}
+
+interface notification {
+  percent: number;
+  repeat?: boolean;
+  callUrl: string;
+}
+
+export function addQuota(
+  ctx: Context,
+  unit: Unit = Unit.AuthenticatedRequests,
+  limit: boolean,
+  amount: number,
+  notifications?: Array<notification>,
+  from: Date = (() => {
+    const date = new Date();
+    date.setMonth(0, 1);
+    date.setMinutes(0, 0, 0);
+    // default to start of current year
+    return date;
+  })(),
+  intervalSeconds: string = `${315_576_000_000}s`, // proto max duration is 1000 years
+  failOnStatusCode = true,
+): Cypress.Chainable<Cypress.Response<any>> {
+  return cy.request({
+    method: 'POST',
+    url: `${ctx.system.baseURL}/instances/${ctx.instanceId}/quotas`,
+    auth: {
+      bearer: ctx.system.token,
+    },
+    body: {
+      unit: unit,
+      amount: amount,
+      resetInterval: intervalSeconds,
+      limit: limit,
+      from: from,
+      notifications: notifications,
+    },
+    failOnStatusCode: failOnStatusCode,
+  });
+}
+
+export function ensureQuotaIsAdded(
+  ctx: Context,
+  unit: Unit,
+  limit: boolean,
+  amount?: number,
+  notifications?: Array<notification>,
+  from?: Date,
+  intervalSeconds?: string,
+): Cypress.Chainable<null> {
+  return addQuota(ctx, unit, limit, amount, notifications, from, intervalSeconds, false).then((res) => {
+    if (!res.isOkStatusCode) {
+      expect(res.status).to.equal(409);
+    }
+    return null;
+  });
+}
+
+export function removeQuota(ctx: Context, unit: Unit, failOnStatusCode = true): Cypress.Chainable<Cypress.Response<any>> {
+  return cy.request({
+    method: 'DELETE',
+    url: `${ctx.system.baseURL}/instances/${ctx.instanceId}/quotas/${unit}`,
+    auth: {
+      bearer: ctx.system.token,
+    },
+    failOnStatusCode: failOnStatusCode,
+  });
+}
+
+export function ensureQuotaIsRemoved(ctx: Context, unit?: Unit): Cypress.Chainable<null> {
+  return removeQuota(ctx, unit, false).then((res) => {
+    if (!res.isOkStatusCode) {
+      expect(res.status).to.equal(404);
+    }
+    return null;
+  });
+}
@@ -0,0 +1,32 @@
+import { requestHeaders } from './apiauth';
+import { API, Entity, SearchResult, Token } from './types';
+
+export function searchSomething(
+  token: Token,
+  searchPath: string,
+  method: string,
+  mapResult: (body: any) => SearchResult,
+  orgId?: string,
+): Cypress.Chainable<SearchResult> {
+  return cy
+    .request({
+      method: method,
+      url: searchPath,
+      headers: requestHeaders(token, orgId),
+      failOnStatusCode: method == 'POST',
+    })
+    .then((res) => {
+      return mapResult(res.body);
+    });
+}
+
+export function findFromList(find: (entity: Entity) => boolean, idField: string = 'id'): (body: any) => SearchResult {
+  return (b) => {
+    const entity = b.result?.find(find);
+    return {
+      entity: entity,
+      sequence: parseInt(<string>b.details.processedSequence),
+      id: entity?.[idField],
+    };
+  };
+}
@@ -0,0 +1,28 @@
+import { ensureItemDoesntExist, ensureItemExists } from './ensure';
+import { API, Entity } from './types';
+import { ensureSMTPProviderExists } from './smtp';
+
+export function ensureSMSProviderExists(api: API) {
+  // remove and create
+  ensureSMSProviderDoesntExist(api);
+  return ensureItemExists(
+    api,
+    `${api.adminBaseURL}/sms/_search`,
+    ({ twilio: { sid: foundSid } }: any) => foundSid === 'initial-sid',
+    `${api.adminBaseURL}/sms/twilio`,
+    {
+      sid: 'initial-sid',
+      senderNumber: 'initial-senderNumber',
+      token: 'initial-token',
+    },
+  );
+}
+
+export function ensureSMSProviderDoesntExist(api: API) {
+  return ensureItemDoesntExist(
+    api,
+    `${api.adminBaseURL}/sms/_search`,
+    (provider: any) => !!provider,
+    (provider) => `${api.adminBaseURL}/sms/${provider.id}`,
+  );
+}
@@ -0,0 +1,32 @@
+import { ensureItemDoesntExist, ensureItemExists } from './ensure';
+import { API, Entity } from './types';
+
+export function ensureSMTPProviderExists(api: API, providerDescription: string) {
+  return ensureItemExists(
+    api,
+    `${api.adminBaseURL}/smtp/_search`,
+    (provider: any) => {
+      return provider.description === providerDescription;
+    },
+    `${api.adminBaseURL}/smtp`,
+    {
+      name: providerDescription,
+      description: providerDescription,
+      senderAddress: '[email protected]',
+      senderName: 'A Sender',
+      host: 'smtp.host.com:587',
+      user: 'smtpuser',
+    },
+  );
+}
+
+export function activateSMTPProvider(api: API, providerId: string) {
+  return cy.request({
+    method: 'POST',
+    url: `${api.adminBaseURL}/smtp/${providerId}/_activate`,
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${api.token}`,
+    },
+  });
+}
@@ -0,0 +1,27 @@
+export interface Token {
+  token: string;
+}
+
+export interface API extends Token {
+  mgmtBaseURL: string;
+  adminBaseURL: string;
+  authBaseURL: string;
+  assetsBaseURL: string;
+  oidcBaseURL: string;
+  oauthBaseURL: string;
+  samlBaseURL: string;
+  featuresBaseURL: string;
+}
+
+export interface SystemAPI extends Token {
+  baseURL: string;
+}
+
+export type SearchResult = {
+  entity: Entity | null;
+  sequence: number;
+  id: string;
+};
+
+// Entity is an object but not a function
+export type Entity = { [k: string]: any } & ({ bind?: never } | { call?: never });
@@ -0,0 +1,71 @@
+import { requestHeaders } from './apiauth';
+import { ensureItemDoesntExist, ensureItemExists } from './ensure';
+import { API } from './types';
+
+export function ensureHumanUserExists(api: API, username: string) {
+  return ensureItemExists(
+    api,
+    `${api.mgmtBaseURL}/users/_search`,
+    (user: any) => user.userName === username,
+    `${api.mgmtBaseURL}/users/human`,
+    {
+      ...defaultHuman,
+      user_name: username,
+    },
+    undefined,
+    'userId',
+  );
+}
+
+export function ensureMachineUserExists(api: API, username: string) {
+  return ensureItemExists(
+    api,
+    `${api.mgmtBaseURL}/users/_search`,
+    (user: any) => user.userName === username,
+    `${api.mgmtBaseURL}/users/machine`,
+    {
+      user_name: username,
+      name: 'e2emachinename',
+      description: 'e2emachinedescription',
+    },
+    undefined,
+    'userId',
+  );
+}
+
+export function ensureUserDoesntExist(api: API, username: string) {
+  return ensureItemDoesntExist(
+    api,
+    `${api.mgmtBaseURL}/users/_search`,
+    (user: any) => user.userName === username,
+    (user) => `${api.mgmtBaseURL}/users/${user.id}`,
+  );
+}
+
+export function createHumanUser(api: API, username: string, failOnStatusCode = true) {
+  return cy.request({
+    method: 'POST',
+    url: `${api.mgmtBaseURL}/users/human`,
+    body: {
+      ...defaultHuman,
+      user_name: username,
+    },
+    auth: {
+      bearer: api.token,
+    },
+    failOnStatusCode: failOnStatusCode,
+  });
+}
+
+const defaultHuman = {
+  profile: {
+    first_name: 'e2efirstName',
+    last_name: 'e2elastName',
+  },
+  email: {
+    email: '[email protected]',
+  },
+  phone: {
+    phone: '+41 123456789',
+  },
+};