Skip to main content

@eigeninteractive/server/testing

@eigeninteractive/server/testing: the test-auth recipe, for the engine's own suite and for implementor test workers alike:

// test/worker.ts, your production entry with explicit Firebase fakes:
export default createEngine({
  ...sameConfig,
  testing: {
    auth: testVerifier(),
    firebaseAdmin: () => testFirebaseAdmin,
  },
});
// a spec:
import { exports } from "cloudflare:workers";
await exports.default.fetch(url, { headers: await testBearer({ uid: "alice" }) });

(exports.default is the loopback binding to the test worker's default export, the supported replacement for the deprecated SELF fetcher. It needs Cloudflare.GlobalProps to declare mainModule; see the engine's own test/env.d.ts for the hand-rolled version, or use wrangler types.)

Tokens are verified through the SAME jose code path production uses; only the JWKS is local. The RS256 keypair below is a public fixture (checked in, shipped in the package); it protects nothing and must never reach a production config: pass testing ONLY in test workers.

Interfaces​

FakeCommerceEvidence​

Defined in: server/packages/server/src/testing.ts:117

Properties​

accountId​
accountId: string;

Defined in: server/packages/server/src/testing.ts:120

kind?​
kind?: "oneTime" | "subscription";

Defined in: server/packages/server/src/testing.ts:125

providerReference​
providerReference: string;

Defined in: server/packages/server/src/testing.ts:119

purchasedAt?​
purchasedAt?: number;

Defined in: server/packages/server/src/testing.ts:122

refusal?​
refusal?: string;

Defined in: server/packages/server/src/testing.ts:131

Answer as a provider that read the purchase and will never accept it.

replaces?​
replaces?: string;

Defined in: server/packages/server/src/testing.ts:129

The transaction this one replaced, as Play's linkedPurchaseToken.

requiresAcknowledgement?​
requiresAcknowledgement?: boolean;

Defined in: server/packages/server/src/testing.ts:126

sealedProviderState?​
sealedProviderState?: string;

Defined in: server/packages/server/src/testing.ts:127

state?​
state?: CommerceTransactionState;

Defined in: server/packages/server/src/testing.ts:121

transactionId​
transactionId: string;

Defined in: server/packages/server/src/testing.ts:118

validFrom?​
validFrom?: number;

Defined in: server/packages/server/src/testing.ts:123

validUntil?​
validUntil?: number;

Defined in: server/packages/server/src/testing.ts:124

FakeCommerceProvider​

Defined in: server/packages/server/src/testing.ts:141

A fake provider with the controls a lifecycle test needs.

Reconciliation and acknowledgement are the two places where the engine depends on a provider doing something later, so a fake that cannot fail, stall, or refuse to answer cannot prove either of them works.

Extends​

Properties​

acknowledged​
readonly acknowledged: string[];

Defined in: server/packages/server/src/testing.ts:146

Every transaction this provider was asked to acknowledge, in order.

checkouts​
readonly checkouts: {
  accountId: string;
  operationId: string;
  providerReference: string;
  url: string;
}[];

Defined in: server/packages/server/src/testing.ts:156

One entry per checkout session the provider actually opened. A replayed operation identity must not add one.

accountId​
accountId: string;
operationId​
operationId: string;
providerReference​
providerReference: string;
url​
url: string;
key​
readonly key: string;

Defined in: server/packages/server/src/commerce/types.ts:172

Inherited from​

CommerceProvider.key

sweeps​
readonly sweeps: string[][];

Defined in: server/packages/server/src/testing.ts:148

Each sweep's requested ids, in order. Proves queue rotation.

transactions​
readonly transactions: Map<string, Partial<VerifiedCommerceTransaction>>;

Defined in: server/packages/server/src/testing.ts:144

Current provider truth per transaction, returned by the next sweep. A transaction absent from here is one the provider will not answer for.

Methods​

acknowledge()?​
acknowledge?(env, transaction): Promise<void>;

Defined in: server/packages/server/src/commerce/types.ts:190

Runs only after the normalized transaction and grants commit.

Parameters​
ParameterType
envunknown
transactionCommerceTransactionReference
Returns​

Promise<void>

Inherited from​

CommerceProvider.acknowledge

clearFailures()​
clearFailures(): void;

Defined in: server/packages/server/src/testing.ts:153

Returns​

void

createCheckout()?​
createCheckout?(env, input): Promise<CommerceCheckout>;

Defined in: server/packages/server/src/commerce/types.ts:191

Parameters​
ParameterType
envunknown
inputCreateCheckoutInput
Returns​

Promise<CommerceCheckout>

Inherited from​

CommerceProvider.createCheckout

failAcknowledgement()​
failAcknowledgement(message?): void;

Defined in: server/packages/server/src/testing.ts:152

Make every acknowledge throw until cleared.

Parameters​
ParameterType
message?string
Returns​

void

failNextSweep()​
failNextSweep(message?): void;

Defined in: server/packages/server/src/testing.ts:150

Make the whole next reconcile call throw, as a provider outage does.

Parameters​
ParameterType
message?string
Returns​

void

management()?​
management?(
   env,
   accountId,
   providerAccountId,
   returnUrl
): Promise<CommerceManagement>;

Defined in: server/packages/server/src/commerce/types.ts:192

Parameters​
ParameterType
envunknown
accountIdstring
providerAccountIdstring
returnUrlstring
Returns​

Promise<CommerceManagement>

Inherited from​

CommerceProvider.management

products()?​
products?(env, providerReferences): Promise<readonly CommerceProduct[]>;

Defined in: server/packages/server/src/commerce/types.ts:179

