PocketIc

Defined in: packages/pic/src/pocket-ic.ts:139

This class represents the main PocketIC client. It is responsible for interacting with the PocketIC server via the REST API. See PocketIcServer for details on the server to use with this client.

Example

The easist way to use PocketIC is to use setupCanister convenience method:

import { PocketIc, PocketIcServer } from '@dfinity/pic';
import { _SERVICE, idlFactory } from '../declarations';

const wasmPath = resolve('..', '..', 'canister.wasm');

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const fixture = await pic.setupCanister<_SERVICE>({ idlFactory, wasmPath });
const { actor } = fixture;

// perform tests...

await pic.tearDown();
await picServer.stop();

If more control is needed, then the createCanister, installCode and createActor methods can be used directly:

import { PocketIc, PocketIcServer } from '@dfinity/pic';
import { _SERVICE, idlFactory } from '../declarations';

const wasm = resolve('..', '..', 'canister.wasm');

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const canisterId = await pic.createCanister();
await pic.installCode({ canisterId, wasm });
const actor = pic.createActor<_SERVICE>({ idlFactory, canisterId });

// perform tests...

await pic.tearDown();
await picServer.stop();

Methods

addCycles()

addCycles(canisterId, amount): Promise<bigint>

Defined in: packages/pic/src/pocket-ic.ts:1870

Add cycles to the specified canister.

Parameters

canisterId

Principal

The Principal of the canister to add cycles to.

amount

bigint

The amount of cycles to add.

Returns

Promise<bigint>

The new cycle balance of the canister.

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const newCyclesBalance = await pic.addCycles(canisterId, BigInt(10_000_000));

await pic.tearDown();
await picServer.stop();

advanceCertifiedTime()

advanceCertifiedTime(duration): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:1560

Advance the time of the IC by the given duration in milliseconds and immediately have query calls and read state requests reflect the new time.

Use advanceTime to advance time without immediately reflecting the new time.

Parameters

duration

number

The duration to advance the time by.

Returns

Promise<void>

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const initialTime = await pic.getTime();
await pic.advanceCertifiedTime(1_000);

const newTime = await pic.getTime();

await pic.tearDown();
await picServer.stop();

advanceTime()

advanceTime(duration): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:1529

Advance the time of the IC by the given duration in milliseconds. tick should be called after calling this method in order for query calls and read state requests to reflect the new time.

Use advanceCertifiedTime to advance time and immediately have query calls and read state requests reflect the new time.

Parameters

duration

number

The duration to advance the time by.

Returns

Promise<void>

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const initialTime = await pic.getTime();
await pic.advanceTime(1_000);
await pic.tick();

const newTime = await pic.getTime();

await pic.tearDown();
await picServer.stop();

awaitCall()

awaitCall(call): Promise<Uint8Array<ArrayBufferLike>>

Defined in: packages/pic/src/pocket-ic.ts:1251

Executes rounds until the given call has finished, see submitCall.

Parameters

call

SubmittedCall

The submitted call, see SubmittedCall.

Returns

Promise<Uint8Array<ArrayBufferLike>>

The Candid-encoded response of the update call. Throws if the call was rejected.

canisterExists()

canisterExists(canisterId): Promise<boolean>

Defined in: packages/pic/src/pocket-ic.ts:1655

Checks whether the given canister exists.

Parameters

canisterId

Principal

The Principal of the canister to check.

Returns

Promise<boolean>

true if the canister exists, false otherwise.

See

Principal

canisterStatus()

canisterStatus(options): Promise<CanisterStatusResult>

Defined in: packages/pic/src/pocket-ic.ts:714

Returns the status of the given canister.

Parameters

options

CanisterStatusOptions

Options for querying the canister status, see CanisterStatusOptions.

Returns

Promise<CanisterStatusResult>

The canister status, see CanisterStatusResult.

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const status = await pic.canisterStatus({ canisterId });

await pic.tearDown();
await picServer.stop();

createActor()

createActor<T>(options): Actor<T>

Defined in: packages/pic/src/pocket-ic.ts:973

Creates an Actor for the given canister. An Actor is a typesafe class that implements the Candid interface of a canister. To create a canister for the Actor, see createCanister. For a more convenient way of creating a PocketIC instance, creating a canister and installing code, see setupCanister.

