@shopify/ui-extensions-tester 0.0.1-alpha.0 → 2026.4.0-rc.3

package/README.md

@@ -14,6 +14,7 @@ This testing library provides strongly typed mocks of the extension API--like th
 ## 📋 Recommendations
 
 - **TypeScript** — we recommend TypeScript to enforce API compliance against mock objects
+- **Node.js ≥ 22.0.0** and **TypeScript ≥ 5.2** — to use ([Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management))
 - **@testing-library/preact** — if your extension uses [Preact](https://preactjs.com/), we recommend installing [`@testing-library/preact`](https://preactjs.com/guide/v10/preact-testing-library/) for its `fireEvent` and `waitFor` helpers
 
 ## 📦 Installation
@@ -72,7 +73,7 @@ Your extension's own `package.json` (inside `extensions/my-extension/`) already
   "devDependencies": {
     "@shopify/ui-extensions-tester": "latest",
     "@testing-library/preact": "^3.2.0",
-    "typescript": "^5.0.0",
+    "typescript": "^5.2.0",
     "vitest": "^3.0.0"
   }
 }
@@ -144,7 +145,34 @@ The path must match the target you pass to `getExtension()`.
 
 ## 🏊‍♀️ Getting started
 
-Every test file follows the same pattern: create an extension harness, call `extension.setUp()` before each test, call `extension.tearDown()` after.
+Every test file follows the same pattern:
+create an extension harness, set it up before
+each test, and tear it down after.
+
+### Quick start with `using` (Node ≥ 22.0.0)
+
+If your runtime supports
+[Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management),
+use `setUpExtension` for zero-boilerplate
+setup and automatic teardown:
+
+```ts
+import {setUpExtension} from '@shopify/ui-extensions-tester';
+
+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
+});
+```
+
+### Classic setup
+
+Alternatively, create the harness once and
+manage the lifecycle with `beforeEach` /
+`afterEach`:
 
 ```ts
 import {getExtension} from '@shopify/ui-extensions-tester';
@@ -339,25 +367,31 @@ Each surface exports some helpers:
 
 Exports from `@shopify/ui-extensions-tester`:
 
-### `getExtension(target, options?)`
+### `setUpExtension(target, options?)`
+
+Sets up an extension for testing and returns a
+disposable object that supports automatic
+teardown with the `using` keyword:
+
+```ts
+test('example', async () => {
+  using extension = setUpExtension(
+    'purchase.checkout.block.render',
+  );
+  await extension.render();
+  // tearDown() called automatically
+});
+```
 
-Returns an extension test harness for the given target. It reads `shopify.extension.toml`, finds the module for the given target, and provides helpers to mock the environment and render the extension. It locates `shopify.extension.toml` by walking up from the calling test file's directory, and falls back to searching `extensions/` under the current working directory.
+It reads `shopify.extension.toml`, finds the module for the given target, and provides helpers to mock the environment and render the extension. It locates `shopify.extension.toml` by walking up from the calling test file's directory, and falls back to searching `extensions/` under the current working directory. Results are cached: calling `getExtension` twice with the same target and the same resolved TOML returns the same instance.
 
 | Option            | Type     | Default                       | Description                                                |
 | ----------------- | -------- | ----------------------------- | ---------------------------------------------------------- |
 | `configSearchDir` | `string` | calling test file's directory | Directory to start searching for `shopify.extension.toml`. |
 
-By default `getExtension` walks up from the test file's directory to find `shopify.extension.toml`.
-
-**Returns** an `Extension<T>` object with the following members:
+By default, it walks up from the test file's directory to find `shopify.extension.toml`.
 
-#### `extension.setUp()`
-
-Sets up an extension environment for testing. Creates a mock `shopify` global with some defaults.
-
-#### `extension.tearDown()`
-
-Tears down the extension environment. Resets the `shopify` global and clears `document.body`.
+**Returns** an `Extension` object with the following members:
 
 #### `extension.render()`
 
@@ -402,6 +436,22 @@ extension.navigation.currentEntry =
 
 Assigning to `extension.navigation` also updates `globalThis.navigation`, so extension code that calls `navigation.navigate()` directly will use the mock.
 
+### `getExtension(target, options?)`
+
+> ⚠️ Prefer [`setUpExtension`](#setupextensiontarget-options) on Node ≥ 22.0.0. Use `getExtension` only if your runtime does not support [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management).
+
+Accepts the same arguments as `setUpExtension`. You must call `extension.setUp()` and `extension.tearDown()` explicitly.
+
+**Returns** an `Extension` object with the following additional members:
+
+#### `extension.setUp()`
+
+Sets up an extension environment for testing. Creates a mock `shopify` global with some defaults.
+
+#### `extension.tearDown()`
+
+Tears down the extension environment. Resets the `shopify` global and clears `document.body`.
+
 ### `createNavigationHistoryEntry(options?)`
 
 Creates a [`NavigationHistoryEntry`](https://developer.mozilla.org/en-US/docs/Web/API/NavigationHistoryEntry) for mocking `navigation.currentEntry` or other navigation values.

package/admin.esnext

@@ -0,0 +1 @@
+export * from "./build/esnext/admin/index.esnext";

package/admin.js

@@ -0,0 +1 @@
+module.exports = require("./build/cjs/admin/index.js");

package/admin.mjs

@@ -0,0 +1 @@
+export * from "./build/esm/admin/index.mjs";

package/build/cjs/_virtual/_rollupPluginBabelHelpers.js

@@ -0,0 +1,15 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+function _classPrivateFieldLooseBase(e, t) {
+  if (!{}.hasOwnProperty.call(e, t)) throw new TypeError("attempted to use private field on non-instance");
+  return e;
+}
+var id = 0;
+function _classPrivateFieldLooseKey(e) {
+  return "__private_" + id++ + "_" + e;
+}
+
+exports.classPrivateFieldLooseBase = _classPrivateFieldLooseBase;
+exports.classPrivateFieldLooseKey = _classPrivateFieldLooseKey;

package/build/cjs/admin/factories.js

@@ -0,0 +1,323 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var signals = require('../mocks/signals.js');
+var i18n = require('../mocks/i18n.js');
+var index = require('./index.js');
+
+/**
+ * Extracts the API type for a given admin extension target directly from the
+ * implementation's `ExtensionTargets` interface.
+ *
+ * Properties prefixed with `__` are private internal APIs and are excluded
+ * from the mock type so they cannot be relied on in test suites.
+ */
+
+// ---------------------------------------------------------------------------
+// Derived types — not directly exported from the admin surface barrel
+// ---------------------------------------------------------------------------
+
+function gidFromTarget(target) {
+  const resource = target.split('.')[1].replace(/-details$|-index$|-fulfilled-card$|-purchase-option$/, '').split('-').map(part => part.charAt(0).toUpperCase() + part.slice(1)).join('');
+  return `gid://shopify/${resource}/1`;
+}
+function createData(selected = []) {
+  return {
+    selected
+  };
+}
+function createNavigation() {
+  return {
+    navigate: () => {}
+  };
+}
+function createConfigApp() {
+  return {
+    launchUrl: 'https://mock-app.test/launch',
+    applicationUrl: 'https://mock-app.test'
+  };
+}
+function createMockStandardApi(target) {
+  return {
+    extension: {
+      target
+    },
+    auth: {
+      idToken: async () => 'mock-id-token'
+    },
+    i18n: i18n.createMockI18n(),
+    intents: {
+      launchUrl: undefined,
+      invoke: async () => ({
+        complete: Promise.resolve({
+          code: 'closed'
+        })
+      })
+    },
+    storage: index.createStorage(),
+    query: async () => ({
+      data: undefined
+    })
+  };
+}
+function createMockStandardRenderingApi(target) {
+  return {
+    ...createMockStandardApi(target),
+    resourcePicker: async () => undefined,
+    picker: async () => ({
+      selected: Promise.resolve(undefined)
+    })
+  };
+}
+function createMockBlockApi(target) {
+  return {
+    ...createMockStandardRenderingApi(target),
+    data: createData([{
+      id: gidFromTarget(target)
+    }]),
+    navigation: createNavigation()
+  };
+}
+function createMockActionApi(target) {
+  return {
+    ...createMockStandardRenderingApi(target),
+    close: () => {},
+    data: createData([{
+      id: gidFromTarget(target)
+    }])
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Group factory functions — each composes the correct API for a target group
+// ---------------------------------------------------------------------------
+
+function createPrintActionMock(target) {
+  return {
+    ...createMockStandardRenderingApi(target),
+    data: createData()
+  };
+}
+function createShouldRenderMock(target) {
+  return {
+    ...createMockStandardApi(target),
+    data: createData()
+  };
+}
+function createProductDetailsConfigMock(target) {
+  return {
+    ...createMockBlockApi(target),
+    data: {
+      selected: [],
+      product: {
+        id: 'gid://shopify/Product/1',
+        title: 'Mock Product',
+        handle: 'mock-product',
+        status: 'ACTIVE',
+        totalVariants: 1,
+        totalInventory: 10,
+        hasOnlyDefaultVariant: true,
+        onlineStoreUrl: 'https://mock-shop.myshopify.com/products/mock-product',
+        options: [],
+        productType: '',
+        productComponents: []
+      },
+      app: createConfigApp()
+    }
+  };
+}
+function createProductVariantDetailsConfigMock(target) {
+  return {
+    ...createMockBlockApi(target),
+    data: {
+      selected: [],
+      variant: {
+        id: 'gid://shopify/ProductVariant/1',
+        sku: 'MOCK-SKU',
+        barcode: '',
+        title: 'Default',
+        displayName: 'Mock Product - Default',
+        price: '0.00',
+        compareAtPrice: '0.00',
+        taxable: true,
+        taxCode: '',
+        weight: 0,
+        selectedOptions: [],
+        productVariantComponents: []
+      },
+      app: createConfigApp()
+    }
+  };
+}
+function createDiscountFunctionSettingsMock(target) {
+  return {
+    ...createMockStandardRenderingApi(target),
+    navigation: createNavigation(),
+    applyMetafieldChange: async () => index.createResult('applyMetafieldChange'),
+    data: {
+      id: 'gid://shopify/DiscountAutomaticApp/1',
+      metafields: []
+    },
+    discounts: {
+      discountClasses: signals.createReadonlySignalLike([]),
+      updateDiscountClasses: () => index.createResult('updateDiscountClasses'),
+      discountMethod: signals.createReadonlySignalLike('automatic')
+    }
+  };
+}
+function createOrderRoutingRuleMock(target) {
+  return {
+    ...createMockStandardRenderingApi(target),
+    applyMetafieldsChange: () => {},
+    data: {
+      rule: {
+        label: 'Mock Routing Rule',
+        description: 'A mock order routing rule',
+        id: 'gid://shopify/DeliveryCustomization/1',
+        metafields: []
+      }
+    }
+  };
+}
+function createValidationSettingsMock(target) {
+  return {
+    ...createMockStandardRenderingApi(target),
+    applyMetafieldChange: async () => index.createResult('applyMetafieldChange'),
+    data: {
+      validation: undefined,
+      shopifyFunction: {
+        id: 'gid://shopify/ShopifyFunction/1'
+      }
+    }
+  };
+}
+function createPurchaseOptionsCardMock(target) {
+  return {
+    ...createMockActionApi(target),
+    data: {
+      selected: []
+    }
+  };
+}
+function createCustomerSegmentTemplateMock(target) {
+  return {
+    ...createMockStandardApi(target)
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Factory map — TypeScript verifies each entry against ApiForTarget<K>
+// ---------------------------------------------------------------------------
+
+const adminMockFactories = {
+  // Runnable targets
+  'admin.customers.segmentation-templates.data': createCustomerSegmentTemplateMock,
+  'admin.app.tools.data': createMockStandardApi,
+  // Block targets
+  'admin.product-details.block.render': createMockBlockApi,
+  'admin.order-details.block.render': createMockBlockApi,
+  'admin.customer-details.block.render': createMockBlockApi,
+  'admin.collection-details.block.render': createMockBlockApi,
+  'admin.draft-order-details.block.render': createMockBlockApi,
+  'admin.abandoned-checkout-details.block.render': createMockBlockApi,
+  'admin.catalog-details.block.render': createMockBlockApi,
+  'admin.company-details.block.render': createMockBlockApi,
+  'admin.company-location-details.block.render': createMockBlockApi,
+  'admin.gift-card-details.block.render': createMockBlockApi,
+  'admin.product-variant-details.block.render': createMockBlockApi,
+  'admin.product-details.reorder.render': createMockBlockApi,
+  // Action targets
+  'admin.product-details.action.render': createMockActionApi,
+  'admin.catalog-details.action.render': createMockActionApi,
+  'admin.company-details.action.render': createMockActionApi,
+  'admin.gift-card-details.action.render': createMockActionApi,
+  'admin.order-details.action.render': createMockActionApi,
+  'admin.customer-details.action.render': createMockActionApi,
+  'admin.customer-segment-details.action.render': createMockActionApi,
+  'admin.product-index.action.render': createMockActionApi,
+  'admin.order-index.action.render': createMockActionApi,
+  'admin.customer-index.action.render': createMockActionApi,
+  'admin.discount-index.action.render': createMockActionApi,
+  'admin.collection-details.action.render': createMockActionApi,
+  'admin.collection-index.action.render': createMockActionApi,
+  'admin.abandoned-checkout-details.action.render': createMockActionApi,
+  'admin.product-variant-details.action.render': createMockActionApi,
+  'admin.draft-order-details.action.render': createMockActionApi,
+  'admin.draft-order-index.action.render': createMockActionApi,
+  'admin.discount-details.action.render': createMockActionApi,
+  'admin.order-fulfilled-card.action.render': createMockActionApi,
+  // Bulk action targets
+  'admin.product-index.selection-action.render': createMockActionApi,
+  'admin.order-index.selection-action.render': createMockActionApi,
+  'admin.customer-index.selection-action.render': createMockActionApi,
+  'admin.draft-order-index.selection-action.render': createMockActionApi,
+  'admin.discount-index.selection-action.render': createMockActionApi,
+  // Purchase options card action targets
+  'admin.product-purchase-option.action.render': createPurchaseOptionsCardMock,
+  'admin.product-variant-purchase-option.action.render': createPurchaseOptionsCardMock,
+  // Print action targets
+  'admin.order-details.print-action.render': createPrintActionMock,
+  'admin.product-details.print-action.render': createPrintActionMock,
+  'admin.order-index.selection-print-action.render': createPrintActionMock,
+  'admin.product-index.selection-print-action.render': createPrintActionMock,
+  // Configuration targets
+  'admin.product-details.configuration.render': createProductDetailsConfigMock,
+  'admin.product-variant-details.configuration.render': createProductVariantDetailsConfigMock,
+  // Function settings targets
+  'admin.discount-details.function-settings.render': createDiscountFunctionSettingsMock,
+  'admin.settings.internal-order-routing-rule.render': createOrderRoutingRuleMock,
+  'admin.settings.order-routing-rule.render': createOrderRoutingRuleMock,
+  'admin.settings.validation.render': createValidationSettingsMock,
+  // Should-render targets (action)
+  'admin.product-details.action.should-render': createShouldRenderMock,
+  'admin.catalog-details.action.should-render': createShouldRenderMock,
+  'admin.company-details.action.should-render': createShouldRenderMock,
+  'admin.gift-card-details.action.should-render': createShouldRenderMock,
+  'admin.order-details.action.should-render': createShouldRenderMock,
+  'admin.customer-details.action.should-render': createShouldRenderMock,
+  'admin.customer-segment-details.action.should-render': createShouldRenderMock,
+  'admin.product-index.action.should-render': createShouldRenderMock,
+  'admin.order-index.action.should-render': createShouldRenderMock,
+  'admin.customer-index.action.should-render': createShouldRenderMock,
+  'admin.discount-index.action.should-render': createShouldRenderMock,
+  'admin.collection-details.action.should-render': createShouldRenderMock,
+  'admin.collection-index.action.should-render': createShouldRenderMock,
+  'admin.abandoned-checkout-details.action.should-render': createShouldRenderMock,
+  'admin.product-variant-details.action.should-render': createShouldRenderMock,
+  'admin.draft-order-details.action.should-render': createShouldRenderMock,
+  'admin.draft-order-index.action.should-render': createShouldRenderMock,
+  'admin.discount-details.action.should-render': createShouldRenderMock,
+  'admin.order-fulfilled-card.action.should-render': createShouldRenderMock,
+  // Should-render targets (bulk action)
+  'admin.product-index.selection-action.should-render': createShouldRenderMock,
+  'admin.order-index.selection-action.should-render': createShouldRenderMock,
+  'admin.customer-index.selection-action.should-render': createShouldRenderMock,
+  'admin.draft-order-index.selection-action.should-render': createShouldRenderMock,
+  'admin.discount-index.selection-action.should-render': createShouldRenderMock,
+  // Should-render targets (print action)
+  'admin.order-details.print-action.should-render': createShouldRenderMock,
+  'admin.product-details.print-action.should-render': createShouldRenderMock,
+  'admin.order-index.selection-print-action.should-render': createShouldRenderMock,
+  'admin.product-index.selection-print-action.should-render': createShouldRenderMock
+};
+
+// ---------------------------------------------------------------------------
+// Main factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a complete mock API for an admin extension target.
+ * Each entry in the factory map is type-checked by TypeScript against
+ * the concrete API type for that target.
+ */
+function createMockAdminTargetApi(target) {
+  const factory = adminMockFactories[target];
+  if (!factory) {
+    throw new Error(`Unsupported admin target: "${target}". ` + 'Add an entry for this target in adminMockFactories.');
+  }
+  return factory(target);
+}
+
+exports.createMockAdminTargetApi = createMockAdminTargetApi;
+exports.gidFromTarget = gidFromTarget;

package/build/cjs/admin/index.js

@@ -0,0 +1,70 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Creates a mock `Storage` instance.
+ *
+ * Optionally accepts a `Record<string, unknown>` of initial entries.
+ */
+function createStorage(initialEntries) {
+  const store = new Map(initialEntries ? Object.entries(initialEntries) : []);
+  return {
+    set: async (key, value) => {
+      store.set(key, value);
+    },
+    setMany: async entries => {
+      for (const [entryKey, entryValue] of Object.entries(entries)) {
+        store.set(entryKey, entryValue);
+      }
+    },
+    get: async key => store.get(key),
+    getMany: async keys => keys.map(entry => store.get(entry)),
+    clear: async () => {
+      store.clear();
+    },
+    delete: async key => store.delete(key),
+    deleteMany: async keys => {
+      const result = {};
+      for (const entry of keys) {
+        result[entry] = store.delete(entry);
+      }
+      return result;
+    },
+    entries: async () => store.entries()
+  };
+}
+
+/**
+ * Maps each admin mutation API name to its result type.
+ */
+
+const adminMutationDefaults = {
+  applyMetafieldChange: () => ({
+    type: 'success'
+  }),
+  updateDiscountClasses: () => ({
+    success: true,
+    value: []
+  })
+};
+
+/**
+ * Creates a typed mock result for an admin mutation API.
+ *
+ * @param mutation - The mutation API name (e.g. `'applyMetafieldChange'`).
+ * @param result - Optional partial override merged with the default.
+ *
+ * @example
+ * createResult('applyMetafieldChange');
+ * createResult('updateDiscountClasses', {value: ['ORDER']});
+ */
+function createResult(mutation, result) {
+  return {
+    ...adminMutationDefaults[mutation](),
+    ...result
+  };
+}
+
+exports.createResult = createResult;
+exports.createStorage = createStorage;

package/build/cjs/api-version.js

@@ -0,0 +1,22 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * The API version supported by this version of the library.
+ *
+ * At build time, `"2026.4.0-rc.3"` is replaced by rollup with the
+ * raw NPM version string from package.json (e.g. `"2026.4.0-rc.1"`).
+ *
+ * When running from source (e.g. in tests), the placeholder is still
+ * present, so we fall back to reading package.json via require.
+ */
+
+const npmVersion = "2026.4.0-rc.3";
+function npmVersionToApiVersion(version) {
+  const [year, minor] = version.split('.');
+  return `${year}-${minor.padStart(2, '0')}`;
+}
+const API_VERSION = npmVersionToApiVersion(npmVersion);
+
+exports.API_VERSION = API_VERSION;