How to Test your Theme Before Submitting to the Shopify Theme Store

When developing themes for the Shopify Theme Store, it's critical to test your project regularly to ensure required features are working as expected and to understand how your theme responds to different conditions. In fact, the quality assurance (QA) process can be the most important stage in your journey to launching a theme on the Shopify Theme Store. 

By setting up a robust testing environment, and establishing a frequent QA process, you can ensure that your theme is feature-complete and ready for use by Shopify merchants around the world. The more time you spend testing your theme and addressing usability issues, the more likely you are to experience a streamlined review.

A rigorous testing strategy also extends beyond the theme review process, and can reduce future support debt by preventing merchants from encountering usability issues when they adopt your theme. 

In this article we'll show you how to set up a development store especially for testing your theme, and how to populate it with products and store data that will help you identify potential issues in your theme. We'll also demonstrate techniques for testing mandatory features, as well as share tools that can be used to automate testing and evaluate your theme against our required benchmarks for accessibility and performance. 

Setting up a test environment

The first step in setting up a robust testing process will be creating a development store that you can populate with various products, menus, pages, and store data. It's important that the content you add to your development store has different characteristics that test the limits of how merchants will be using their store. This will help you identify where potential design issues are occurring and where elements of your theme may need to be fixed. 

"It's important that the content you add to your development store has different characteristics that test the limits of how merchants will be using their store."

Once you've created a development store from your Partner Dashboard, there are a number of ways you can populate your store with demo products. One option would be to import products to your development store using CSV files from our open GitHub repository, or you can use the Shopify CLI to generate products with the shopify populate command. The benefit of using the Shopify CLI to populate data is that you can choose what kind of data (products, customers or orders) as well as how many elements to generate.

Once you've populated the store with products, you should alter the individual settings of some products so you can observe how your theme responds when products have different characteristics. 

Here are some instances specific to products that you should test:

• Set up variants with different prices, so you can check that prices adjust dynamically when a variant is changed.
• Create a product with different options, where some of the variants are sold out and unavailable. To create unavailable variants, simply skip some of the option combinations. This will test that the ‘Add to cart’ button is disabled or replaced when a sold-out variant or an unavailable variant combination is selected. 
• Write long product names and long product descriptions (over 1000 characters), so you can ensure test renders correctly and doesn't interfere with other elements on the page.
• Add product images with various different aspect ratios, as well as PNG images to ensure all images display as expected.
• Upload different product media types, to ensure videos and 3D models are rendering correctly. Use our supplied samples for testing different product media types.
• Create discounts on products to ensure that the discounted price appears on the product page, and the cart page. 
• Products with 100 variants across three options.

Navigation is another critical area for testing, as there are a range of different possible configurations of menus that your theme will need to support. Here are some menu settings you can create in your development store that you should test:

• Add a main navigation menu with up to three levels of menu items, to test that drop down elements are working as expected, and don't interfere with other page elements.
• Add a menu with over 10 menu items to test that the header layout doesn't break. 
• Give menu items long names to verify that names remain clearly displayed.
• Create collections that contain a large number of products to ensure pagination is working correctly.

There are many other store elements that you should work into your QA testing process to ensure that your theme is displaying content as expected. Here are some examples of elements to test:

• Add a range of pages with long and short text content to check that text appears correctly for all pages.
• Use a range of images with different aspect ratios across blog articles, products, collections, and featured product sections. Wherever merchants can insert images, you should test that your theme is displaying them appropriately, regardless of the image aspect ratio. 
• Create customer accounts and check how customer pages and order details are appearing.
• Use Hatchful to create a logo and check how your theme responds to different logo sizes and ensure there's fallback text when no logo is available.
• Search keywords on your store and ensure that the search page returns different types of results (products, blogs, and pages) and check that results are not breaking the page layout.
• Follow the entire customer flow to test that any element that a merchant interacts with is working as expected. These include cart notes, filtering, contact forms, newsletters, and links.

Shopify as a platform is very flexible and allows merchants with many different requirements to showcase their store in a multitude of formats. When testing out your theme, consider any edge cases where merchants could be utilizing features in unusual ways to display content. By ensuring that your theme is robust enough to adapt to different store configurations you can set your theme up for success on the Shopify Theme Store.

You might also like: What it Takes to Build for Success on the Shopify Theme Store. 

Testing mandatory features 

In order to meet the varied needs of merchants there are a number of baseline features that all themes must support. All the mandatory features can be found in the Theme store requirements page, where you can find links to learn more about each feature. Shopify's source-available Dawn theme can also be used as a reference to see how each mandatory feature is implemented. 

Before you submit your theme for review, you should carry out a rigorous QA process to ensure all the mandatory features are working as expected. To display some features on your theme, you'll need to activate specific settings within your development store so that the feature is available to the online store. 

"Before you submit your theme for review, you should carry out a rigorous QA process to ensure all the mandatory features are working as expected."