Type Parameters

T

T extends ActorInterface<T> = object

The type of the Actor. Must implement ActorInterface.

Parameters

options

CreateActorOptions

Options for creating the Actor, see CreateActorOptions.

Returns

Actor<T>

The Actor instance.

Example

import { resolve } from 'node:path';
import { PocketIc, PocketIcServer, generateRandomIdentity } from '@dfinity/pic';
import { _SERVICE, idlFactory } from '../declarations/backend.did';

const wasm = resolve('..', '..', 'canister.wasm');
const alice = generateRandomIdentity();

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const canisterId = await pic.createCanister();
await pic.installCode({ canisterId, wasm });
const actor = pic.createActor<_SERVICE>({
  idlFactory,
  canisterId,
  sender: alice.getPrincipal(),
});

await pic.tearDown();
await picServer.stop();

createCanister()

createCanister(options?): Promise<Principal>

Defined in: packages/pic/src/pocket-ic.ts:249

Creates a new canister. For a more convenient way of creating a PocketIC instance, creating a canister and installing code, see setupCanister.

Parameters

options?

CreateCanisterOptions = {}

Options for creating the canister, see CreateCanisterOptions.

Returns

Promise<Principal>

The Principal of the newly created canister.

See

Principal

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const canisterId = await pic.createCanister();

await pic.tearDown();
await picServer.stop();

createDeferredActor()

createDeferredActor<T>(options): DeferredActor<T>

Defined in: packages/pic/src/pocket-ic.ts:1016

Creates a DeferredActor for the given canister. A DeferredActor is a typesafe class that implements the Candid interface of a canister.

A DeferredActor in contrast to a normal Actor will submit the call to the PocketIc replica, but the call will not be executed immediately. Instead, the calls are queued and a Promise is returned by the DeferredActor that can be awaited to process the pending canister call.

To create a canister for the DeferredActor, see createCanister. For a more convenient way of creating a PocketIC instance, creating a canister and installing code, see setupCanister.

Type Parameters

T

T extends ActorInterface<T> = object

The type of the DeferredActor. Must implement ActorInterface.

Parameters

options

CreateActorOptions

Options for creating the DeferredActor, see CreateActorOptions.

Returns

DeferredActor<T>

The DeferredActor instance.

Example

const deferredActor = pic.createDeferredActor<_SERVICE>({
  idlFactory,
  canisterId,
});

const executeCall = await deferredActor.greet('PicJS');
// other calls or ticks...
const response = await executeCall();

deleteCanister()

