core testing

The helpers this package ships for your tests, by the path you import them from. How the test layers fit together is in the testing guide.

@evolve-framework/core/testing

Helpers for running a module's GraphQL schema in tests.

assertSingleValueAsserts an execution result is one value, and throws on a stream.

import { assertSingleValue } from "@evolve-framework/core/testing";

function assertSingleValue<TValue>(
  value: TValue | AsyncIterable<TValue>,
): asserts value is TValue

Returns asserts value is TValue

createGraphQLTestInstanceA Yoga instance for tests: the schema, context and error masking of createGraphQLInstance, without its persisted queries and tracing.

import { createGraphQLTestInstance } from "@evolve-framework/core/testing";

function createGraphQLTestInstance<TServerContext, TUserContext>(
  options: Options<TServerContext, TUserContext>,
): GraphQLInstance<TServerContext, TUserContext>

Option	Type	Description
typeDefs	DocumentNode
resolvers	IResolvers
extraPlugins	({} | Plugin | Plugin<TUserContext & TServerContext & YogaInitialContext>)[] | undefined
context	(context: TServerContext & YogaInitialContext) => TUserContext | Promise<TUserContext>

Returns GraphQLInstance<TServerContext, TUserContext>

@evolve-framework/core/test-support

A service for end-to-end suites that simulates back-office changes and removes test data, guarded to test environments.

TestSupportRefusalAn action refused for a reason the caller can act on: the resource is not test data, or it is not in a state the action applies to.

import { TestSupportRefusal } from "@evolve-framework/core/test-support";

Extends Error

new TestSupportRefusal(message?: string)

assertTestIdentityThrows unless both parts of the rule are present and usable.

import { assertTestIdentity } from "@evolve-framework/core/test-support";

function assertTestIdentity(identity: TestIdentity | undefined): void

Option	Type	Description
domain	string	The reserved domain, e.g. test.example.com.
prefix	string	What every generated local part starts with, e.g. e2e-.

Returns void

createTestSupportModuleThe test-support service's module, for createApplication beside a HealthModule with graphql: false.

import { createTestSupportModule } from "@evolve-framework/core/test-support";

function createTestSupportModule(
  options: TestSupportModuleOptions,
): AbstractModule

Option	Type	Description
simulate	SimulateHandlers	An engine's implementation of every simulation action.
cleanup	CleanupHandlers	An engine's implementation of every cleanup action.
secret	string | undefined	Every request must present authorization: Bearer <secret>. Unset, no request can match, so the routes are closed rather than open.
testIdentity	TestIdentity | undefined	Required: the service refuses to start without it.
overrides?	Partial<SimulateHandlers>	A project's own implementation of single simulation actions, for an integration that writes a shape of its own. The rest keep the default.

Returns AbstractModule

isSimulationEnabledWhether this environment opted in to back-office simulation and test-data cleanup.

import { isSimulationEnabled } from "@evolve-framework/core/test-support";

function isSimulationEnabled(): boolean

Returns boolean

isTestIdentityWhether an email address is a generated test identity.

import { isTestIdentity } from "@evolve-framework/core/test-support";

function isTestIdentity(
  identity: TestIdentity,
  email: string | undefined,
): boolean

Option	Type	Description
domain	string	The reserved domain, e.g. test.example.com.
prefix	string	What every generated local part starts with, e.g. e2e-.

Returns boolean

testIdentityFromEnvironmentThe environment's test identity, or undefined where it names no domain.

import { testIdentityFromEnvironment } from "@evolve-framework/core/test-support";

function testIdentityFromEnvironment(): TestIdentity | undefined

Returns TestIdentity | undefined

testSupportPathThe route an action is served on, e.g.

import { testSupportPath } from "@evolve-framework/core/test-support";

function testSupportPath(
  surface: "cleanup" | "simulate",
  action: string,
): string

Returns string

SIMULATION_ENABLED_ENVThe variable an environment sets to be written to as a test environment.

import { SIMULATION_ENABLED_ENV } from "@evolve-framework/core/test-support";

const SIMULATION_ENABLED_ENV: "SIMULATION_ENABLED"

TEST_IDENTITY_DOMAIN_ENVThe variable an environment names its test identity's domain with.

import { TEST_IDENTITY_DOMAIN_ENV } from "@evolve-framework/core/test-support";

const TEST_IDENTITY_DOMAIN_ENV: "TEST_IDENTITY_DOMAIN"