In this section we'll highlight the features that require activating admin settings so that you're able to test mandatory features on your theme. 

Product media

Merchants are able to upload and associate a range of different media types to their products. You’ll need to support the following media types on your theme's product pages:

• Standard images
• 3D objects
• YouTube or Vimeo video links
• MP4 video files

To test different 3D models and videos you can download our supplied samples that contain various examples of all required product media. The product media feature is available to all merchants with any store configuration, so no settings need to be activated on your development store to enable product media. 

You should test your theme by adding these media objects into one product page to test edge cases, and analyse how the product behaves when all types of media exist on one product. Additionally you should test how the product media objects and page responds with keyboard control and focus states for accessibility, to ensure that your implementation of product media doesn't have a negative impact on accessibility. 

To test that 3D models are rendering correctly you should carry out the following:

• Add two 3D objects to a product.
• Users must be able to interact with the objects in a way that doesn't interfere with other elements on the page. 
• On mobile users must be able to interact with the objects and view them in AR. You should ensure that the “View in your space” button is present. 

To test that videos are rendering correctly you should carry out the following:

• If your theme has a video looping setting, make sure the setting works.
• Make sure the video sound stops when users navigate away from the video. 
• The main media must change to the selected variant image when users select a different variant. 
• Run accessibility tests on the page by manually navigating using keyboard control, as well as analyze how focus stages behave. 

You might also like: How to Use Product Media on Your Custom Shopify Themes.

Unit pricing

Merchants might sell products in specific quantities or measurements, so may need to display a price per unit for those products. Unit pricing allows price per unit to be displayed, but is only available for merchants in Germany. 

In order to test this feature your development store address needs to be set to a German address. Once your store address is set to a German address, you can follow the instructions in our help docs to set up unit pricing. 

To test unit pricing you should carry out the following:

• Select a unit price on a product with multiple variants to make sure the unit price changes dynamically on variant change. 
• Test on the collection page, product form (product page, and quick buy modal if applicable), and cart page, to ensure that the unit price appears. 

If the feature is implemented on your theme correctly you will see the unit price dynamically change when a different variant is selected. Unit pricing should be displayed on all instances where the price appears, including customer account orders, product lists, cart form, featured product section, and others. 

Selling plans

Selling plans represent different methods for how products can be sold on a Shopify store, for example when a merchant is selling a subscription product or service. You can learn more about how to implement the selling plan feature on your theme from our developer documentation.

Selling plans can only be created and applied to products by an app. This means you will need to install one of the new subscription apps that use the subscription APIs on your development store to test that selling plans are appearing correctly with your theme.

Additional requirements for selling plans:

• Your development store must be using Shopify Payments
• No Shopify Scripts should be published 
• There should be no checkout.liquid customizations
• Full list of eligibility requirements here

To add selling plans to the cart, you can use the cart AJAX APIs to add a variant ID with a selling_plan ID to the cart. Alternatively, you can add the following snippet to the product form that allows you to select a selling_plan:

To test selling plans you should carry out the following:

• Add a selling plan to a product via the specific subscription app you've installed on your development store.
• On the product page of your development store, you should see selling plan information appearing.
• The selling plan information must also be displayed on the cart and customer order page.

Pickup availability 

Shopify merchants have the option for customers to pick up their online orders at their retail store, curbside, or any location that they choose. When this feature is enabled customers can view information related to a merchants' store location on the product page. You can learn more about how to implement the pickup availability feature on your theme from our developer documentation.

As pickup availability is a native Shopify feature, you don’t need to install an app to activate this feature on your development store. Full instructions on how to activate pickup availability can be found on our help documentation, but here's a brief summary on how to set it up:

• Activate multi-origin shipping under Settings > Shipping and delivery.
• Add some demo locations under Settings > Locations.
• Navigate to Settings > Shipping and delivery to set up local pickup on the demo locations.
• Select a product in the admin and under the Inventory section, set up variant quantities for each test location.
• After this is all set up, the pickup availability information should show up on the product page. 

To test Pickup availability you should carry out the following:

• Create a product containing multiple variants with different pickup availability options, so you can test if the information changes dynamically when the variant changes.
• Customers need to be able to clearly see the store information. Make sure the information in the pop up/drawer isn’t being cut off or interfering with other elements on the page.

These are just some of the features that are required to be supported by your theme. You should ensure that you've performed a full round of QA based on all the theme store requirements before submitting or resubmitting your theme. 

Tools for testing

The best way to ensure your theme is highly performant, accessible, and works across required browsers is to build with best practices in mind from the offset. It's more difficult and time consuming to refactor problematic code at the end of a project than it is to write code that is correct in the beginning. 

"The best way to ensure your theme is highly performant, accessible, and works across required browsers is to build with best practices in mind from the offset."