deleteCanister(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:383

Deletes the given canister. The canister must be stopped first, see stopCanister.

Parameters

options

DeleteCanisterOptions

Options for deleting the canister, see DeleteCanisterOptions.

Returns

Promise<void>

See

Principal

Example

await pic.stopCanister({ canisterId, sender });
await pic.deleteCanister({ canisterId, sender });

const exists = await pic.canisterExists(canisterId); // false

deleteCanisterSnapshot()

deleteCanisterSnapshot(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:878

Deletes a snapshot of the given canister.

Parameters

options

CanisterSnapshotOptions

Options for deleting the snapshot, see CanisterSnapshotOptions.

Returns

Promise<void>

downloadCanisterSnapshot()

downloadCanisterSnapshot(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:902

Downloads a snapshot of the given canister to a directory on the machine running the PocketIC server, e.g. to reuse a canister’s state across test runs. Upload it again with uploadCanisterSnapshot.

Parameters

options

DownloadCanisterSnapshotOptions

Options for downloading the snapshot, see DownloadCanisterSnapshotOptions.

Returns

Promise<void>

fetchCanisterLogs()

fetchCanisterLogs(options): Promise<CanisterLogRecord[]>

Defined in: packages/pic/src/pocket-ic.ts:1123

Fetches the log records of the given canister, e.g. to inspect traps in timers or heartbeats. Only controllers can read a canister’s logs unless its log visibility allows otherwise, see FetchCanisterLogsOptions.sender.

Parameters

options

FetchCanisterLogsOptions

Options for fetching canister logs, see FetchCanisterLogsOptions.

Returns

Promise<CanisterLogRecord[]>

The canister’s log records, see CanisterLogRecord.

Example

import { PocketIc, PocketIcServer, generateRandomIdentity } from '@dfinity/pic';

const controller = generateRandomIdentity();

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const canisterId = await pic.createCanister({
  sender: controller.getPrincipal(),
  controllers: [controller.getPrincipal()],
});
// install and call the canister...

const logs = await pic.fetchCanisterLogs({
  canisterId,
  sender: controller.getPrincipal(),
});
const messages = logs.map(log => new TextDecoder().decode(log.content));

await pic.tearDown();
await picServer.stop();

getApplicationSubnets()

getApplicationSubnets(): Promise<SubnetTopology[]>

Defined in: packages/pic/src/pocket-ic.ts:1796

Get all application subnet topologies for this instance’s network. The instance network topology is configured via the create method.

Returns

Promise<SubnetTopology[]>

An array of subnet topologies for each application subnet that exists on this instance’s network.

getBitcoinSubnet()

getBitcoinSubnet(): Promise<SubnetTopology | undefined>

Defined in: packages/pic/src/pocket-ic.ts:1712

Get the Bitcoin subnet topology for this instance’s network. The instance network topology is configured via the create method.

Returns

Promise<SubnetTopology | undefined>

The subnet topology for the Bitcoin subnet, if it exists on this instance’s network.

getCanisterSubnetId()

getCanisterSubnetId(canisterId): Promise<Principal | null>

Defined in: packages/pic/src/pocket-ic.ts:1639

Gets the subnet Id of the provided canister Id.

Parameters

canisterId

Principal

The Principal of the canister to get the subnet Id of.

Returns

Promise<Principal | null>

The canister’s subnet Id if the canister exists, null otherwise.

See

Principal

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const subnetId = await pic.getCanisterSubnetId(canisterId);

await pic.tearDown();
await picServer.stop();

getControllers()

getControllers(canisterId): Promise<Principal[]>

Defined in: packages/pic/src/pocket-ic.ts:1343

Get the controllers of the specified canister.

Parameters

canisterId

Principal

The Principal of the canister to get the controllers of.

Returns

Promise<Principal[]>

The controllers of the specified canister.

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const controllers = await pic.getControllers(canisterId);

await pic.tearDown();
await picServer.stop();

getCyclesBalance()

getCyclesBalance(canisterId): Promise<bigint>

Defined in: packages/pic/src/pocket-ic.ts:1839

Gets the current cycle balance of the specified canister.

Parameters

canisterId

Principal

The Principal of the canister to check.

Returns

Promise<bigint>

The current cycles balance of the canister.

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const cyclesBalance = await pic.getCyclesBalance(canisterId);

await pic.tearDown();
await picServer.stop();

getDefaultEffectiveCanisterId()

getDefaultEffectiveCanisterId(): Promise<Principal>

Defined in: packages/pic/src/pocket-ic.ts:1701

Get the default effective canister id for this PocketIC instance. This is useful when calling IcManagementCanister.provisionalCreateCanisterWithCycles on the management canister from @icp-sdk/canisters/ic-management.

Returns

Promise<Principal>

The default effective canister id.

See

Principal

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';
import { IcManagementCanister } from '@icp-sdk/canisters/ic-management';

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const defaultEffectiveCanisterId = await pic.getDefaultEffectiveCanisterId();

const managementCanister = IcManagementCanister.create({ agent });
const canisterId = await managementCanister.provisionalCreateCanisterWithCycles({
  canisterId: defaultEffectiveCanisterId,
});

await pic.tearDown();
await picServer.stop();

getFiduciarySubnet()

getFiduciarySubnet(): Promise<SubnetTopology | undefined>

Defined in: packages/pic/src/pocket-ic.ts:1725

Get the Fiduciary subnet topology for this instance’s network. The instance network topology is configured via the create method.

Returns

Promise<SubnetTopology | undefined>

The subnet topology for the Fiduciary subnet, if it exists on this instance’s network.

getInternetIdentitySubnet()

getInternetIdentitySubnet(): Promise<SubnetTopology | undefined>

Defined in: packages/pic/src/pocket-ic.ts:1755

Get the Internet Identity subnet topology for this instance’s network. The instance network topology is configured via the create method.

Returns

Promise<SubnetTopology | undefined>

The subnet topology for the Internet Identity subnet, if it exists on this instance’s network.

getNnsSubnet()

getNnsSubnet(): Promise<SubnetTopology | undefined>

Defined in: packages/pic/src/pocket-ic.ts:1770

Get the NNS subnet topology for this instance’s network. The instance network topology is configured via the create method.

Returns

Promise<SubnetTopology | undefined>

The subnet topology for the NNS subnet, if it exists on this instance’s network.

getPendingHttpsOutcalls()

getPendingHttpsOutcalls(): Promise<PendingHttpsOutcall[]>

Defined in: packages/pic/src/pocket-ic.ts:1993

Get all pending HTTPS Outcalls across all subnets on this PocketIC instance.

Returns

Promise<PendingHttpsOutcall[]>

An array of pending HTTPS Outcalls.

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

// queue the canister message that will send the HTTPS Outcall
const executeGoogleSearch = await deferredActor.google_search();

// tick for two rounds to allow the canister message to be processed
// and for the HTTPS Outcall to be queued
await pic.tick(2);

// get all queued HTTPS Outcalls
const pendingHttpsOutcalls = await pic.getPendingHttpsOutcalls();

// get the first pending HTTPS Outcall
const pendingGoogleSearchOutcall = pendingHttpsOutcalls[0];

// mock the HTTPS Outcall
await pic.mockPendingHttpsOutcall({
  requestId: pendingGoogleSearchOutcall.requestId,
  subnetId: pendingGoogleSearchOutcall.subnetId,
  response: {
    type: 'success',
    body: new TextEncoder().encode('Google search result'),
    statusCode: 200,
    headers: [],
  },
});

// finish executing the message, including the HTTPS Outcall
const result = await executeGoogleSearch();

await pic.tearDown();
await picServer.stop();

getPubKey()

getPubKey(subnetId): Promise<Uint8Array<ArrayBufferLike>>

Defined in: packages/pic/src/pocket-ic.ts:1587

Fetch the public key of the specified subnet.

Parameters

subnetId

Principal

The Principal of the subnet to fetch the public key of.

Returns

Promise<Uint8Array<ArrayBufferLike>>

The public key of the specified subnet.

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const subnets = pic.getApplicationSubnets();
const pubKey = await pic.getPubKey(subnets[0].id);

await pic.tearDown();
await picServer.stop();

getSnsSubnet()

getSnsSubnet(): Promise<SubnetTopology | undefined>

Defined in: packages/pic/src/pocket-ic.ts:1783

Get the SNS subnet topology for this instance’s network. The instance network topology is configured via the create method.

Returns

Promise<SubnetTopology | undefined>

The subnet topology for the SNS subnet, if it exists on this instance’s network.

getStableMemory()

getStableMemory(canisterId): Promise<Uint8Array<ArrayBufferLike>>

Defined in: packages/pic/src/pocket-ic.ts:1939

Get the stable memory of a given canister.

Parameters

canisterId

Principal

The Principal of the canister to get the stable memory of.

Returns

Promise<Uint8Array<ArrayBufferLike>>

A blob containing the canister’s stable memory.

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const stableMemory = await pic.getStableMemory(canisterId);

await pic.tearDown();
await picServer.stop();

getSystemSubnets()

getSystemSubnets(): Promise<SubnetTopology[]>

Defined in: packages/pic/src/pocket-ic.ts:1809

Get all system subnet topologies for this instance’s network. The instance network topology is configured via the create method.

Returns

Promise<SubnetTopology[]>

An array of subnet topologies for each system subnet that exists on this instance’s network.

getTestThresholdKeysSubnet()

getTestThresholdKeysSubnet(): Promise<SubnetTopology | undefined>

Defined in: packages/pic/src/pocket-ic.ts:1738

Get the test threshold keys subnet topology for this instance’s network. The instance network topology is configured via the create method.

Returns

Promise<SubnetTopology | undefined>

The subnet topology for the test threshold keys subnet, if it exists on this instance’s network.

getTime()

getTime(): Promise<number>

Defined in: packages/pic/src/pocket-ic.ts:1365

Get the current time of the IC in milliseconds since the Unix epoch.

Returns

Promise<number>

The current time in milliseconds since the UNIX epoch.

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const time = await pic.getTime();

await pic.tearDown();
await picServer.stop();

getTopology()

getTopology(): Promise<SubnetTopology[]>

Defined in: packages/pic/src/pocket-ic.ts:1667

Get the topology of this instance’s network. The topology is a list of subnets, each with a type and a list of canister ID ranges that can be deployed to that subnet. The instance network topology is configured via the create method.

Returns

Promise<SubnetTopology[]>

An array of subnet topologies, see SubnetTopology.

ingressStatus()

ingressStatus(call, options?): Promise<Uint8Array<ArrayBufferLike> | null>

Defined in: packages/pic/src/pocket-ic.ts:1266

Fetches the status of the given call without executing any rounds, see submitCall.

Parameters

call

SubmittedCall

The submitted call, see SubmittedCall.

options?

IngressStatusOptions = {}

Options for fetching the status, see IngressStatusOptions.

Returns

Promise<Uint8Array<ArrayBufferLike> | null>

The Candid-encoded response of the update call if it has finished, null otherwise. Throws if the call was rejected.

installCode()

installCode(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:471

Installs the given WASM module to the provided canister. To create a canister to install code to, see createCanister. For a more convenient way of creating a PocketIC instance, creating a canister and installing code, see setupCanister.

Parameters

options

InstallCodeOptions

Options for installing the code, see InstallCodeOptions.

Returns

Promise<void>

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';
import { resolve } from 'node:path';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));
const wasm = resolve('..', '..', 'canister.wasm');

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.installCode({ canisterId, wasm });

await pic.tearDown();
await picServer.stop();

listCanisterSnapshots()

listCanisterSnapshots(options): Promise<CanisterSnapshot[]>

Defined in: packages/pic/src/pocket-ic.ts:856

Lists the snapshots of the given canister.

Parameters

options

ListCanisterSnapshotsOptions

Options for listing the snapshots, see ListCanisterSnapshotsOptions.

Returns

Promise<CanisterSnapshot[]>

The snapshots, see CanisterSnapshot.

loadCanisterSnapshot()

loadCanisterSnapshot(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:832

Restores the given canister from one of its snapshots, see takeCanisterSnapshot.

Parameters

options

CanisterSnapshotOptions

Options for loading the snapshot, see CanisterSnapshotOptions.

Returns

Promise<void>

makeLive()

makeLive(options?): Promise<number>

Defined in: packages/pic/src/pocket-ic.ts:2093

Make the PocketIC instance live by enabling auto progress and starting an HTTP gateway. If the instance was created with CreateInstanceOptions.httpGateway, that gateway is used instead. If the instance is already live, this method returns the port of its HTTP gateway, starting one first if the instance was created live with CreateInstanceOptions.autoProgress.

Parameters

options?

MakeLiveOptions = {}

Options for making the instance live, see MakeLiveOptions. To change them on a live instance, call stopLive first.

Returns

Promise<number>

The HTTP Gateway port.

Example

import { Actor, HttpAgent } from '@icp-sdk/core/agent';
import { PocketIc, PocketIcServer } from '@dfinity/pic';
import { resolve } from 'node:path';
import { idlFactory } from '../declarations';

const wasm = resolve('..', '..', 'canister.wasm');

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());
const { canisterId } = await pic.setupCanister({ idlFactory, wasm });

const httpGatewayPort = await pic.makeLive({ artificialDelayMs: 500 });
const agent = await HttpAgent.create({
  host: `http://localhost:${httpGatewayPort}`,
  shouldFetchRootKey: true,
});
const actor = Actor.createActor(idlFactory, { agent, canisterId });

await pic.stopLive();
await pic.tearDown();
await picServer.stop();

mockPendingHttpsOutcall()

mockPendingHttpsOutcall(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:2044

Mock a pending HTTPS Outcall.

Parameters

options

MockPendingHttpsOutcallOptions

Options for mocking the pending HTTPS Outcall, see MockPendingHttpsOutcallOptions.

Returns

Promise<void>

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

// queue the canister message that will send the HTTPS Outcall
const executeGoogleSearch = await deferredActor.google_search();

// tick for two rounds to allow the canister message to be processed
// and for the HTTPS Outcall to be queued
await pic.tick(2);

// get all queued HTTPS Outcalls
const pendingHttpsOutcalls = await pic.getPendingHttpsOutcalls();

// get the first pending HTTPS Outcall
const pendingGoogleSearchOutcall = pendingHttpsOutcalls[0];

// mock the HTTPS Outcall
await pic.mockPendingHttpsOutcall({
  requestId: pendingGoogleSearchOutcall.requestId,
  subnetId: pendingGoogleSearchOutcall.subnetId,
  response: {
    type: 'success',
    body: new TextEncoder().encode('Google search result'),
    statusCode: 200,
    headers: [],
  },
});

// finish executing the message, including the HTTPS Outcall
const result = await executeGoogleSearch();

await pic.tearDown();
await picServer.stop();

queryCall()

queryCall(options): Promise<Uint8Array<ArrayBufferLike>>

Defined in: packages/pic/src/pocket-ic.ts:1066

Makes a query call to the given canister.

Parameters

options

QueryCallOptions

Options for making the query call, see QueryCallOptions.

Returns

Promise<Uint8Array<ArrayBufferLike>>

The Candid-encoded response of the query call.

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';
import { _SERVICE, idlFactory } from '../declarations';

const wasm = resolve('..', '..', 'canister.wasm');

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

canisterId = await pic.createCanister({
  sender: controllerIdentity.getPrincipal(),
});
await pic.installCode({ canisterId, wasm });

const res = await pic.queryCall({
 canisterId,
 method: 'greet',
});

await pic.tearDown();
await picServer.stop();

reinstallCode()

reinstallCode(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:543

Reinstalls the given WASM module to the provided canister. This will reset both the canister’s heap and its stable memory. To create a canister to upgrade, see createCanister. To install the initial WASM module to a new canister, see installCode.

Parameters

options

ReinstallCodeOptions

Options for reinstalling the code, see ReinstallCodeOptions.

Returns

Promise<void>

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';
import { resolve } from 'node:path';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));
const wasm = resolve('..', '..', 'canister.wasm');

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.reinstallCode({ canisterId, wasm });

await pic.tearDown();
await picServer.stop();

resetCertifiedTime()

resetCertifiedTime(): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:1420

Reset the time of the IC to the current time and immediately have query calls and read state requests reflect the new time.

Use resetTime to reset time without immediately reflecting the new time.

Returns

Promise<void>

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.resetCertifiedTime();

const time = await pic.getTime();

await pic.tearDown();
await picServer.stop();

resetTime()

resetTime(): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:1395

Reset the time of the IC to the current time. tick should be called after calling this method in order for query calls and read state request to reflect the new time.

Use resetCertifiedTime to set time and immediately have query calls and read state requests reflect the new time.

Returns

Promise<void>

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.resetTime();
await pic.tick();

const time = await pic.getTime();

await pic.tearDown();
await picServer.stop();

setCertifiedTime()

setCertifiedTime(time): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:1494

Set the current time of the IC and immediately have query calls and read state requests reflect the new time.

Use setTime to set time without immediately reflecting the new time.

Parameters

time

The time to set in milliseconds since the Unix epoch.

number | Date

Returns

Promise<void>

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const pic = await PocketIc.create();

const date = new Date();

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.setCertifiedTime(date);
// or
await pic.setCertifiedTime(date.getTime());

const time = await pic.getTime();

await pic.tearDown();
await picServer.stop();

setStableMemory()

setStableMemory(canisterId, stableMemory): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:1904

Set the stable memory of a given canister.

Parameters

canisterId

Principal

The Principal of the canister to set the stable memory of.

stableMemory

Uint8Array

A blob containing the stable memory to set.

Returns

Promise<void>

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));
const stableMemory = new Uint8Array([0, 1, 2, 3, 4]);

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.setStableMemory(canisterId, stableMemory);

