Add a testing library for ui-extensions

[kumar303]

This adds a new ui-extensions-tester library, built during Hack Days (internal Shopify link).

All stacks

• 🥞 ui-extensions-tester package setup <-- you are here
• 🥞 A complete mock checkout API
• 🥞 A complete mock point-of-sale API
• 🥞 A complete mock customer-account API
• 🥞 A complete mock Admin API

👁️ How to review this PR

• 📖 Read the developer-facing documentation
• See one of the stacks above to view surface-specific mocks

Example

Here's what it looks like so far in something like your-app/extensions/your-ui-extension/tests/Extension.test.ts:

import {expect, test, beforeEach, afterEach} from 'vitest';
import {setUpExtension} from '@shopify/ui-extensions-tester';

// This reads from ../shopify.extension.toml
const extension = getExtension('purchase.checkout.block.render');

beforeEach(() => {
  extension.setUp();
});

afterEach(() => {
  extension.tearDown();
});

test('renders an Enter button', async () => {
  await extension.render();
  const button = extension.querySelector('s-button');
  expect(button!.textContent).toEqual('Enter');
});

More complete example: checkout-basic-testing-example/tests/Checkout.test.ts

---

Run it like this after checking out the branch for this PR:

yarn build
pushd examples/testing/checkout-basic-testing-example
npm install
npm test

🎩

To try it in a standalone app, you have to install a pre-built package: shopify-ui-extensions-tester-v2026.4.0-rc.1.tgz. This is because /snapit doesn't work before there's at least one public release.

Add it to a package.json file like:

"@shopify/ui-extensions-tester": "file:../shopify-ui-extensions-tester-v2026.4.0-rc.1.tgz"

[kumar303]

• Create mocks for the entire Admin extension API #3914
• Create mocks for the entire Customer Account extension API #3905
• Create mocks for the entire point-of-sale extension API #3904
• Create mocks for the entire checkout extension API #3902
• Add a testing library for ui-extensions #3899 👈 (View in Graphite)
• 2026-04-rc

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cpeddecord]

nit: naming. Random thoughts without much merit:

• ui-extensions-testing-library - similar to React Testing Library
• ui-extensions-test- shorter for no good reason

[kumar303]

/snapit

[vividviolet]

This is amazing! I have a few questions/suggestions

[vividviolet]

Looks great! Thanks for addressing all the feedback. This is good to merge - I just have a few questions that could be addressed if needed in follow up prs

[vividviolet]

This means we'd have to do do a new version of the test library for every library release even though most of the code remains the same. I do see the value in making it simple for developers though. We might want to automate this somehow

[kumar303]

Yes, we'd need to release ui-extensions-tester alongside ui-extensions but if no changes are needed then the version bump would happen automatically. It gets set in a build step.

[vividviolet]

How do we write tests to work with changing signals then?

[kumar303]

Since preact is the default, I think most extensions could be tested in a functional style. In other words, the mock shopify object won't have working signals but I don't think that matters.

To illustrate:

Let's say your extension has a button to change cart quantities and it also subscribes to line items. You wouldn't need the subscription to be fully functional. You could just test it in two steps:

// test that the button works
const mock = vi.fn().mockResolvedValue(
  createResult('applyCartLineChange');
);
extension.shopify.applyCartLineChange = mock;

await extension.render();
const button = document.body.querySelector('s-button');
fireEvent('click', button);
// Make sure the button changes the quantity
await waitFor(() => {
  expect(mock).toHaveBeenCalledWith(...);
});

...

// test that the extension renders the lines
const line = createLineItem();
// This essentially simulates a subscription update:
extension.shopify.lines = [line];

await extension.render();
const text = document.body.querySelector('s-text');
// Make sure the line's quantity was rendered:
expect(text.textContent).toContain(line.quantity);

This testing style assumes the shopify API fully works as specified -- I think that assumption is fine.

[kumar303]

Thanks for calling this out, Trish. I documented the suggested pattern to use for this.

[vividviolet]

Can you clarify why we need to do this? Tests shouldn't mutate the toml so why do we need to copy these tests to their own directory and clone the toml?

[kumar303]

This is just for the internal ui-extensions-tester test suite. Developers would never use this.

It's necessary because some of the tests need to work with different TOML files to simulate different configurations. The fixtures getting copied here are just for defining an extension that can be imported and executed. The fixtures don't include a TOML file.

The first approach I tried was to write a local TOML file before each test but I started seeing flakiness. It worked better when creating a unique TOML file per test.

[jamesvidler]

I ran into a snag with the error ReferenceError: __filename is not defined when running the tests, so I had to add the following to my vitetest.config

export default defineConfig({
  esbuild: {
    jsx: "automatic",
    jsxImportSource: "preact",
  },
  test: {
    environment: "jsdom",
//NEEDED TO ADD THIS, or a I got an error ReferenceError: __filename is not defined when running the tests
    server: {
      deps: {
        inline: ["@shopify/ui-extensions-tester"],
      },
    },
  },
});

It looks like we've patched that now, but I wasn't able to get the updated tgz package to relfect the changes.

I'm comfortable approving and we can test again once the package is publicly released and fix forward if neccessary or update the docs.