feat: add logging support

nathanosdev · nathanosdev · commit 71d109bd7ea7 · 2024-04-21T04:00:44.000+02:00
diff --git a/docs/docs/guides/02-using-jest.md b/docs/docs/guides/02-using-jest.md
@@ -85,6 +85,7 @@ const config: Config = {
   testEnvironment: 'node',
   globalSetup: '<rootDir>/global-setup.ts',
   globalTeardown: '<rootDir>/global-teardown.ts',
+  testTimeout: 30_000,
 };
 
 export default config;
diff --git a/docs/docs/guides/03-using-vitest.md b/docs/docs/guides/03-using-vitest.md
@@ -108,6 +108,7 @@ export default defineConfig({
   test: {
     root: 'examples/counter/tests',
     globalSetup: './global-setup.ts',
+    testTimeout: 30_000,
   },
 });
 ```
diff --git a/examples/clock/src/main.mo b/examples/clock/src/main.mo
@@ -1,12 +1,14 @@
 import Time "mo:base/Time";
 import { now } = "mo:base/Time";
 import { setTimer; recurringTimer } = "mo:base/Timer";
+import Debug "mo:base/Debug";
 
 actor Clock {
   private type Time = Time.Time;
   private stable var time : Time = 0;
 
   public query func get() : async Time {
+    Debug.print("Getting current time...");
     return time / 1_000_000;
   };
 
diff --git a/examples/clock/tests/global-setup.ts b/examples/clock/tests/global-setup.ts
@@ -1,7 +1,10 @@
 import { PocketIcServer } from '@hadronous/pic';
 
 module.exports = async function (): Promise<void> {
-  const pic = await PocketIcServer.start();
+  const pic = await PocketIcServer.start({
+    pipeStdout: false,
+    pipeStderr: true,
+  });
   const url = pic.getUrl();
 
   process.env.PIC_URL = url;
diff --git a/examples/clock/tests/jest.config.ts b/examples/clock/tests/jest.config.ts
@@ -6,6 +6,7 @@ const config: Config = {
   testEnvironment: 'node',
   globalSetup: '<rootDir>/global-setup.ts',
   globalTeardown: '<rootDir>/global-teardown.ts',
+  testTimeout: 30_000,
 };
 
 export default config;
diff --git a/examples/counter/tests/vitest.config.ts b/examples/counter/tests/vitest.config.ts
@@ -4,5 +4,6 @@ export default defineConfig({
   test: {
     root: 'examples/counter/tests',
     globalSetup: './global-setup.ts',
+    testTimeout: 30_000,
   },
 });
diff --git a/examples/multicanister/tests/jest.config.ts b/examples/multicanister/tests/jest.config.ts
@@ -6,6 +6,7 @@ const config: Config = {
   testEnvironment: 'node',
   globalSetup: '<rootDir>/global-setup.ts',
   globalTeardown: '<rootDir>/global-teardown.ts',
+  testTimeout: 30_000,
 };
 
 export default config;
diff --git a/examples/nns_proxy/tests/jest.config.ts b/examples/nns_proxy/tests/jest.config.ts
@@ -6,6 +6,7 @@ const config: Config = {
   testEnvironment: 'node',
   globalSetup: '<rootDir>/global-setup.ts',
   globalTeardown: '<rootDir>/global-teardown.ts',
+  testTimeout: 30_000,
 };
 
 export default config;
diff --git a/examples/todo/tests/jest.config.ts b/examples/todo/tests/jest.config.ts
@@ -6,6 +6,7 @@ const config: Config = {
   testEnvironment: 'node',
   globalSetup: '<rootDir>/global-setup.ts',
   globalTeardown: '<rootDir>/global-teardown.ts',
+  testTimeout: 30_000,
 };
 
 export default config;
diff --git a/packages/pic/src/identity.ts b/packages/pic/src/identity.ts
@@ -22,18 +22,22 @@ import { Ed25519KeyIdentity } from '@dfinity/identity';
  *
  * @example
  * ```ts
- * import { PocketIc, createIdentity } from '@hadronous/pic';
+ * import { PocketIc, PocketIcServer, createIdentity } from '@hadronous/pic';
  * import { AnonymousIdentity } from '@dfinity/agent';
  * import { _SERVICE, idlFactory } from '../declarations';
  *
  * const wasmPath = resolve('..', '..', 'canister.wasm');
  *
- * const pic = await PocketIc.create();
+ * const picServer = await PocketIcServer.create();
+ * const pic = await PocketIc.create(picServer.getUrl());
  * const fixture = await pic.setupCanister<_SERVICE>(idlFactory, wasmPath);
  * const { actor } = fixture;
  *
  * const bob = createIdentity('SuperSecretSeedPhraseForBob');
  * actor.setIdentity(bob);