await pic.tearDown();
await picServer.stop();

setTime()

setTime(time): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:1457

Set the current time of the IC. tick should be called after calling this method in order for query calls and read state request to reflect the new time.

Use setCertifiedTime to set time and immediately have query calls and read state requests reflect the new time.

Parameters

time

The time to set in milliseconds since the Unix epoch.

number | Date

Returns

Promise<void>

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const pic = await PocketIc.create();

const date = new Date();

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.setTime(date);
// or
await pic.setTime(date.getTime());

await pic.tick();

const time = await pic.getTime();

await pic.tearDown();
await picServer.stop();

setupCanister()

setupCanister<T>(options): Promise<CanisterFixture<T>>

Defined in: packages/pic/src/pocket-ic.ts:205

A convenience method that creates a new canister, installs the given WASM module to it and returns a typesafe Actor that implements the Candid interface of the canister. To just create a canister, see createCanister. To just install code to an existing canister, see installCode. To just create an Actor for an existing canister, see createActor.

Type Parameters

T

T extends ActorInterface<T> = object

Parameters

options

SetupCanisterOptions

Options for setting up the canister, see SetupCanisterOptions.

Returns

Promise<CanisterFixture<T>>

The Actor instance.

See

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';
import { _SERVICE, idlFactory } from '../declarations';

