createTestCanister

createTestCanister<A>(idlFactory, handlers): FakeCanister

Defined in: core/src/testing/test-canister.ts:101

Builds a canister for installFakeReplica from the service’s Candid interface and a handler per method, typed from the service. The fake replica decodes each call’s arguments with the interface, runs the method’s handler and encodes its result, so the reactor under test encodes, decodes, caches and unwraps exactly as it does against a replica.

A query call to a method the interface does not mark query or composite_query is rejected, as a replica rejects it. A method with no handler rejects every call to it, and a handler for a method the service does not have throws here.

Return { Err: ... } from a method that returns a Result to test the CanisterError a reactor throws for it, and throw from a handler to test the CallError a trap produces.

Type Parameters

A

A = BaseActor

The service type, such as the _SERVICE generated with the idlFactory. It types each handler’s arguments and result.

Parameters

idlFactory

(IDL) => any

The service’s Candid interface, as a reactor takes it.

handlers

TestCanisterHandlers<A>

The methods the test canister answers.

Returns

FakeCanister

A canister to install under its ID in installFakeReplica.

Example

import { createTestCanister, installFakeReplica } from "@ic-reactor/core/testing"
import { idlFactory, type _SERVICE } from "./declarations/backend"

const balances = new Map<string, bigint>()

const replica = installFakeReplica({
  canisters: {
    "bkyz2-fmaaa-aaaaa-qaaaq-cai": createTestCanister<_SERVICE>(idlFactory, {
      // The caller is the principal the agent signed the call as.
      balance: (_args, { caller }) => balances.get(caller.toText()) ?? 0n,
      deposit: ([amount], { caller }) => {
        if (amount === 0n) return { Err: { InvalidAmount: null } }
        const next = (balances.get(caller.toText()) ?? 0n) + amount
        balances.set(caller.toText(), next)
        return { Ok: next }
      },
    }),
  },
})