+ *
+ * await pic.tearDown();
+ * await picServer.stop();
  * ```
  */
 export function createIdentity(seedPhrase: string): Identity {
@@ -67,18 +71,22 @@ function generateMnemonic(): string {
  *
  * @example
  * ```ts
- * import { PocketIc, generateRandomIdentity } from '@hadronous/pic';
+ * import { PocketIc, PocketIcServer, generateRandomIdentity } from '@hadronous/pic';
  * import { AnonymousIdentity } from '@dfinity/agent';
  * import { _SERVICE, idlFactory } from '../declarations';
  *
  * const wasmPath = resolve('..', '..', 'canister.wasm');
  *
- * const pic = await PocketIc.create();
+ * const picServer = await PocketIcServer.create();
+ * const pic = await PocketIc.create(picServer.getUrl());
  * const fixture = await pic.setupCanister<_SERVICE>(idlFactory, wasmPath);
  * const { actor } = fixture;
  *
  * const bob = generateRandomIdentity();
  * actor.setIdentity(bob);
+ *
+ * await pic.tearDown();
+ * await picServer.stop();
  * ```
  */
 export function generateRandomIdentity(): Identity {
diff --git a/packages/pic/src/index.ts b/packages/pic/src/index.ts
@@ -11,3 +11,4 @@ export type {
   UpgradeCanisterOptions,
 } from './pocket-ic-types';
 export { PocketIcServer } from './pocket-ic-server';
+export { StartServerOptions as ServerStartOptions } from './pocket-ic-server-types';
diff --git a/packages/pic/src/pocket-ic-server-types.ts b/packages/pic/src/pocket-ic-server-types.ts
@@ -0,0 +1,14 @@
+/**
+ * Options for starting a PocketIC server.
+ */
+export interface StartServerOptions {
+  /**
+   * Whether to pipe the server's stdout to the parent process's stdout.
+   */
+  pipeStdout?: boolean;
+
+  /**
+   * Whether to pipe the server's stderr to the parent process's stderr.
+   */
+  pipeStderr?: boolean;
+}
diff --git a/packages/pic/src/pocket-ic-server.ts b/packages/pic/src/pocket-ic-server.ts
@@ -15,7 +15,34 @@ import {
   isArm,
   isDarwin,
 } from './util';
-
+import { StartServerOptions } from './pocket-ic-server-types';
+
+/**
+ * This class represents the main PocketIC server.
+ * It is responsible for maintaining the lifecycle of the server process.
+ * See {@link PocketIc} for details on the client to use with this server.
+ *
+ * @category API
+ *
+ * @example
+ * ```ts
+ * import { PocketIc, PocketIcServer } from '@hadronous/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();
+ * ```
+ */
 export class PocketIcServer {
   private readonly url: string;
 
@@ -26,7 +53,15 @@ export class PocketIcServer {
     this.url = `http://127.0.0.1:${portNumber}`;
   }
 
-  public static async start(): Promise<PocketIcServer> {
+  /**
+   * Start a new PocketIC server.
+   *
+   * @param options Options for starting the server.
+   * @returns An instance of the PocketIC server.
+   */
+  public static async start(
+    options: StartServerOptions = {},
+  ): Promise<PocketIcServer> {
     const binPath = this.getBinPath();
     await this.assertBinExists(binPath);
 
@@ -35,9 +70,15 @@ export class PocketIcServer {
     const portFilePath = tmpFile(`${picFilePrefix}.port`);
     const readyFilePath = tmpFile(`${picFilePrefix}.ready`);
 
-    const serverProcess = spawn(binPath, ['--pid', pid.toString()], {
-      stdio: 'ignore',
-    });
+    const serverProcess = spawn(binPath, ['--pid', pid.toString()]);
+
+    if (options.pipeStdout) {
+      serverProcess.stdout.pipe(process.stdout);
+    }
+
+    if (options.pipeStderr) {
+      serverProcess.stderr.pipe(process.stderr);
+    }
 
     serverProcess.on('error', error => {
       if (isArm() && isDarwin()) {
@@ -61,10 +102,20 @@ export class PocketIcServer {
     });
   }
 
+  /**
+   * Get the URL of the server.
+   *
+   * @returns The URL of the server.
+   */
   public getUrl(): string {
     return this.url;
   }
 
+  /**
+   * Stop the server.
+   *
+   * @returns A promise that resolves when the server has stopped.
+   */
   public async stop(): Promise<void> {
     return new Promise((resolve, reject) => {
       this.serverProcess.on('exit', () => {
diff --git a/packages/pic/src/pocket-ic.ts b/packages/pic/src/pocket-ic.ts