Parameters​
ParameterType
envunknown
providerReferencesreadonly string[]
Returns​

Promise<readonly CommerceProduct[]>

Inherited from​

CommerceProvider.products

reconcile()?​
reconcile?(env, transactions): Promise<readonly VerifiedCommerceTransaction[]>;

Defined in: server/packages/server/src/commerce/types.ts:188

Fetches current state for locally active or pending transaction refs.

Parameters​
ParameterType
envunknown
transactionsreadonly CommerceTransactionReference[]
Returns​

Promise<readonly VerifiedCommerceTransaction[]>

Inherited from​

CommerceProvider.reconcile

reportProviderAccount()​
reportProviderAccount(providerAccountId): void;

Defined in: server/packages/server/src/testing.ts:159

Report this provider customer on the next checkout instead of the account's usual one, as a provider confusing two customers would.

Parameters​
ParameterType
providerAccountIdstring
Returns​

void

validateReference()?​
validateReference?(providerReference, kind): void;

Defined in: server/packages/server/src/commerce/types.ts:178

Throws when a catalog reference cannot name anything this provider sells as an offer of kind. Called for every offer at createEngine, so a misspelt reference is a deploy failure rather than a refused purchase.

Parameters​
ParameterType
providerReferencestring
kind"oneTime" | "subscription"
Returns​

void

Inherited from​

CommerceProvider.validateReference

verifyClaim()​
verifyClaim(env, input): Promise<VerifiedCommerceTransaction>;

Defined in: server/packages/server/src/commerce/types.ts:180

Parameters​
ParameterType
envunknown
inputVerifyClaimInput
Returns​

Promise<VerifiedCommerceTransaction>

Inherited from​

CommerceProvider.verifyClaim

verifyWebhook()?​
verifyWebhook?(env, request): Promise<
  | VerifiedCommerceEvent
| null>;

Defined in: server/packages/server/src/commerce/types.ts:186

Verifies the raw request and fetches current provider state when needed. Resolves null for an authentic notification that concerns no purchase, such as a console test message, so the provider is answered and stops resending.

Parameters​
ParameterType
envunknown
requestRequest
Returns​

Promise< | VerifiedCommerceEvent | null>

Inherited from​

CommerceProvider.verifyWebhook

TestTokenOptions​

Defined in: server/packages/server/src/testing.ts:74

Properties​

anonymous?​
anonymous?: boolean;

Defined in: server/packages/server/src/testing.ts:76

claims?​
claims?: Record<string, unknown>;

Defined in: server/packages/server/src/testing.ts:81

Override any registered claim (e.g. an expired exp, a wrong aud).

email?​
email?: string;

Defined in: server/packages/server/src/testing.ts:77

name?​
name?: string;

Defined in: server/packages/server/src/testing.ts:78

picture?​
picture?: string;

Defined in: server/packages/server/src/testing.ts:79

uid​
uid: string;

Defined in: server/packages/server/src/testing.ts:75

Variables​

TEST_PROJECT_ID​

const TEST_PROJECT_ID: "eigen-test" = "eigen-test";

Defined in: server/packages/server/src/testing.ts:40

testFirebaseAdmin​

const testFirebaseAdmin: FirebaseAdminEffects;

Defined in: server/packages/server/src/testing.ts:64

No-op Firebase Admin effects for test workers and test Durable Objects.

Functions​

fakeCommerceProvider()​

function fakeCommerceProvider(
   products,
   now?,
   key?
): FakeCommerceProvider;

Defined in: server/packages/server/src/testing.ts:163

Deterministic provider for commerce lifecycle and implementor conformance tests.

Parameters​

ParameterTypeDefault valueDescription
productsreadonly (CommerceProduct & { kind?: "oneTime" | "subscription"; })[]undefined-
now?() => numberDate.now-
key?string"fake"The provider key. Give a sweep test its own, so the reconciliation queue it reasons about holds only the rows that test seeded.

Returns​

FakeCommerceProvider

mintTestToken()​

function mintTestToken(opts): Promise<string>;

Defined in: server/packages/server/src/testing.ts:84

Parameters​

ParameterType
optsTestTokenOptions

Returns​

Promise<string>

testAccount()​

function testAccount(
   d1,
   userId,
   now?
): Promise<string>;

Defined in: server/packages/server/src/testing.ts:304

Provision the account a commerce test is about.

The ledger refuses to write for an account that does not exist, because a provider notification names an account from its own metadata and that metadata outlives an erasure. Anything reaching the ledger through the API has already been provisioned by the auth middleware; a test calling the ledger directly has to say so itself.

Parameters​

ParameterType
d1D1Database
userIdstring
now?number

Returns​

Promise<string>

testBearer()​

function testBearer(opts): Promise<Record<string, string>>;

Defined in: server/packages/server/src/testing.ts:103

Authorization header for a minted token.

Parameters​

ParameterType
optsTestTokenOptions

Returns​

Promise<Record<string, string>>

testMutationHeaders()​

function testMutationHeaders(opts): Promise<Record<string, string>>;

Defined in: server/packages/server/src/testing.ts:110

Headers for an authenticated JSON mutation.

Parameters​

ParameterType
optsTestTokenOptions

Returns​

Promise<Record<string, string>>

testVerifier()​

function testVerifier(): TokenVerifier;

Defined in: server/packages/server/src/testing.ts:70

The verifier a test worker passes under createEngine({ testing }).

Returns​

TokenVerifier

withCreationId()​

function withCreationId(
   method,
   path,
   body
): unknown;

Defined in: server/packages/server/src/testing.ts:321

Parameters​

ParameterType
methodstring
pathstring
bodyunknown

Returns​

unknown