However, you'll always need a way to evaluate your efforts and determine if your theme is meeting the benchmarks required for submission to the Shopify Theme Store. These testing techniques should be employed daily as part of your development workflow, to help you understand the impact of new changes you are introducing to your codebase, and allow you to identify opportunities for improvement. 

Tools for testing online store performance

Google's Lighthouse tool is what our review team use when they're determining the loading performance of your theme. To be accepted into the Shopify Theme Store, a theme must have a minimum average lighthouse performance score of 60 for mobile across the home page, product page, and collection page. 

You can run Lighthouse tests on your own development stores by generating a preview link and using this on Google's Pagespeed Insights. Because development stores are password protected, you will not be able to audit using the root myshopify.com URL. Preview links created from the admin however are publicly accessible without a password and can be used to audit different pages of your theme. 

For a holistic view of your theme's performance across different pages, you should run audits on the home page, product page, and collection page (using 10-25 products for a realistic result). It's recommended to run 10 times for each page to give a solid average as many factors can affect results (location, Internet speed, etc). The average across all pages should be over 60 on mobile. 

Additionally, we've released the Shopify Lighthouse CI GitHub Action to support developers who use a continuous integration (CI) process as part of their development workflow. When you use this GitHub action, your theme code will be uploaded to a benchmark shop and where a speed score is calculated. This will allow you to identify performance issues early, as you build your theme. 

To learn what techniques you can use to improve the performance of your theme, you should read our performance best practices for Shopify themes and performance benchmarking instructions on our developer documentation. 

Tools for testing accessibility

Accessibility should be baked into every aspect of your theme build as it's essential to providing an inclusive experience for both merchants and their customers. Meeting the Shopify Theme Store accessibility requirements extends beyond publishing your theme in our marketplace—you’ll also be providing your merchants and their shoppers with an improved experience.

We recently published a great article by Scott Vinkle on testing themes for accessibility, that will help you understand and meet the new accessibility requirements of the Shopify Theme Store. This blog post demonstrates a range of techniques for auditing objective and subjective accessibility issues, as well as how to perform audits on specific components of your theme. 

As with performance, the Shopify Theme review team use Lighthouse to determine how accessible your theme is. To be accepted into the Shopify Theme Store, a theme must have a minimum average Lighthouse accessibility score of 90 across the product, collection, and home page, for both desktop and mobile. 

By running Lighthouse accessibility tests on each individual page you can not only determine the accessibility score, but discover exactly what accessibility issues your theme may have. For example Lighthouse reports will highlight if form fields are missing a label association, or if color contrast issues are found.

Other tools for running accessibility audits include Accessibility Insights for Web which is a Chrome browser extension that allows you to easily run tests while you are working on your theme. Any developers who use VS Code can install the axe Accessibility Linter plugin which identifies markup issues that could lead to accessibility barriers in our theme files. 

Tools for testing browser compatibility

It's crucial that your theme allows merchants to access the same information and experience across different browsers and devices. The Shopify Theme Store requirements state that your theme should support the latest two releases of Safari, Chrome, Firefox, and Edge, for both Mac and PC, where available. 

One of the most reliable ways to test how your theme interacts with older browser versions, is through a service like BrowserStack, which emulates all versions of required browsers. It's also common for developers to stress-test their projects on legacy versions on Internet Explorer, which you can access through Microsoft's Virtual Machines tool. To learn more about cross-browser support, you can read our blog post on building for modern browsers. 

Regarding mobile devices, Chrome's DevTools can be used to emulate specific mobile devices and screen sizes, so this is a useful tool to form part of your integrated QA process. This will allow you to simulate the mobile user experience from your laptop or desktop, and introduce throttling to see how performance could be impacted when using fast or slow 3G internet speeds. 

Where possible however, you should test your theme manually on as many physical devices as possible. This will give you an authentic view into how your theme responds to touch events and target functions, so having access to an Android and an iOS device, using DevTools is highly recommended. 

Other tools for testing

There are a wide range of additional tools that can be utilized when evaluating your theme and ensuring it's providing the best experience to merchants and buyers. Here's a few others for your testing toolkit:

• Theme Check for analysing and correcting Liquid code errors is available both as a VS Code, and as part of the Shopify CLI.
• Facebook sharing debugger and Twitter card validator for testing OG tags are rendering correctly on social media. 
• The Disable Javascript Chrome DevTools feature for testing navigation and the product form without Javascript.
• Sometimes the best testing methods are with real people. Consider connecting with people outside of your organisation who would have fresh eyes and a fresh perspective to test your theme. 

You might also like: Tips for an Efficient Shopify Theme Review Process.

Testing for success

When testing your theme, it's worth employing a combination of sources to get a holistic view of where issues may arise, rather than relying on a single perspective. Establishing a robust and regular testing process will allow developers to see where bugs are appearing while building themes, and set your theme up for success on the Shopify Theme Store. 

Hopefully with the help of this article, testing your themes will be that much easier!