Class: PocketIc

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.create();
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.create();
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

create()

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

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.create();
const pic = await PocketIc.create(picServer.getUrl());

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

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

Source

pocket-ic.ts:109

setupCanister()

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

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 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.create();
const pic = await PocketIc.create(picServer.getUrl());

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

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

Source

pocket-ic.ts:149

createCanister()

createCanister(options): Promise< Principal >

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.create();
const pic = await PocketIc.create(picServer.getUrl());

const canisterId = await pic.createCanister();

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

Source

pocket-ic.ts:205

startCanister()

startCanister(options): Promise< void >

Starts the given canister.

Parameters

• options: StartCanisterOptions

Options for starting the canister, see StartCanisterOptions.

Returns

Promise< void >

See

Principal

Example

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

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

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

await pic.startCanister({ canisterId });

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

Source

pocket-ic.ts:268

stopCanister()

stopCanister(options): Promise< void >

Stops the given canister.

Parameters

• options: StopCanisterOptions

Options for stopping the canister, see StopCanisterOptions.

Returns

Promise< void >

See

Principal

Example

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

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

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

await pic.stopCanister({ canisterId });

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

Source

pocket-ic.ts:313

installCode()

installCode(options): Promise< void >

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 '@dfinity/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.create();
const pic = await PocketIc.create(picServer.getUrl());

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

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

Source

pocket-ic.ts:363

reinstallCode()

reinstallCode(options): Promise< void >

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 '@dfinity/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.create();
const pic = await PocketIc.create(picServer.getUrl());

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

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

Source

pocket-ic.ts:424

upgradeCanister()

upgradeCanister(options): Promise< void >

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 '@dfinity/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.create();
const pic = await PocketIc.create(picServer.getUrl());

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

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

Source

pocket-ic.ts:479

updateCanisterSettings()

updateCanisterSettings(options): Promise< void >

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 '@dfinity/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

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

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

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

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

Source

pocket-ic.ts:532

createActor()

createActor<T>(interfaceFactory, canisterId): Actor< T >

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 extends ActorInterface< T > = object

Parameters

• interfaceFactory: InterfaceFactory

The InterfaceFactory to use for the Actor.

• canisterId: Principal

The Principal of the canister to create the Actor for.

Returns

Actor< T >

The Actor instance.

Typeparam

T The type of the Actor. Must implement ActorInterface.

See

Example

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

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

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

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

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

Source

pocket-ic.ts:595

createDeferredActor()

createDeferredActor<T>(interfaceFactory, canisterId): DeferredActor< T >

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 extends ActorInterface< T > = object

Parameters

• interfaceFactory: InterfaceFactory

The InterfaceFactory to use for the DeferredActor.

• canisterId: Principal

The Principal of the canister to create the DeferredActor for.

Returns

DeferredActor< T >

The DeferredActor instance.

Typeparam

T The type of the DeferredActor. Must implement ActorInterface.

See

Example

Source

pocket-ic.ts:630

queryCall()

queryCall(options): Promise< ArrayBufferLike >

Makes a query call to the given canister.

Parameters

• options: QueryCallOptions

Options for making the query call, see QueryCallOptions.

Returns

Promise< ArrayBufferLike >

The Candid-encoded response of the query call.

Example

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

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

const picServer = await PocketIcServer.create();
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();

Source

pocket-ic.ts:674

updateCall()

updateCall(options): Promise< ArrayBufferLike >

Makes an update call to the given canister.

Parameters

• options: UpdateCallOptions

Options for making the update call, see UpdateCallOptions.

Returns

Promise< ArrayBufferLike >

The Candid-encoded response of the update call.

Example

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

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

const picServer = await PocketIcServer.create();
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();

Source

pocket-ic.ts:727

tearDown()

tearDown(): Promise< void >

Deletes the PocketIC instance.

Returns

Promise< void >

Example

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

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

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

Source

pocket-ic.ts:763

tick()

tick(times): Promise< void >

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.create();
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 >

Source

pocket-ic.ts:788

getControllers()

getControllers(canisterId): Promise< Principal[] >

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 '@dfinity/principal';

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

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

