Running tests

Configuring the server binary

By default, the PocketIC server binary downloaded by the @dfinity/pic install script is used, which requires allowing the install script. A different binary can be provided using the binPath option, for example:

const picServer = await PocketIcServer.start({
  binPath: '/path/to/pocket-ic',
});

Alternatively, the POCKET_IC_BIN environment variable can be set to the path of the binary, for example:

POCKET_IC_BIN=/path/to/pocket-ic npm test

The binPath option takes precedence over the POCKET_IC_BIN environment variable.

Configuring logging

Canister logs

Logs for canisters can be configured when running the PocketIC server using the showCanisterLogs option, for example:

const picServer = await PocketIcServer.start({
  showCanisterLogs: true,
});

To assert on a canister’s logs in a test, fetch its log records with fetchCanisterLogs. By default, only the canister’s controllers can read its logs; other principals need the canister’s log visibility to allow them:

const pic = await PocketIc.create(picServer.getUrl());
// set up a canister controlled by `controller`...

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

Records can be narrowed to an index or timestamp range with filter, for example filter: { type: 'byIdx', start: 0n, end: 10n }.

Server logs

Logs for the PocketIC server can be configured by setting the POCKET_IC_LOG_DIR and POCKET_IC_LOG_DIR_LEVELS environment variables.

The POCKET_IC_LOG_DIR variable specifies the directory where the logs will be stored. It accepts any valid relative, or absolute directory path.

The POCKET_IC_LOG_DIR_LEVELS variable specifies the log levels. It accepts any of the following string values: trace, debug, info, warn, or error.

For example:

POCKET_IC_LOG_DIR=./logs POCKET_IC_LOG_DIR_LEVELS=trace npm test

It’s also possible to set individual log levels for different modules, for examples:

POCKET_IC_LOG_DIR=./logs POCKET_IC_LOG_DIR_LEVELS=pocket_ic_server=trace,tower_http=info,axum::rejection=info npm test

Runtime logs

Logs for the IC runtime can be configured when running the PocketIC server using the showRuntimeLogs option, for example:

const picServer = await PocketIcServer.start({
  showRuntimeLogs: true,
});