Test and debug Shopify Functions
- Users that have
checkout.liquid
customizations need to upgrade to Shopify Extensions in Checkout to use Function APIs. - Stores on any plan can use public apps that are distributed through the Shopify App Store and contain functions. Only stores on a Shopify Plus plan can use custom apps that contain Shopify Function APIs.
- Some Shopify Functions capabilities are available only to stores on a Shopify Plus plan. See Shopify Function APIs for details.
This guide describes recommended practices for testing and debugging when you are developing functions. Depending on your needs, you will use some combination of testing on Shopify, local execution, and unit tests.
Anchor to Testing on your development storeTesting on your development store
Testing your function on Shopify is a form of exploratory testing and the best way to confirm the function's expected behavior when it's used in a store.
When you run app dev
, Shopify CLI streams execution logs for your functions to your terminal, and writes details of the function execution input, output, and more to your filesystem. You can use the production-like function input values for other testing methods.
The app logs
command can also be used to stream logs for a development store. This command provides additional capabilities such as log filtering and JSON output.
Additionally, all function runs for development stores are logged in your Partner Dashboard. Manual steps are required on the store to trigger the function.
Anchor to Test your function on a development storeTest your function on a development store
- If you're developing a function in a language other than JavaScript or TypeScript, ensure you have configured
build.watch
in your function extension configuration.
-
Use the Shopify CLI
dev
command to start app preview:Terminal
shopify app devYou can keep the preview running as you work on your function. When you make changes to a watched file, Shopify CLI rebuilds your function and updates the function extension's drafts, so you can immediately test your changes.
-
Follow the CLI prompts to preview your app, and install it on your development store.
-
Enable the function and test it on your development store.
The steps that you need to follow to test your function depend on the function API that you're implementing. Refer to the Shopify Functions use case tutorials for details.
-
Add debugging logs to your function by writing to
eprintln!
in Rust,console.log
in JavaScript, orSTDERR
in other languages.CautionYou should always remove debugging logs before deploying and releasing your function.
-
When your function executes, review your debug logs in the
app dev
output. -
To review execution details, either click
Open log file
in the terminal output, or navigate to the output file path, depending on your terminal's capabilities.InfoWindows Terminal users can enable hyperlinks in Shopify CLI by setting the
FORCE_HYPERLINK=1
environment variable. -
To stream detailed logs for a single function, open a new terminal window and run
app logs
with the--source
argument:Streaming filtered logs
shopify app logs --source extensions.<function_handle>InfoYou can list log sources for your app with the
app logs sources
command.
Anchor to Execute the function locally using Shopify CLIExecute the function locally using Shopify CLI
Shopify CLI can mimic production execution of your function's WebAssembly module. This allows for faster local testing of function output, measuring your function against function performance restrictions. You can use this for local or automated integration tests in WebAssembly and to measure function performance.
The app function replay
command quickly executes the function using input from a previously logged function execution, and re-executes as your make changes to your code. The app function run
command can be used to perform a single function execution using a provided JSON input, so you can test function logic locally for known or logged input values. You can pass in any JSON input.
You can use the --json
argument of app function run
to get function measurements and output as JSON. This output can be used in automated testing and scripts.
Anchor to Replay a function locallyReplay a function locally
-
In the output of
app dev
, copy the 6-character log file identifier for the function execution which you wish to replay. For example,9f1f0e
. -
Open a separate terminal window and
cd
to your function extension folder. -
Use the
--log
argument withapp function replay
to specify the execution to run:Replay the function execution
shopify app function replay --log <log_file_identifier>InfoIf you don't have a log file identifier, you can use
app function replay
without this argument and select from a list of recent executions. -
After your function has the desired output, you can re-test on your development store.
If you're still running
app dev
, then your changes should already be available for testing on Shopify.
Anchor to Writing unit tests for functionsWriting unit tests for functions
We recommend implementing automated testing during development based on known use cases.
Writing unit tests allows you to validate your function logic repeatedly as your code evolves. Unit tests are also useful for debugging, because they enable step debugging using the native tooling of your development stack.
For examples, refer to some sample apps.
Unit tests don't run in WebAssembly, which in rare cases might cause different results than what's found in production.
Anchor to Write unit tests for functionsWrite unit tests for functions
You can retrieve a valid input JSON result for your input query from the log files output by app dev
, the output of the app logs
command, function run logs in your Partner Dashboard, or by constructing your own mock input. You can use this JSON to write tests which test your function as a single unit.
The recommended tool for writing unit tests depends on your choice of programming language for your function:
- For Rust, the
shopify_function
crate provides arun_function_with_input
utility method to simplify unit testing withcargo test
. View an example. - For JavaScript or TypeScript, we recommend Vitest. Input JSON can be used directly in your JavaScript code to execute the function. View an example.
For complex functions, you might design your code in a way that allows you to break up your tests into multiple units.
Anchor to Debugging functions in productionDebugging functions in production
For production stores, all function runs are visible in your Partner Dashboard, but details are only available for runs that have been shared by users. If your function execution is failing, or if your function is not behaving as intended, you should request that the user share those logs. You can also reproduce the issue in a development store, or one of the local testing options.