const controllers = await pic.getControllers(canisterId);

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

#### Source

[pocket-ic.ts:816](https://github.com/dfinity/pic-js/blob/ab67d5290bfc22ea0c731f5b4ae42b85bba1c599/packages/pic/src/pocket-ic.ts#L816)

***

### getTime()

> **getTime**(): `Promise`\< `number` \>

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

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

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

const time = await pic.getTime();

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

Source

pocket-ic.ts:838

resetTime()

resetTime(): Promise< void >

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.create();
const pic = await PocketIc.create(picServer.getUrl());

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

const time = await pic.getTime();

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

Source

pocket-ic.ts:868

resetCertifiedTime()

resetCertifiedTime(): Promise< void >

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.create();
const pic = await PocketIc.create(picServer.getUrl());

await pic.resetCertifiedTime();

const time = await pic.getTime();

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

Source

pocket-ic.ts:893

setTime()

setTime(time): Promise< void >

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: number | Date

The time to set in milliseconds since the Unix epoch.

Returns

Promise< void >

Example

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

const pic = await PocketIc.create();

const date = new Date();

const picServer = await PocketIcServer.create();
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();

Source

pocket-ic.ts:930

setCertifiedTime()

setCertifiedTime(time): Promise< void >

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: number | Date

The time to set in milliseconds since the Unix epoch.

Returns

Promise< void >

Example

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

const pic = await PocketIc.create();

const date = new Date();

const picServer = await PocketIcServer.create();
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();

Source

pocket-ic.ts:967

advanceTime()

advanceTime(duration): Promise< void >

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.create();
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();

Source

pocket-ic.ts:1002

advanceCertifiedTime()

advanceCertifiedTime(duration): Promise< void >

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.create();
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();

Source

pocket-ic.ts:1032

getPubKey()

getPubKey(subnetId): Promise< ArrayBufferLike >

Fetch the public key of the specified subnet.

Parameters

• subnetId: Principal

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

Returns

Promise< ArrayBufferLike >

The public key of the specified subnet.

Example

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

const picServer = await PocketIcServer.create();
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();

Source

pocket-ic.ts:1058

getCanisterSubnetId()

getCanisterSubnetId(canisterId): Promise< null | Principal >

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< null | Principal >

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.create();
const pic = await PocketIc.create(picServer.getUrl());

const subnetId = await pic.getCanisterSubnetId(canisterId);

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

Source

pocket-ic.ts:1085

getTopology()

getTopology(): Promise< SubnetTopology[] >

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.

Source

pocket-ic.ts:1101

getBitcoinSubnet()

getBitcoinSubnet(): Promise< undefined | SubnetTopology >

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

Returns

Promise< undefined | SubnetTopology >

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

Source

pocket-ic.ts:1114

getFiduciarySubnet()

getFiduciarySubnet(): Promise< undefined | SubnetTopology >

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

Returns

Promise< undefined | SubnetTopology >

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

Source

pocket-ic.ts:1127

getInternetIdentitySubnet()

getInternetIdentitySubnet(): Promise< undefined | SubnetTopology >

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

Returns

Promise< undefined | SubnetTopology >

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

Source

pocket-ic.ts:1140

getNnsSubnet()

getNnsSubnet(): Promise< undefined | SubnetTopology >

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

Returns

Promise< undefined | SubnetTopology >

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

Source

pocket-ic.ts:1155

getSnsSubnet()

getSnsSubnet(): Promise< undefined | SubnetTopology >

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

Returns

Promise< undefined | SubnetTopology >

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

Source

pocket-ic.ts:1168

getApplicationSubnets()

getApplicationSubnets(): Promise< SubnetTopology[] >

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.

Source

pocket-ic.ts:1181

getSystemSubnets()

getSystemSubnets(): Promise< SubnetTopology[] >

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.

Source

pocket-ic.ts:1194

getCyclesBalance()

getCyclesBalance(canisterId): Promise< number >

Gets the current cycle balance of the specified canister.

Parameters

• canisterId: Principal

The Principal of the canister to check.

Returns

Promise< number >

The current cycles balance of the canister.

See

Principal

Example

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

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

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

const cyclesBalance = await pic.getCyclesBalance(canisterId);

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

Source

pocket-ic.ts:1224

addCycles()

addCycles(canisterId, amount): Promise< number >

Add cycles to the specified canister.

Parameters

• canisterId: Principal

The Principal of the canister to add cycles to.

• amount: number

The amount of cycles to add.

Returns

Promise< number >

The new cycle balance of the canister.

See

Principal

Example

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

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

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

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

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

Source

pocket-ic.ts:1255

setStableMemory()

setStableMemory(canisterId, stableMemory): Promise< void >

Set the stable memory of a given canister.

Parameters

• canisterId: Principal

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

• stableMemory: ArrayBufferLike

A blob containing the stable memory to set.

Returns

Promise< void >

See

Principal

Example

import { Principal } from '@dfinity/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.create();
const pic = await PocketIc.create(picServer.getUrl());

await pic.setStableMemory(canisterId, stableMemory);

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

Source

pocket-ic.ts:1289

getStableMemory()

getStableMemory(canisterId): Promise< ArrayBufferLike >

Get the stable memory of a given canister.

Parameters

• canisterId: Principal

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

Returns

Promise< ArrayBufferLike >

A blob containing the canister's stable memory.

See

Principal

Example

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

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

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

const stableMemory = await pic.getStableMemory(canisterId);

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

Source

pocket-ic.ts:1324

getPendingHttpsOutcalls()

getPendingHttpsOutcalls(): Promise< PendingHttpsOutcall[] >

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 '@dfinity/principal';
import { PocketIc, PocketIcServer } from '@dfinity/pic';

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

const picServer = await PocketIcServer.create();
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();

Source

pocket-ic.ts:1380

mockPendingHttpsOutcall()

mockPendingHttpsOutcall(options): Promise< void >

Mock a pending HTTPS Outcall.

Parameters

• options: MockPendingHttpsOutcallOptions

Options for mocking the pending HTTPS Outcall, see MockPendingHttpsOutcallOptions.

Returns

Promise< void >

Example

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

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

const picServer = await PocketIcServer.create();
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();

Source

pocket-ic.ts:1431

Class: PocketIc

Example​

Methods​

create()​

Parameters​

Returns​

Example​

Source​

setupCanister()​

Type parameters​

Parameters​

Returns​

See​

Example​

Source​

createCanister()​

Parameters​

Returns​

See​

Example​

Source​

startCanister()​

Parameters​

Returns​

See​

Example​

Source​

stopCanister()​

Parameters​

Returns​

See​

Example​

Source​

installCode()​

Parameters​

Returns​

See​

Example​

Source​

reinstallCode()​

Parameters​

Returns​

See​

Example​

Source​

upgradeCanister()​

Parameters​

Returns​

See​

Example​

Source​

updateCanisterSettings()​

Parameters​

Returns​

See​

Example​

Source​

createActor()​

Type parameters​

Parameters​

Returns​

Typeparam​

See​

Example​

Source​

createDeferredActor()​

Type parameters​

Parameters​

Returns​

Typeparam​

See​

Example​

Source​

queryCall()​

Parameters​

Returns​

Example​

Source​

updateCall()​

Parameters​

Example

Methods

create()

Parameters

Returns

Example

Source

setupCanister()

Type parameters

Parameters

Returns

See

Example

Source

createCanister()

Parameters

Returns

See

Example

Source

startCanister()

Parameters

Returns

See

Example

Source

stopCanister()

Parameters

Returns

See

Example

Source

installCode()

Parameters

Returns

See

Example

Source

reinstallCode()

Parameters

Returns

See

Example

Source

upgradeCanister()

Parameters

Returns

See

Example

Source

updateCanisterSettings()

Parameters

Returns

See

Example

Source

createActor()

Type parameters

Parameters

Returns

Typeparam

See

Example

Source

createDeferredActor()

Type parameters

Parameters

Returns

Typeparam

See

Example

Source

queryCall()

Parameters

Returns

Example

Source

updateCall()

Parameters

Returns