const wasmPath = resolve('..', '..', 'canister.wasm');

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const fixture = await pic.setupCanister<_SERVICE>({ idlFactory, wasmPath });
const { actor } = fixture;

await pic.tearDown();
await picServer.stop();

startCanister()

startCanister(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:300

Starts the given canister.

Parameters

options

StartCanisterOptions

Options for starting the canister, see StartCanisterOptions.

Returns

Promise<void>

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.startCanister({ canisterId });

await pic.tearDown();
await picServer.stop();

stopCanister()

stopCanister(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:345

Stops the given canister.

Parameters

options

StopCanisterOptions

Options for stopping the canister, see StopCanisterOptions.

Returns

Promise<void>

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.stopCanister({ canisterId });

await pic.tearDown();
await picServer.stop();

stopLive()

stopLive(): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:2148

Disables auto progress and stops the HTTP gateway started by makeLive. A gateway created with CreateInstanceOptions.httpGateway keeps running until the instance is torn down.

Returns

Promise<void>

Example

const httpGatewayPort = await pic.makeLive();
// make calls through the HTTP gateway...

await pic.stopLive();

submitCall()

submitCall(options): Promise<SubmittedCall>

Defined in: packages/pic/src/pocket-ic.ts:1222

Submits an update call to the given canister without executing it. The call is executed by later rounds, e.g. from tick, and its result is fetched with awaitCall or ingressStatus.

Parameters

options

UpdateCallOptions

Options for submitting the update call, see UpdateCallOptions.

Returns

Promise<SubmittedCall>

The submitted call, see SubmittedCall.

Example

const call = await pic.submitCall({ canisterId, method: 'greet' });

await pic.ingressStatus(call); // null, the call has not been executed yet
await pic.tick();
const res = await pic.ingressStatus(call); // the Candid-encoded response

takeCanisterSnapshot()

takeCanisterSnapshot(options): Promise<CanisterSnapshot>

Defined in: packages/pic/src/pocket-ic.ts:802

Takes a snapshot of the given canister’s code and memory, which loadCanisterSnapshot restores. Canister settings are not included.

Parameters

options

TakeCanisterSnapshotOptions

Options for taking the snapshot, see TakeCanisterSnapshotOptions.

Returns

Promise<CanisterSnapshot>

The snapshot, see CanisterSnapshot.

Example

const snapshot = await pic.takeCanisterSnapshot({ canisterId, sender });

// change the canister's state...

await pic.loadCanisterSnapshot({
  canisterId,
  snapshotId: snapshot.id,
  sender,
});

tearDown()

tearDown(): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:1289

Deletes the PocketIC instance.

Returns

Promise<void>

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.tearDown();
await picServer.stop();

tick()

tick(times?): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:1314

Make the IC produce and progress by one block. Accepts a parameter times to tick multiple times, the default is 1.

Parameters

times?

number = 1

The number of new blocks to produce and progress by. Defaults to 1.

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.tick();

// or to tick multiple times
await pic.tick(3);

await pic.tearDown();
await picServer.stop();

Returns

Promise<void>

uninstallCode()

uninstallCode(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:420

Uninstalls the code of the given canister, removing its WASM module and memory. The canister and its settings are kept.

Parameters

options

UninstallCodeOptions

Options for uninstalling the code, see UninstallCodeOptions.

Returns

Promise<void>

See

Principal

Example

await pic.uninstallCode({ canisterId, sender });

const { moduleHash } = await pic.canisterStatus({ canisterId, sender }); // null

updateCall()

updateCall(options): Promise<Uint8Array<ArrayBufferLike>>

Defined in: packages/pic/src/pocket-ic.ts:1181

Makes an update call to the given canister.

Parameters

options

UpdateCallOptions

Options for making the update call, see UpdateCallOptions.

Returns

Promise<Uint8Array<ArrayBufferLike>>

The Candid-encoded response of the update call.

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';
import { _SERVICE, idlFactory } from '../declarations';

const wasm = resolve('..', '..', 'canister.wasm');

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

canisterId = await pic.createCanister({
  sender: controllerIdentity.getPrincipal(),
});
await pic.installCode({ canisterId, wasm });

const res = await pic.updateCall({
 canisterId,
 method: 'greet',
});

await pic.tearDown();
await picServer.stop();

updateCanisterSettings()

updateCanisterSettings(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:672

Updates the settings of the given canister.

Parameters

options

UpdateCanisterSettingsOptions

Options for updating the canister settings, see UpdateCanisterSettingsOptions.

Returns

Promise<void>

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.updateCanisterSettings({
 canisterId,
 controllers: [Principal.fromUint8Array(new Uint8Array([1]))],
});

await pic.tearDown();
await picServer.stop();

upgradeCanister()

upgradeCanister(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:608

Upgrades the given canister with the given WASM module. This will reset the canister’s heap, but preserve stable memory. To create a canister to upgrade to, see createCanister. To install the initial WASM module to a new canister, see installCode.

Parameters

options

UpgradeCanisterOptions

Options for upgrading the canister, see UpgradeCanisterOptions.

Returns

Promise<void>

See

Principal

Example

import { Principal } from '@icp-sdk/core/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';
import { resolve } from 'node:path';

const canisterId = Principal.fromUint8Array(new Uint8Array([0]));
const wasm = resolve('..', '..', 'canister.wasm');

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

await pic.upgradeCanister({ canisterId, wasm });

await pic.tearDown();
await picServer.stop();

uploadCanisterSnapshot()

uploadCanisterSnapshot(options): Promise<Uint8Array<ArrayBufferLike>>

Defined in: packages/pic/src/pocket-ic.ts:924

Uploads a snapshot to the given canister from a directory on the machine running the PocketIC server, as written by downloadCanisterSnapshot. Restore the canister from it with loadCanisterSnapshot.

Parameters

options

UploadCanisterSnapshotOptions

Options for uploading the snapshot, see UploadCanisterSnapshotOptions.

Returns

Promise<Uint8Array<ArrayBufferLike>>

The ID of the uploaded snapshot.

verifyCanisterSignature()

verifyCanisterSignature(options): Promise<void>

Defined in: packages/pic/src/pocket-ic.ts:1610

Verifies a canister signature, as issued by canisters like Internet Identity.

Parameters

options

VerifyCanisterSignatureOptions

Options for verifying the signature, see VerifyCanisterSignatureOptions. Throws if the signature is invalid.

Returns

Promise<void>

Example

const nnsSubnet = await pic.getNnsSubnet();
const rootKey = await pic.getPubKey(nnsSubnet.id);

await pic.verifyCanisterSignature({
  message,
  signature,
  publicKey,
  rootKey,
});

create()

static create(url, options?): Promise<PocketIc>

Defined in: packages/pic/src/pocket-ic.ts:165

Creates a PocketIC instance.

Parameters

url

string

The URL of an existing PocketIC server to connect to.

options?

CreateInstanceOptions

Options for creating the PocketIC instance see CreateInstanceOptions.

Returns

Promise<PocketIc>

A new PocketIC instance.

Example

import { PocketIc, PocketIcServer } from '@dfinity/pic';

const picServer = await PocketIcServer.start();
const pic = await PocketIc.create(picServer.getUrl());

const fixture = await pic.setupCanister<_SERVICE>({ idlFactory, wasmPath });
const { actor } = fixture;

await pic.tearDown();
await picServer.stop();