@shopify/ui-extensions-tester 2026.4.0-rc.2 → 2026.4.0

package/src/index.ts

@@ -32,21 +32,19 @@ type Mutable<T> = T extends (...args: any[]) => any
   ? {-readonly [K in keyof T]: Mutable<T[K]>}
   : T;
 
-interface Extension<T extends AnyExtensionTarget> {
-  /**
-   * Sets up an extension environment for testing.
-   *
-   * For example, it creates a mock `shopify` global with some defaults.
-   */
-  setUp(): void;
-
-  /**
-   * Tears down the extension environment.
-   *
-   * For example, it resets the `shopify` global and clears `document.body`.
-   */
-  tearDown(): void;
+/**
+ * `Symbol.dispose` for runtimes that support it, with a polyfill
+ * fallback so the library works on older Node versions too.
+ */
+export const SymbolDispose: typeof Symbol.dispose = ((Symbol as any).dispose ??
+  Symbol.for('Symbol.dispose')) as typeof Symbol.dispose;
 
+/**
+ * Members shared by both {@link ExtensionHarness} (returned by
+ * `getExtension`) and {@link DisposableExtensionHarness} (returned
+ * by `setUpExtension`).
+ */
+interface BaseExtensionHarness<T extends AnyExtensionTarget> {
   /**
    * Imports and executes the extension module's default export,
    * rendering the extension into `document.body`.
@@ -94,6 +92,163 @@ interface Extension<T extends AnyExtensionTarget> {
   navigation: Navigation;
 }
 
+/**
+ * Returned by `getExtension`.  The caller is responsible for calling
+ * `setUp()` before each test and `tearDown()` after.
+ */
+interface ExtensionHarness<T extends AnyExtensionTarget>
+  extends BaseExtensionHarness<T> {
+  /**
+   * Sets up an extension environment for testing.
+   *
+   * For example, it creates a mock `shopify` global with some defaults.
+   */
+  setUp(): void;
+
+  /**
+   * Tears down the extension environment.
+   *
+   * For example, it resets the `shopify` global and clears `document.body`.
+   */
+  tearDown(): void;
+}
+
+/**
+ * Returned by `setUpExtension`.  Already set up — tears down
+ * automatically via `Symbol.dispose` (the `using` keyword):
+ *
+ * ```ts
+ * using extension = setUpExtension('purchase.checkout.block.render');
+ * ```
+ */
+interface DisposableExtensionHarness<T extends AnyExtensionTarget>
+  extends BaseExtensionHarness<T> {
+  [SymbolDispose](): void;
+}
+
+class Extension<T extends AnyExtensionTarget> implements ExtensionHarness<T> {
+  #target: T;
+  #resolvedModule: string;
+  #modulePath: string;
+  #checkout: boolean;
+  #networkAccess: boolean;
+  #apiAccess: boolean;
+
+  #fetchImpl!: typeof globalThis.fetch;
+  #previousFetch: typeof globalThis.fetch | undefined;
+  #navigationImpl: Navigation = createMockNavigation();
+  #previousNavigation: any;
+
+  constructor(target: T, options?: {configSearchDir?: string}) {
+    const configSearchDir =
+      options?.configSearchDir ?? path.dirname(getCallerFile());
+    const tomlPath = findToml(configSearchDir);
+    const tomlDir = path.dirname(tomlPath);
+    const tomlContent = fs.readFileSync(tomlPath, 'utf-8');
+    validateApiVersion(tomlContent);
+    const modulePath = parseTargetModule(tomlContent, target);
+
+    this.#target = target;
+    this.#modulePath = modulePath;
+    this.#resolvedModule = path.resolve(tomlDir, modulePath);
+    this.#checkout = isCheckoutTarget(target);
+    this.#networkAccess = this.#checkout && parseNetworkAccess(tomlContent);
+    this.#apiAccess = this.#checkout && parseApiAccess(tomlContent);
+  }
+
+  setUp(): void {
+    installFetchPolyfills();
+
+    this.#fetchImpl =
+      this.#checkout && !this.#networkAccess && !this.#apiAccess
+        ? async () => {
+            // Checkout is the only surface that currently enforces
+            // fetch capabilities.
+            throw new Error(
+              'fetch() is not available. Add network_access = true or ' +
+                'api_access = true to [extensions.capabilities] in shopify.extension.toml.',
+            );
+          }
+        : async () => new Response();
+
+    this.#previousFetch = (globalThis as any).fetch;
+    this.#previousNavigation = (globalThis as any).navigation;
+    this.#navigationImpl = createMockNavigation();
+    (globalThis as any).shopify = deepWritableProxy(
+      createMockTargetApi(this.#target),
+    );
+    (globalThis as any).fetch = this.#fetchImpl;
+    (globalThis as any).navigation = this.#navigationImpl;
+  }
+
+  get shopify(): Mutable<ApiForTarget<T>> {
+    if (!(globalThis as any).shopify) {
+      throw new Error(
+        'You must call extension.setUp() before accessing extension.shopify.',
+      );
+    }
+    return (globalThis as any).shopify;
+  }
+
+  get fetch(): typeof globalThis.fetch {
+    return this.#fetchImpl;
+  }
+
+  set fetch(fn: typeof globalThis.fetch) {
+    this.#fetchImpl = fn;
+    (globalThis as any).fetch = fn;
+  }
+
+  get navigation() {
+    return this.#navigationImpl;
+  }
+
+  set navigation(obj: any) {
+    this.#navigationImpl = obj;
+    (globalThis as any).navigation = obj;
+  }
+
+  async render(): Promise<void> {
+    const mod = await import(this.#resolvedModule);
+    const renderFn = mod.default;
+    if (typeof renderFn !== 'function') {
+      throw new Error(
+        `Expected default export of ${
+          this.#modulePath
+        } to be a function, got ${typeof renderFn}`,
+      );
+    }
+    await renderFn();
+  }
+
+  tearDown(): void {
+    // Dynamically import preact to unmount cleanly without requiring
+    // the test file to depend on preact directly.
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const {render} = require('preact');
+      render(null, document.body);
+    } catch {
+      // Fallback if preact isn't available
+      document.body.innerHTML = '';
+    }
+    delete (globalThis as any).shopify;
+    if (this.#previousFetch === undefined) {
+      delete (globalThis as any).fetch;
+    } else {
+      (globalThis as any).fetch = this.#previousFetch;
+    }
+    if (this.#previousNavigation === undefined) {
+      delete (globalThis as any).navigation;
+    } else {
+      (globalThis as any).navigation = this.#previousNavigation;
+    }
+    uninstallFetchPolyfills();
+  }
+}
+
+const extensionCache = new Map<string, Extension<any>>();
+
 /**
  * Returns an extension test harness for the given target.
  *
@@ -112,114 +267,52 @@ interface Extension<T extends AnyExtensionTarget> {
 export function getExtension<T extends AnyExtensionTarget>(
   target: T,
   options?: {configSearchDir?: string},
-): Extension<T> {
-  const configSearchDir =
+): ExtensionHarness<T> {
+  const resolvedConfigSearchDir =
     options?.configSearchDir ?? path.dirname(getCallerFile());
-  const tomlPath = findToml(configSearchDir);
-  const tomlDir = path.dirname(tomlPath);
-  const tomlContent = fs.readFileSync(tomlPath, 'utf-8');
-  validateApiVersion(tomlContent);
-  const modulePath = parseTargetModule(tomlContent, target);
-  const resolvedModule = path.resolve(tomlDir, modulePath);
-  const checkout = isCheckoutTarget(target);
-  const networkAccess = checkout && parseNetworkAccess(tomlContent);
-  const apiAccess = checkout && parseApiAccess(tomlContent);
-
-  let fetchImpl: typeof globalThis.fetch;
-  let previousFetch: typeof globalThis.fetch | undefined;
-  let navigationImpl = createMockNavigation();
-  let previousNavigation: any;
-
-  const ext = {
-    setUp(): void {
-      installFetchPolyfills();
-
-      fetchImpl =
-        checkout && !networkAccess && !apiAccess
-          ? async () => {
-              // Checkout is the only surface that currently enforces
-              // fetch capabilities.
-              throw new Error(
-                'fetch() is not available. Add network_access = true or ' +
-                  'api_access = true to [extensions.capabilities] in shopify.extension.toml.',
-              );
-            }
-          : async () => new Response();
-
-      previousFetch = (globalThis as any).fetch;
-      previousNavigation = (globalThis as any).navigation;
-      (globalThis as any).shopify = deepWritableProxy(
-        createMockTargetApi(target),
-      );
-      (globalThis as any).fetch = fetchImpl;
-      (globalThis as any).navigation = navigationImpl;
-    },
-
-    get shopify(): any {
-      if (!(globalThis as any).shopify) {
-        throw new Error(
-          'You must call extension.setUp() before accessing extension.shopify.',
-        );
-      }
-      return (globalThis as any).shopify;
-    },
+  const tomlPath = findToml(resolvedConfigSearchDir);
+  const tomlMtimeMs = fs.statSync(tomlPath).mtimeMs;
+  const cacheKey = JSON.stringify([target, tomlPath, tomlMtimeMs]);
 
-    get fetch(): typeof globalThis.fetch {
-      return fetchImpl;
-    },
-
-    set fetch(fn: typeof globalThis.fetch) {
-      fetchImpl = fn;
-      (globalThis as any).fetch = fn;
-    },
-
-    get navigation() {
-      return navigationImpl;
-    },
-
-    set navigation(obj: any) {
-      navigationImpl = obj;
-      (globalThis as any).navigation = obj;
-    },
+  const cached = extensionCache.get(cacheKey);
+  if (cached) {
+    return cached as Extension<T>;
+  }
 
-    async render(): Promise<void> {
-      const mod = await import(resolvedModule);
-      const renderFn = mod.default;
-      if (typeof renderFn !== 'function') {
-        throw new Error(
-          `Expected default export of ${modulePath} to be a function, got ${typeof renderFn}`,
-        );
-      }
-      await renderFn();
-    },
+  const ext = new Extension<T>(target, {
+    configSearchDir: resolvedConfigSearchDir,
+  });
+  extensionCache.set(cacheKey, ext);
+  return ext;
+}
 
-    tearDown(): void {
-      // Dynamically import preact to unmount cleanly without requiring
-      // the test file to depend on preact directly.
-      try {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const {render} = require('preact');
-        render(null, document.body);
-      } catch {
-        // Fallback if preact isn't available
-        document.body.innerHTML = '';
-      }
-      delete (globalThis as any).shopify;
-      if (previousFetch === undefined) {
-        delete (globalThis as any).fetch;
-      } else {
-        (globalThis as any).fetch = previousFetch;
-      }
-      if (previousNavigation === undefined) {
-        delete (globalThis as any).navigation;
-      } else {
-        (globalThis as any).navigation = previousNavigation;
-      }
-      uninstallFetchPolyfills();
-    },
-  };
+/**
+ * Sets up an extension for testing and returns a disposable object
+ * that supports automatic teardown with the `using` keyword:
+ *
+ * ```ts
+ * test('rendering the extension', async () => {
+ *   using extension = setUpExtension(
+ *     'purchase.checkout.block.render',
+ *   );
+ *   await extension.render();
+ *   // tearDown() is called automatically at the end of the block
+ * });
+ * ```
+ *
+ * @param target - The extension target to mock.
+ * @param options - Optional configuration (same as {@link getExtension}).
+ */
+export function setUpExtension<T extends AnyExtensionTarget>(
+  target: T,
+  options?: {configSearchDir?: string},
+): DisposableExtensionHarness<T> {
+  const extension = getExtension(target, options);
+  extension.setUp();
 
-  return ext as Extension<T>;
+  return Object.assign(extension, {
+    [SymbolDispose]: () => extension.tearDown(),
+  }) as DisposableExtensionHarness<T>;
 }
 
 function validateApiVersion(toml: string): void {
@@ -301,8 +394,10 @@ function getCallerFile(): string {
     let callerFile = '';
 
     Error.prepareStackTrace = (_err, stack) => {
-      // stack[0] is getCallerFile, stack[1] is getExtension, stack[2] is the caller
-      for (let i = 2; i < stack.length; i++) {
+      // Walk the stack, skipping all frames that originate from this
+      // package file.  This works regardless of whether the caller is
+      // getExtension() or setUpExtension() → getExtension().
+      for (let i = 1; i < stack.length; i++) {
         const fileName = stack[i]!.getFileName();
         if (fileName && fileName !== thisPackageFilePath) {
           callerFile = fileName;

package/src/point-of-sale/factories.ts

@@ -14,6 +14,7 @@ import type {
   CashDrawerApi,
   ScannerSource,
   StorageApi,
+  ConnectivityApiContent,
   ConnectivityState,
   Cart,
   Session,
@@ -87,9 +88,15 @@ function createTransaction(): Transaction {
   } as Transaction;
 }
 
+function createConnectivityApiContent(): ConnectivityApiContent {
+  return {
+    current: createReadonlySignalLike(createConnectivityState()),
+  };
+}
+
 function createMockBaseEventData() {
   return {
-    connectivity: createConnectivityState(),
+    connectivity: createConnectivityApiContent(),
     device: {name: 'Mock POS Device', deviceId: 1, isTablet: false},
     locale: 'en-US',
     session: createSessionCurrentSession(),

package/src/tests/admin-factories.test.ts

@@ -1,4 +1,4 @@
-import {gidFromTarget} from '../admin/factories';
+import {createMockAdminTargetApi, gidFromTarget} from '../admin/factories';
 
 describe('gidFromTarget', () => {
   it.each([
@@ -29,3 +29,27 @@ describe('gidFromTarget', () => {
     expect(gidFromTarget(target)).toBe(expectedGid);
   });
 });
+
+describe('createMockAdminTargetApi', () => {
+  it('keeps app tools targets on the standard api', () => {
+    const api = createMockAdminTargetApi('admin.app.tools.data');
+
+    expect(api.extension.target).toBe('admin.app.tools.data');
+    expect(typeof api.query).toBe('function');
+    expect(api).not.toHaveProperty('tools');
+    expect(api).not.toHaveProperty('resourcePicker');
+  });
+
+  it('creates a standard rendering api for app intent targets', () => {
+    const api = createMockAdminTargetApi('admin.app.intent.render');
+
+    expect(api.extension.target).toBe('admin.app.intent.render');
+    expect(typeof api.resourcePicker).toBe('function');
+    expect(typeof api.picker).toBe('function');
+    expect(api).not.toHaveProperty('tools');
+    expect(typeof api.intents.response?.ok).toBe('function');
+    expect(typeof api.intents.response?.error).toBe('function');
+    expect(typeof api.intents.response?.closed).toBe('function');
+    expect(api).not.toHaveProperty('close');
+  });
+});

package/src/tests/getExtension.test.ts

@@ -1,7 +1,10 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
 import {getExtension} from '../index';
 
 import {API_VERSION} from '../api-version';
-import {createTestSandbox, type TestSandbox} from './helpers';
+import {createTestSandbox, makeToml, type TestSandbox} from './helpers';
 
 describe('getExtension', () => {
   let sandbox: TestSandbox;
@@ -164,4 +167,93 @@ describe('getExtension', () => {
       }).toThrow(/bogus.*does not exist/);
     });
   });
+
+  describe('caching', () => {
+    it('returns the same instance for the same target and configSearchDir', () => {
+      sandbox.placeToml();
+      const ext1 = getExtension('purchase.checkout.block.render', {
+        configSearchDir: sandbox.tempDir,
+      });
+      const ext2 = getExtension('purchase.checkout.block.render', {
+        configSearchDir: sandbox.tempDir,
+      });
+      expect(ext1).toBe(ext2);
+    });
+
+    it('returns different instances for the same target but different configSearchDir', () => {
+      sandbox.placeToml({inDir: 'root'});
+      sandbox.placeToml({inDir: 'subDir'});
+      const ext1 = getExtension('purchase.checkout.block.render', {
+        configSearchDir: sandbox.tempDir,
+      });
+      const ext2 = getExtension('purchase.checkout.block.render', {
+        configSearchDir: sandbox.tomlDirs.subDir,
+      });
+      expect(ext1).not.toBe(ext2);
+    });
+
+    it('returns the same instance when configSearchDir resolves to the same path', () => {
+      sandbox.placeToml();
+      const ext1 = getExtension('purchase.checkout.block.render', {
+        configSearchDir: sandbox.tempDir,
+      });
+      // Use a path with a redundant segment that resolves to the same directory
+      const ext2 = getExtension('purchase.checkout.block.render', {
+        configSearchDir: `${sandbox.tempDir}/sub/..`,
+      });
+      expect(ext1).toBe(ext2);
+    });
+
+    it('returns the same instance when configSearchDir is omitted and then explicitly set to the resolved default', () => {
+      sandbox.placeToml();
+      // When configSearchDir is omitted, it defaults to path.dirname(getCallerFile()).
+      // If we then call with that same directory explicitly, we should get the same instance.
+      const callerDir = path.dirname(__filename);
+
+      // Place a toml in the caller's directory tree so both calls find it
+      const tomlPath = path.join(callerDir, 'shopify.extension.toml');
+      fs.writeFileSync(tomlPath, makeToml());
+
+      try {
+        const ext1 = getExtension('purchase.checkout.block.render');
+        const ext2 = getExtension('purchase.checkout.block.render', {
+          configSearchDir: callerDir,
+        });
+        expect(ext1).toBe(ext2);
+      } finally {
+        fs.unlinkSync(tomlPath);
+      }
+    });
+
+    it('returns different instances for different targets', () => {
+      sandbox.placeToml({
+        target: 'purchase.checkout.block.render',
+      });
+      const ext1 = getExtension('purchase.checkout.block.render', {
+        configSearchDir: sandbox.tempDir,
+      });
+
+      sandbox.placeToml({target: 'pos.home.tile.render'});
+      const ext2 = getExtension('pos.home.tile.render', {
+        configSearchDir: sandbox.tempDir,
+      });
+
+      expect(ext1).not.toBe(ext2);
+    });
+
+    it('returns a new instance when the config file changes on disk', () => {
+      sandbox.placeToml();
+      const ext1 = getExtension('purchase.checkout.block.render', {
+        configSearchDir: sandbox.tempDir,
+      });
+
+      // Rewrite the toml — the resolved config file has changed
+      sandbox.placeToml();
+      const ext2 = getExtension('purchase.checkout.block.render', {
+        configSearchDir: sandbox.tempDir,
+      });
+
+      expect(ext1).not.toBe(ext2);
+    });
+  });
 });

package/src/tests/setUpExtension.test.ts

@@ -0,0 +1,52 @@
+import {setUpExtension, SymbolDispose} from '../index';
+
+import {createTestSandbox, type TestSandbox} from './helpers';
+
+describe('setUpExtension', () => {
+  let sandbox: TestSandbox;
+
+  beforeEach(() => {
+    sandbox = createTestSandbox();
+    sandbox.placeToml();
+  });
+
+  afterEach(() => {
+    sandbox.destroy();
+  });
+
+  it('calls setUp and returns a ready extension', () => {
+    const extension = setUpExtension('purchase.checkout.block.render', {
+      configSearchDir: sandbox.tempDir,
+    });
+    // shopify global should be available without calling setUp manually
+    expect(extension.shopify).toBeDefined();
+    expect(extension.shopify.extension.apiVersion).toBeDefined();
+  });
+
+  it('tears down when Symbol.dispose is called', () => {
+    const extension = setUpExtension('purchase.checkout.block.render', {
+      configSearchDir: sandbox.tempDir,
+    });
+    expect((globalThis as any).shopify).toBeDefined();
+    extension[SymbolDispose]();
+    expect((globalThis as any).shopify).toBeUndefined();
+  });
+
+  it('supports repeated setUp/tearDown cycles via setUpExtension', () => {
+    // First cycle
+    const ext1 = setUpExtension('purchase.checkout.block.render', {
+      configSearchDir: sandbox.tempDir,
+    });
+    expect((globalThis as any).shopify).toBeDefined();
+    ext1[SymbolDispose]();
+    expect((globalThis as any).shopify).toBeUndefined();
+
+    // Second cycle (reuses cached Extension)
+    const ext2 = setUpExtension('purchase.checkout.block.render', {
+      configSearchDir: sandbox.tempDir,
+    });
+    expect((globalThis as any).shopify).toBeDefined();
+    ext2[SymbolDispose]();
+    expect((globalThis as any).shopify).toBeUndefined();
+  });
+});