Test checkout UI extensions

Testing checkout UI extensions in different scenarios is a UX guideline. The purpose is to recreate merchant and customer experiences and ensure that extensions behave as desired.

Anchor to Test locallyTest locally

The custom field and product offer tutorials show you how to start generating and previewing extensions. Previewing UI extensions locally is different when using static and block extension targets.

Anchor to Static extension targetsStatic extension targets

When you're using a static extension target, the UI extension automatically renders in a chosen location.

Anchor to Block extension targetsBlock extension targets

When you're using a block extension target, merchants can place the UI extension in any of the supported placements on the page.

To preview a block extension in each supported placement, append ?placement-reference={name} to the checkout URL that's outputted by Shopify CLI. For example, ?placement-reference=DELIVERY1.

Use the following placement references to test each supported placement:

Anchor to Placement referencesPlacement references

Here are all the placement references for each page.

Anchor to CheckoutCheckout

Block extension target: purchase.checkout.block.render

Placement references: WALLETS1, INFORMATION1, INFORMATION2, INFORMATION3, DELIVERY1, DELIVERY2, PAYMENT1, PAYMENT1, PAYMENT3, PAYMENT4

Anchor to Thank youThank you

Block extension target: purchase.thank-you.block.render

Placement references: ORDER_SUMMARY1, ORDER_SUMMARY2, ORDER_SUMMARY3, ORDER_SUMMARY4, ORDER_STATUS1, ORDER_STATUS2, ORDER_STATUS3

Anchor to Order StatusOrder Status

Block extension target: customer-account.order-status.block.render

Placement references: ORDER_SUMMARY1, ORDER_SUMMARY2, ORDER_SUMMARY3, ORDER_SUMMARY4, ORDER_STATUS1, ORDER_STATUS2, ORDER_STATUS3

Anchor to Test with Shop PayTest with Shop Pay

To use extensions in Shop Pay, you need to activate Shopify Payments on your development store and enable test mode. You can develop extensions locally in Shop Pay and preview published extensions.

Anchor to Step 1: Enable Shopify Payments in test modeStep 1: Enable Shopify Payments in test mode

For development stores, where you aren't accepting real payments, enable Shopify Payments.

1. From your Shopify admin, go to Settings > Payments.

2. Initiate the signup process by clicking Activate Shopify Payments.

3. Once on the signup page, click back to go to the payment settings page.

4. Follow the steps to enable test mode.

   Note

   To save changes, you require a valid Customer statement descriptor and Phone number.

Learn more about setting up Shopify payments.

Anchor to Step 2: Complete test orders in Shop PayStep 2: Complete test orders in Shop Pay

To complete test orders in Shop Pay, you'll need to create a Shop Pay account with a vaulted test card.

1. Create a guest checkout using a test card for the payment method. Use an email that doesn't have a Shop Pay Account attributed to it.

2. Click Save my information for a faster checkout and enter a valid phone number.

You should now have a new Shop Pay account with a vaulted test credit card that you can use to complete checkouts from Shop Pay.

Anchor to Test the extension in the checkout editorTest the extension in the checkout editor

After you've published your extension, you'll test the experience of Plus merchants who have installed your app.

In this step, you'll preview different placements for extensions using the checkout editor. Checkout UI extensions don't display in checkout until the merchant uses the checkout editor to add the app and place it in checkout.

1. From the Shopify admin click Settings > Checkout. Then click Customize checkout.

2. Use the dropdown list at the top of the page to navigate to the checkout step where you want to add your extension.

3. To activate your extension, click Add app block on the bottom left of the page, and select your extension from the list.

   If your extension doesn't appear in the list, then you need to enable a preview of your extension:

   1. In your Partner Dashboard, go to Apps.
   2. Click the name of your app.
   3. Click Extensions, and click the name of your extension.
   4. Click Enable.

4. Preview different placements for the extension by dragging and dropping the extension between the different targets. Test extension experiences in other checkout contexts like One-page checkout, Three-page checkout, and Shop Pay.

5. When you've chosen a placement, click Save.

Anchor to Three-page checkoutThree-page checkout

Three-page checkout is the default checkout context. To test your extension on three-page checkout, complete the following steps:

1. Open the Settings tab.
2. Under Checkout layout, click One-page checkout.
3. Click Three-page checkout.

Anchor to One-page checkoutOne-page checkout

To test your extension on one-page checkout, complete the following steps:

1. Open the Settings tab.
2. Under Checkout layout, click Three-page checkout.
3. Click One-page checkout.

Anchor to Shop PayShop Pay

To test your extension on Shop Pay, complete the following steps:

1. From checkout, click Add app block, and select your extension from the list.
2. Enable Include app in Shop Pay using the checkout behavior controls.
3. Click the cart icon in the editor header.
4. Click Preview Shop Pay from the list of options.

Anchor to Troubleshooting with source mapsTroubleshooting with source maps

Sometimes it can be useful to debug your extension on a merchant's shop in production. Your extension's code is bundled and minified and can be difficult to read, but you can use a sourcemap which will allow you to debug your extension with your source code.

Anchor to Find your sourcemapFind your sourcemap

If you're using Shopify CLI version 3.70.0 or higher, the command to deploy your extension will also produce a source map file for your extension on your local file system within your extension's project directory. Look for a dist folder within your extension's project directory.

Passing the verbose flag on the app deploy command will indicate the source map file's location.

Anchor to Link your sourcemap in developer toolsLink your sourcemap in developer tools

Now that you have your sourcemap, you'll need to link that to the extension code. The following instructions assume you are using the Google Chrome browser.

1. Open Chrome DevTools
2. Click on the Sources tab
3. Each extension has its own service worker with a human-readable name that includes the extension type, app name, and other identifying information. You'll need to expand the appropriate service worker and find your javascript bundle. It should be under the path:

4. Right-click within the script content window and select add sourcemap to link your sourcemap.

Anchor to Debugging with sourcemapsDebugging with sourcemaps

Once you've linked your sourcemap, you should see your source code in the developer tools and be able to add breakpoints and step through your code.

Anchor to Integrate sourcemaps with application monitoring toolsIntegrate sourcemaps with application monitoring tools

If you're using application monitoring tools like Sentry or BugSnag, you may be able to upload the source map file to de-obfuscate JavaScript stack traces. However, this is dependent on the tool you're using and is not officially supported at this time.

Anchor to Next stepsNext steps

• Learn how to deploy extensions to release changes to users.