@dfinity/pic
Version:
An Internet Computer Protocol canister testing library for TypeScript and JavaScript.
1,001 lines (1,000 loc) • 38.2 kB
TypeScript
import { Principal } from '@icp-sdk/core/principal';
import { IDL } from '@icp-sdk/core/candid';
import { ActorInterface, Actor } from './pocket-ic-actor';
import { CanisterFixture, CreateCanisterOptions, CreateInstanceOptions, InstallCodeOptions, ReinstallCodeOptions, SetupCanisterOptions, UpgradeCanisterOptions, SubnetTopology, UpdateCanisterSettingsOptions, StartCanisterOptions, StopCanisterOptions, QueryCallOptions, UpdateCallOptions, PendingHttpsOutcall, MockPendingHttpsOutcallOptions } from './pocket-ic-types';
import { DeferredActor } from './pocket-ic-deferred-actor';
/**
* This class represents the main PocketIC client.
* It is responsible for interacting with the PocketIC server via the REST API.
* See {@link PocketIcServer} for details on the server to use with this client.
*
* @category API
*
* @example
* The easist way to use PocketIC is to use {@link setupCanister} convenience method:
* ```ts
* 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 {@link createCanister}, {@link installCode} and
* {@link createActor} methods can be used directly:
* ```ts
* 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();
* ```
*/
export declare class PocketIc {
private readonly client;
private constructor();
/**
* Creates a PocketIC instance.
*
* @param url The URL of an existing PocketIC server to connect to.
* @param options Options for creating the PocketIC instance see {@link CreateInstanceOptions}.
* @returns A new PocketIC instance.
*
* @example
* ```ts
* 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();
* ```
*/
static create(url: string, options?: CreateInstanceOptions): Promise<PocketIc>;
/**
* A convenience method that creates a new canister,
* installs the given WASM module to it and returns a typesafe {@link Actor}
* that implements the Candid interface of the canister.
* To just create a canister, see {@link createCanister}.
* To just install code to an existing canister, see {@link installCode}.
* To just create an Actor for an existing canister, see {@link createActor}.
*
* @param options Options for setting up the canister, see {@link SetupCanisterOptions}.
* @returns The {@link Actor} instance.
*
* @see [Candid](https://internetcomputer.org/docs/current/references/candid-ref)
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
setupCanister<T extends ActorInterface<T> = ActorInterface>({ sender, arg, wasm, idlFactory, computeAllocation, controllers, cycles, freezingThreshold, memoryAllocation, targetCanisterId, targetSubnetId, reservedCyclesLimit, }: SetupCanisterOptions): Promise<CanisterFixture<T>>;
/**
* Creates a new canister.
* For a more convenient way of creating a PocketIC instance,
* creating a canister and installing code, see {@link setupCanister}.
*
* @param options Options for creating the canister, see {@link CreateCanisterOptions}.
* @returns The Principal of the newly created canister.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
createCanister({ sender, cycles, controllers, computeAllocation, freezingThreshold, memoryAllocation, reservedCyclesLimit, targetCanisterId, targetSubnetId, }?: CreateCanisterOptions): Promise<Principal>;
/**
* Starts the given canister.
*
* @param options Options for starting the canister, see {@link StartCanisterOptions}.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
startCanister({ canisterId, sender, targetSubnetId, }: StartCanisterOptions): Promise<void>;
/**
* Stops the given canister.
*
* @param options Options for stopping the canister, see {@link StopCanisterOptions}.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
stopCanister({ canisterId, sender, targetSubnetId, }: StopCanisterOptions): Promise<void>;
/**
* Installs the given WASM module to the provided canister.
* To create a canister to install code to, see {@link createCanister}.
* For a more convenient way of creating a PocketIC instance,
* creating a canister and installing code, see {@link setupCanister}.
*
* @param options Options for installing the code, see {@link InstallCodeOptions}.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
installCode({ arg, sender, canisterId, wasm, targetSubnetId, }: InstallCodeOptions): 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 {@link createCanister}.
* To install the initial WASM module to a new canister, see {@link installCode}.
*
* @param options Options for reinstalling the code, see {@link ReinstallCodeOptions}.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
reinstallCode({ sender, arg, canisterId, wasm, }: ReinstallCodeOptions): 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 {@link createCanister}.
* To install the initial WASM module to a new canister, see {@link installCode}.
*
* @param options Options for upgrading the canister, see {@link UpgradeCanisterOptions}.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
upgradeCanister({ sender, arg, canisterId, wasm, upgradeModeOptions, }: UpgradeCanisterOptions): Promise<void>;
/**
* Updates the settings of the given canister.
*
* @param options Options for updating the canister settings, see {@link UpdateCanisterSettingsOptions}.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
updateCanisterSettings({ canisterId, computeAllocation, controllers, freezingThreshold, memoryAllocation, reservedCyclesLimit, sender, }: UpdateCanisterSettingsOptions): Promise<void>;
/**
* Creates an {@link Actor} for the given canister.
* An {@link Actor} is a typesafe class that implements the Candid interface of a canister.
* To create a canister for the {@link Actor}, see {@link createCanister}.
* For a more convenient way of creating a PocketIC instance,
* creating a canister and installing code, see {@link setupCanister}.
*
* @param interfaceFactory The InterfaceFactory to use for the {@link Actor}.
* @param canisterId The Principal of the canister to create the {@link Actor} for.
* @typeParam T The type of the {@link Actor}. Must implement {@link ActorInterface}.
* @returns The {@link Actor} instance.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
* @see [InterfaceFactory](https://js.icp.build/core/latest/libs/candid/api/namespaces/idl/type-aliases/interfacefactory/)
*
* @example
* ```ts
* import { Principal } from '@icp-sdk/core/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.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 });
*
* await pic.tearDown();
* await picServer.stop();
* ```
*/
createActor<T extends ActorInterface<T> = ActorInterface>(interfaceFactory: IDL.InterfaceFactory, canisterId: Principal): Actor<T>;
/**
* Creates a {@link DeferredActor} for the given canister.
* A {@link DeferredActor} is a typesafe class that implements the Candid interface of a canister.
*
* A {@link DeferredActor} in contrast to a normal {@link 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 {@link DeferredActor} that can be awaited to process the pending canister call.
*
* To create a canister for the {@link DeferredActor}, see {@link createCanister}.
* For a more convenient way of creating a PocketIC instance,
* creating a canister and installing code, see {@link setupCanister}.
*
* @param interfaceFactory The InterfaceFactory to use for the {@link DeferredActor}.
* @param canisterId The Principal of the canister to create the {@link DeferredActor} for.
* @typeParam T The type of the {@link DeferredActor}. Must implement {@link ActorInterface}.
* @returns The {@link DeferredActor} instance.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
* @see [InterfaceFactory](https://js.icp.build/core/latest/libs/candid/api/namespaces/idl/type-aliases/interfacefactory/)
*/
createDeferredActor<T extends ActorInterface<T> = ActorInterface>(interfaceFactory: IDL.InterfaceFactory, canisterId: Principal): DeferredActor<T>;
/**
* Makes a query call to the given canister.
*
* @param options Options for making the query call, see {@link QueryCallOptions}.
* @returns The Candid-encoded response of the query call.
*
* @example
* ```ts
* 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();
* ```
*/
queryCall({ canisterId, method, arg, sender, targetSubnetId, }: QueryCallOptions): Promise<Uint8Array>;
/**
* Makes an update call to the given canister.
*
* @param options Options for making the update call, see {@link UpdateCallOptions}.
* @returns The Candid-encoded response of the update call.
*
* @example
* ```ts
* 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();
* ```
*/
updateCall({ canisterId, method, arg, sender, targetSubnetId, }: UpdateCallOptions): Promise<Uint8Array>;
/**
* Deletes the PocketIC instance.
*
* @example
* ```ts
* import { PocketIc, PocketIcServer } from '@dfinity/pic';
*
* const picServer = await PocketIcServer.start();
* const pic = await PocketIc.create(picServer.getUrl());
*
* await pic.tearDown();
* await picServer.stop();
* ```
*/
tearDown(): Promise<void>;
/**
* Make the IC produce and progress by one block. Accepts a parameter `times` to tick multiple times,
* the default is `1`.
*
* @param times The number of new blocks to produce and progress by. Defaults to `1`.
*
* ```ts
* 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();
* ```
*/
tick(times?: number): Promise<void>;
/**
* Get the controllers of the specified canister.
*
* @param canisterId The Principal of the canister to get the controllers of.
* @returns The controllers of the specified canister.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
getControllers(canisterId: Principal): Promise<Principal[]>;
/**
* Get the current time of the IC in milliseconds since the Unix epoch.
*
* @returns The current time in milliseconds since the UNIX epoch.
*
* @example
* ```ts
* 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();
* ```
*/
getTime(): Promise<number>;
/**
* Reset the time of the IC to the current time.
* {@link tick} should be called after calling this method in order for query calls
* and read state request to reflect the new time.
*
* Use {@link resetCertifiedTime} to set time and immediately have query calls and
* read state requests reflect the new time.
*
* @example
* ```ts
* 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();
* ```
*/
resetTime(): 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 {@link resetTime} to reset time without immediately reflecting the new time.
*
* @example
* ```ts
* 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();
* ```
*/
resetCertifiedTime(): Promise<void>;
/**
* Set the current time of the IC.
* {@link tick} should be called after calling this method in order for query calls
* and read state request to reflect the new time.
*
* Use {@link setCertifiedTime} to set time and immediately have query calls and
* read state requests reflect the new time.
*
* @param time The time to set in milliseconds since the Unix epoch.
*
* @example
* ```ts
* 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();
* ```
*/
setTime(time: Date | number): Promise<void>;
/**
* Set the current time of the IC and immediately have query calls and
* read state requests reflect the new time.
*
* Use {@link setTime} to set time without immediately reflecting the new time.
*
* @param time The time to set in milliseconds since the Unix epoch.
*
* @example
* ```ts
* 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();
* ```
*/
setCertifiedTime(time: Date | number): Promise<void>;
/**
* Advance the time of the IC by the given duration in milliseconds.
* {@link tick} should be called after calling this method in order for query calls
* and read state requests to reflect the new time.
*
* Use {@link advanceCertifiedTime} to advance time and immediately have query calls and
* read state requests reflect the new time.
*
* @param duration The duration to advance the time by.
*
* @example
* ```ts
* 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();
* ```
*/
advanceTime(duration: number): 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 {@link advanceTime} to advance time without immediately reflecting the new time.
*
* @param duration The duration to advance the time by.
*
* @example
* ```ts
* 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();
* ```
*/
advanceCertifiedTime(duration: number): Promise<void>;
/**
* Fetch the public key of the specified subnet.
*
* @param subnetId The Principal of the subnet to fetch the public key of.
* @returns The public key of the specified subnet.
*
* @example
* ```ts
* 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();
* ```
*/
getPubKey(subnetId: Principal): Promise<Uint8Array>;
/**
* Gets the subnet Id of the provided canister Id.
*
* @param canisterId The Principal of the canister to get the subnet Id of.
* @returns The canister's subnet Id if the canister exists, `null` otherwise.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
getCanisterSubnetId(canisterId: Principal): Promise<Principal | null>;
/**
* 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 {@link create} method.
*
* @returns An array of subnet topologies, see {@link SubnetTopology}.
*/
getTopology(): Promise<SubnetTopology[]>;
/**
* Get the default effective canister id for this PocketIC instance.
* This is useful when calling [`IcManagementCanister.provisionalCreateCanisterWithCycles`](https://js.icp.build/canisters/latest/api/ic-management/classes/icmanagementcanister#provisionalcreatecanisterwithcycles)
* on the management canister from `@icp-sdk/canisters/ic-management`.
*
* @returns The default effective canister id.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
getDefaultEffectiveCanisterId(): Promise<Principal>;
/**
* Get the Bitcoin subnet topology for this instance's network.
* The instance network topology is configured via the {@link create} method.
*
* @returns The subnet topology for the Bitcoin subnet,
* if it exists on this instance's network.
*/
getBitcoinSubnet(): Promise<SubnetTopology | undefined>;
/**
* Get the Fiduciary subnet topology for this instance's network.
* The instance network topology is configured via the {@link create} method.
*
* @returns The subnet topology for the Fiduciary subnet,
* if it exists on this instance's network.
*/
getFiduciarySubnet(): Promise<SubnetTopology | undefined>;
/**
* Get the Internet Identity subnet topology for this instance's network.
* The instance network topology is configured via the {@link create} method.
*
* @returns The subnet topology for the Internet Identity subnet,
* if it exists on this instance's network.
*/
getInternetIdentitySubnet(): Promise<SubnetTopology | undefined>;
/**
* Get the NNS subnet topology for this instance's network.
* The instance network topology is configured via the {@link create} method.
*
* @returns The subnet topology for the NNS subnet,
* if it exists on this instance's network.
*/
getNnsSubnet(): Promise<SubnetTopology | undefined>;
/**
* Get the SNS subnet topology for this instance's network.
* The instance network topology is configured via the {@link create} method.
*
* @returns The subnet topology for the SNS subnet,
* if it exists on this instance's network.
*/
getSnsSubnet(): Promise<SubnetTopology | undefined>;
/**
* Get all application subnet topologies for this instance's network.
* The instance network topology is configured via the {@link create} method.
*
* @returns An array of subnet topologies for each application subnet
* that exists on this instance's network.
*/
getApplicationSubnets(): Promise<SubnetTopology[]>;
/**
* Get all system subnet topologies for this instance's network.
* The instance network topology is configured via the {@link create} method.
*
* @returns An array of subnet topologies for each system subnet
* that exists on this instance's network.
*/
getSystemSubnets(): Promise<SubnetTopology[]>;
/**
* Gets the current cycle balance of the specified canister.
*
* @param canisterId The Principal of the canister to check.
* @returns The current cycles balance of the canister.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
getCyclesBalance(canisterId: Principal): Promise<bigint>;
/**
* Add cycles to the specified canister.
*
* @param canisterId The Principal of the canister to add cycles to.
* @param amount The amount of cycles to add.
* @returns The new cycle balance of the canister.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
addCycles(canisterId: Principal, amount: bigint): Promise<bigint>;
/**
* Set the stable memory of a given canister.
*
* @param canisterId The Principal of the canister to set the stable memory of.
* @param stableMemory A blob containing the stable memory to set.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
setStableMemory(canisterId: Principal, stableMemory: Uint8Array): Promise<void>;
/**
* Get the stable memory of a given canister.
*
* @param canisterId The Principal of the canister to get the stable memory of.
* @returns A blob containing the canister's stable memory.
*
* @see [Principal](https://js.icp.build/core/latest/libs/principal/api/classes/principal/)
*
* @example
* ```ts
* 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();
* ```
*/
getStableMemory(canisterId: Principal): Promise<Uint8Array>;
/**
* Get all pending HTTPS Outcalls across all subnets on this
* PocketIC instance.
*
* @returns An array of pending HTTPS Outcalls.
*
* @example
* ```ts
* 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();
* ```
*/
getPendingHttpsOutcalls(): Promise<PendingHttpsOutcall[]>;
/**
* Mock a pending HTTPS Outcall.
*
* @param options Options for mocking the pending HTTPS Outcall, see {@link MockPendingHttpsOutcallOptions}.
*
* @example
* ```ts
* 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();
* ```
*/
mockPendingHttpsOutcall({ requestId, response, subnetId, additionalResponses, }: MockPendingHttpsOutcallOptions): Promise<void>;
}