TEST_IDENTITY_PREFIX_ENVThe variable an environment names its test identity's prefix with.

import { TEST_IDENTITY_PREFIX_ENV } from "@evolve-framework/core/test-support";

const TEST_IDENTITY_PREFIX_ENV: "TEST_IDENTITY_PREFIX"

testSupportContractEvery simulation and cleanup action, with its request and response schema.

import { testSupportContract } from "@evolve-framework/core/test-support";

const testSupportContract: { simulate: { "invoice/raise": { request: ZodObject<{ amount: ZodObject<{ centAmount: ZodNumber; currencyCode: ZodString; }, $strip>; invoiceNumber: ZodOptional…

CleanupAction

import { type CleanupAction } from "@evolve-framework/core/test-support";

export type CleanupAction = keyof typeof cleanupContract;

CleanupHandlersAn implementation of every cleanup action.

import { type CleanupHandlers } from "@evolve-framework/core/test-support";

export type CleanupHandlers = Handlers<"cleanup">;

SimulateAction

import { type SimulateAction } from "@evolve-framework/core/test-support";

export type SimulateAction = keyof typeof simulateContract;

SimulateHandlersAn implementation of every simulation action.

import { type SimulateHandlers } from "@evolve-framework/core/test-support";

export type SimulateHandlers = Handlers<"simulate">;

TestIdentityA generated test identity: an address at a reserved domain whose local part starts with a known prefix.

import { type TestIdentity } from "@evolve-framework/core/test-support";

export type TestIdentity = {
  domain: string;
  prefix: string;
};

TestSupportContextWhat every action is handed beside its request.

import { type TestSupportContext } from "@evolve-framework/core/test-support";

export type TestSupportContext = {
  testIdentity: TestIdentity;
};

TestSupportContract

import { type TestSupportContract } from "@evolve-framework/core/test-support";

export type TestSupportContract = typeof testSupportContract;

TestSupportRequestWhat an action takes, by surface and action name.

import { type TestSupportRequest } from "@evolve-framework/core/test-support";

export type TestSupportRequest<S extends keyof TestSupportContract, A extends keyof TestSupportContract[S]> = TestSupportContract[S][A] extends {
  request: infer Req extends z.ZodType;
} ? z.infer<Req> : never;

TestSupportResponseWhat an action answers, by surface and action name.

import { type TestSupportResponse } from "@evolve-framework/core/test-support";

export type TestSupportResponse<S extends keyof TestSupportContract, A extends keyof TestSupportContract[S]> = TestSupportContract[S][A] extends {
  response: infer Res extends z.ZodType;
} ? z.infer<Res> : never;

@evolve-framework/core/test-support/contract

The request and response schemas of that service, for a test client that needs only the types.

testSupportPathThe route an action is served on, e.g.

import { testSupportPath } from "@evolve-framework/core/test-support/contract";

function testSupportPath(
  surface: "cleanup" | "simulate",
  action: string,
): string

Returns string

testSupportContractEvery simulation and cleanup action, with its request and response schema.

import { testSupportContract } from "@evolve-framework/core/test-support/contract";

const testSupportContract: { simulate: { "invoice/raise": { request: ZodObject<{ amount: ZodObject<{ centAmount: ZodNumber; currencyCode: ZodString; }, $strip>; invoiceNumber: ZodOptional…

CleanupAction

import { type CleanupAction } from "@evolve-framework/core/test-support/contract";

export type CleanupAction = keyof typeof cleanupContract;

SimulateAction

import { type SimulateAction } from "@evolve-framework/core/test-support/contract";

export type SimulateAction = keyof typeof simulateContract;

TestSupportContract

import { type TestSupportContract } from "@evolve-framework/core/test-support/contract";

export type TestSupportContract = typeof testSupportContract;

TestSupportRequestWhat an action takes, by surface and action name.

import { type TestSupportRequest } from "@evolve-framework/core/test-support/contract";

export type TestSupportRequest<S extends keyof TestSupportContract, A extends keyof TestSupportContract[S]> = TestSupportContract[S][A] extends {
  request: infer Req extends z.ZodType;
} ? z.infer<Req> : never;

TestSupportResponseWhat an action answers, by surface and action name.

import { type TestSupportResponse } from "@evolve-framework/core/test-support/contract";

export type TestSupportResponse<S extends keyof TestSupportContract, A extends keyof TestSupportContract[S]> = TestSupportContract[S][A] extends {
  response: infer Res extends z.ZodType;
} ? z.infer<Res> : never;