feat(pic): support overriding the PocketIC binary path

docs/src/content/docs/guides/running-tests.mdx

@@ -4,6 +4,24 @@ sidebar:
   order: 5
 ---
 
+## Configuring the server binary
+
+By default, the PocketIC server binary downloaded when installing `@dfinity/pic` is used. A different binary can be provided using the `binPath` option, for example:
+
+```ts
+const pic = 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:
+
+```shell
+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

packages/pic/postinstall.mjs

@@ -85,4 +85,4 @@ async function downloadPicBinary() {
   chmodSync(TARGET_PATH, 0o700);
 }
 
-downloadPicBinary();
+await downloadPicBinary();

packages/pic/src/error.ts

@@ -34,7 +34,7 @@ export class BinNotFoundError extends Error {
 
   constructor(picBinPath: string) {
     super(
-      `Could not find the PocketIC binary. The PocketIC binary could not be found at ${picBinPath}. Please try installing @dfinity/pic again.`,
+      `Could not find the PocketIC binary at ${picBinPath}. If the path was provided via the binPath option or the POCKET_IC_BIN environment variable, please check that it points to an existing binary. Otherwise, please try installing @dfinity/pic again.`,
     );
   }
 }

packages/pic/src/pocket-ic-server-types.ts

@@ -11,4 +11,11 @@ export interface StartServerOptions {
    * Whether to pipe the canister logs to the parent process's stderr.
    */
   showCanisterLogs?: boolean;
+
+  /**
+   * Path to the PocketIC server binary.
+   * Defaults to the `POCKET_IC_BIN` environment variable if set,
+   * otherwise the binary downloaded by this package's install script.
+   */
+  binPath?: string;
 }

packages/pic/src/pocket-ic-server.ts

@@ -63,7 +63,7 @@ export class PocketIcServer {
   public static async start(
     options: StartServerOptions = {},
   ): Promise<PocketIcServer> {
-    const binPath = this.getBinPath();
+    const binPath = this.getBinPath(options);
     await this.assertBinExists(binPath);
 
     const pid = process.ppid;
@@ -145,8 +145,12 @@ export class PocketIcServer {
     });
   }
 
-  private static getBinPath(): string {
-    return resolve(__dirname, '..', 'pocket-ic');
+  private static getBinPath(options: StartServerOptions): string {
+    return (
+      options.binPath ||
+      process.env.POCKET_IC_BIN ||
+      resolve(__dirname, '..', 'pocket-ic')
+    );
   }
 
   private static async assertBinExists(binPath: string): Promise<void> {

packages/pic/tests/src/pocket-ic-server.spec.ts

@@ -0,0 +1,36 @@
+import { PocketIcServer } from '../../src';
+import { BinNotFoundError } from '../../src/error';
+
+describe('PocketIcServer', () => {
+  const originalPocketIcBin = process.env.POCKET_IC_BIN;
+
+  afterEach(() => {
+    if (originalPocketIcBin === undefined) {
+      delete process.env.POCKET_IC_BIN;
+    } else {
+      process.env.POCKET_IC_BIN = originalPocketIcBin;
+    }
+  });
+
+  it('should use the binary from the binPath option', async () => {
+    await expect(
+      PocketIcServer.start({ binPath: '/non-existent/bin-path/pocket-ic' }),
+    ).rejects.toThrow(new BinNotFoundError('/non-existent/bin-path/pocket-ic'));
+  });
+
+  it('should use the binary from the POCKET_IC_BIN environment variable', async () => {
+    process.env.POCKET_IC_BIN = '/non-existent/env-path/pocket-ic';
+
+    await expect(PocketIcServer.start()).rejects.toThrow(
+      new BinNotFoundError('/non-existent/env-path/pocket-ic'),
+    );
+  });
+
+  it('should prefer the binPath option over the POCKET_IC_BIN environment variable', async () => {
+    process.env.POCKET_IC_BIN = '/non-existent/env-path/pocket-ic';
+
+    await expect(
+      PocketIcServer.start({ binPath: '/non-existent/bin-path/pocket-ic' }),
+    ).rejects.toThrow(new BinNotFoundError('/non-existent/bin-path/pocket-ic'));
+  });
+});