---
title: Test and debug Shopify Functions
description: Recommendations on how to test and debug when developing functions.
source_url:
  html: 'https://shopify.dev/docs/apps/build/functions/test-debug-functions'
  md: 'https://shopify.dev/docs/apps/build/functions/test-debug-functions.md'
---

ExpandOn this page

* [Testing on your dev store](https://shopify.dev/docs/apps/build/functions/test-debug-functions.md#testing-on-your-dev-store)
* [Execute the function locally using Shopify CLI](https://shopify.dev/docs/apps/build/functions/test-debug-functions.md#execute-the-function-locally-using-shopify-cli)
* [Writing unit tests for functions](https://shopify.dev/docs/apps/build/functions/test-debug-functions.md#writing-unit-tests-for-functions)
* [Writing Wasm integration tests for functions](https://shopify.dev/docs/apps/build/functions/test-debug-functions.md#writing-wasm-integration-tests-for-functions)
* [Debugging functions in production](https://shopify.dev/docs/apps/build/functions/test-debug-functions.md#debugging-functions-in-production)

# Test and debug Shopify Functions

Functions availability

* 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](https://help.shopify.com/manual/intro-to-shopify/pricing-plans/plans-features/shopify-plus-plan) can use [custom apps](https://help.shopify.com/manual/apps/app-types/custom-apps) that contain [Shopify Function APIs](https://shopify.dev/docs/api/functions).
* Some Shopify Functions capabilities are available only to stores on a [Shopify Plus plan](https://help.shopify.com/manual/intro-to-shopify/pricing-plans/plans-features/shopify-plus-plan). See [Shopify Function APIs](https://shopify.dev/docs/api/functions#availability-of-shopify-functions) for details.

This guide describes recommended practices for testing and debugging when you're developing functions. Depending on your needs, you'll use a combination of testing on Shopify, local execution, and unit tests.

***

## Testing on your dev 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`](https://shopify.dev/docs/api/shopify-cli/app/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`](https://shopify.dev/docs/api/shopify-cli/app/app-logs) command can also be used to stream logs for a dev store. This command provides additional capabilities such as log filtering and JSON output.

Additionally, all function runs for dev stores are logged in your [Dev Dashboard](https://dev.shopify.com/dashboard/). Manual steps are required on the store to trigger the function.

### Test your function on a dev store

1. 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](https://shopify.dev/docs/api/functions/configuration#properties).

1) Use the Shopify CLI [`dev` command](https://shopify.dev/docs/api/shopify-cli/app/app-dev) to start the dev preview:

   ## Terminal

   ```terminal
   shopify app dev
   ```

   You 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.

2) Follow the CLI prompts to preview your app on your development store.

1. Enable the function and test it on your dev 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](https://shopify.dev/docs/apps/build/functions#getting-started) for details.

2. Add debugging logs to your function by writing to `log!` in Rust, `console.log` in JavaScript, or `shopify_function_log_new_utf8_str` in other languages.

   Caution

   You should always remove debugging logs before deploying and releasing your function.

3. When your function executes, review your debug logs in the `app dev` output.

4. To review execution details, click **Open log file** in the terminal output, or navigate to the output file path, depending on your terminal's capabilities.

   Info

   Windows Terminal users can enable hyperlinks in Shopify CLI by setting the `FORCE_HYPERLINK=1` environment variable.

5. To stream detailed logs for a single function, open a new terminal window and run `app logs` with the `--source` argument:

   ## Streaming filtered logs

   ```terminal
   shopify app logs --source extensions.<function_handle>
   ```

   Info

   You can list log sources for your app with the [`app logs sources`](https://shopify.dev/docs/api/shopify-cli/app/app-logs-sources) command.

***

## Execute 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](https://shopify.dev/docs/api/functions/current#other-limitations). You can use this for local or automated integration tests in WebAssembly and to measure function performance.

The [`app function replay`](https://shopify.dev/docs/api/shopify-cli/app/app-function-replay) command quickly executes the function using input from a previously logged function execution, and re-executes as you make changes to your code. The [`app function run`](https://shopify.dev/docs/api/shopify-cli/app/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.

Info

You can use the [`--json` argument](https://shopify.dev/docs/api/shopify-cli/app/app-function-run) of `app function run` to get function measurements and output as JSON. This output can be used in automated testing and scripts.

### Replay a function locally

1. In the output of `app dev`, copy the six-character log file identifier for the function execution which you wish to replay. For example, `9f1f0e`.

2. Open a separate terminal window and `cd` to your function extension folder.

3. Use the `--log` argument with `app function replay` to specify the execution to run:

   ## Replay the function execution

   ```terminal
   shopify app function replay --log <log_file_identifier>
   ```

   Info

   If 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.

4. After your function has the desired output, you can [re-test on your dev store](#test-your-function-on-a-development-store).

   If you're still running `app dev`, then your changes should already be available for testing on Shopify.

***

## Writing 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](https://github.com/Shopify/function-examples/tree/main/sample-apps).

Caution

Unit tests don't run in WebAssembly, which in rare cases might cause different results than what's found in production.

### Write unit tests for functions

You can retrieve a valid input JSON result for your [input query](https://shopify.dev/docs/api/functions/current#input) from the [log files output by `app dev`](#test-your-function-on-a-development-store), the output of the [`app logs`](https://shopify.dev/docs/api/shopify-cli/app/app-logs) command, function run logs in your [Dev Dashboard](https://dev.shopify.com/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](https://shopify.dev/docs/apps/build/functions/programming-languages) for your function:

* For Rust, the `shopify_function` crate provides a [`run_function_with_input`](https://docs.rs/shopify_function/latest/shopify_function/fn.run_function_with_input.html) utility method to simplify unit testing with `cargo test`. [View an example](https://github.com/Shopify/function-examples/blob/main/sample-apps/discounts/extensions/product-discount-rust/src/run.rs#L77-L199).
* For JavaScript or TypeScript, we recommend [Vitest](https://vitest.dev/). Input JSON can be used directly in your JavaScript code to execute the function. [View an example](https://github.com/Shopify/function-examples/blob/main/sample-apps/discounts/extensions/product-discount-js/src/run.test.js).

For complex functions, you might design your code in a way that allows you to break up your tests into multiple units.

***

## Writing Wasm integration tests for functions

Use integration tests to validate the behaviour of your function's [WebAssembly](https://shopify.dev/docs/apps/build/functions/programming-languages/webassembly-for-functions) module. The tests allow you to validate that the compiled binary in production continues to produce the expected output for a given input.

When you generate a function from a template, it contains a `tests/` directory with a default integration test file and fixture:

* `default.test.js` - The test file that compiles your function and runs it against fixtures.
* `fixtures/log.json` - A default test fixture with sample input and expected output.

The integration tests use the [`@shopify/shopify-function-test-helpers`](https://www.npmjs.com/package/@shopify/shopify-function-test-helpers) package, which provides convenient helper methods:

* `buildFunction()` - Compiles your function source code to WebAssembly.
* `loadFixture()` - Loads and parses fixture JSON files.
* `validateTestAssets()` - Validates input queries and fixtures against your function's GraphQL schema.
* `runFunction()` - Executes your compiled WebAssembly module with test inputs.

Note

For a complete list of available methods, refer to the [README](https://github.com/Shopify/shopify-function-test-helpers?tab=readme-ov-file).

To run the integration tests from your function directory:

## Run integration tests

```terminal
npm test
```

Info

You might need to run `npm install` in your app root first to install the test dependencies defined in the function's `package.json`.

The default test compiles your function to WebAssembly, then executes it using the test fixtures in `tests/fixtures/`. The test ensures that:

1. Your function compiles successfully to WebAssembly.
2. Your input query is valid for your schema.
3. Each of your fixtures has a valid input and output.
4. The execution of your WebAssembly module produces the expected output for the given input.

### Add additional test fixtures

You can add more test cases by creating additional fixture files in the `tests/fixtures/` directory. The test automatically discovers and runs all `.json` files in this directory.

#### Fixture file structure

Each fixture file represents a single test case and must contain the following fields:

* **`export`** - The WebAssembly export function name for your function. This value depends on your function type and is defined in your function's configuration.
* **`target`** - The function API target (for example, `cart.transform.run`, `payment.customization.run`). This determines which GraphQL schema is used to validate your fixture.
* **`input`** - The input data for your function test, matching your function's input query GraphQL schema. This is the data your function receives when it executes.
* **`output`** - The expected output from your function. The test validates that your function produces this exact output when given the corresponding input.

#### Create a fixture from logged function execution

The easiest way to create test fixtures is to use real function execution data.

**Using automatically generated log files:**

When you run [`app dev`](#test-your-function-on-a-development-store), Shopify CLI automatically creates log files for each function execution on your dev store in your app's `.shopify/logs` directory. You can drag and drop these log files directly into your `tests/fixtures/` folder to use them as test fixtures.

**Manually creating fixtures:**

Alternatively, you can manually create fixtures from logged execution data:

1. View past executions in your [Dev Dashboard](https://dev.shopify.com/dashboard/).

2. From the logged execution, copy the **input** and **output** JSON.

3. Create a new file in `tests/fixtures/` (for example, `tests/fixtures/my-test-case.json`).

4. Structure your fixture with the required fields:

   ```json
   {
     "payload": {
       "export": "your-export-name",
       "target": "your.target.name",
       "input": {
         // Paste the input JSON from your log here
       },
       "output": {
         // Paste the expected output JSON from your log here
       }
     }
   }
   ```

   Info

   The `export` and `target` values are specific to your function type. You can find these values in your function's [`shopify.extension.toml` configuration file](https://shopify.dev/docs/api/functions/configuration).

5. Run `npm test` to execute your new test case.

***

## Debugging functions in production

For production stores, all function runs are visible in your Dev Dashboard, but details are available only for runs that have been [shared by users](https://shopify.dev/docs/apps/build/functions/monitoring-and-errors). If your function execution is failing, or if your function isn't behaving as intended, then you should request that the user share those logs. You can also reproduce the issue in a dev store, or one of the local testing options.

***

* [Testing on your dev store](https://shopify.dev/docs/apps/build/functions/test-debug-functions.md#testing-on-your-dev-store)
* [Execute the function locally using Shopify CLI](https://shopify.dev/docs/apps/build/functions/test-debug-functions.md#execute-the-function-locally-using-shopify-cli)
* [Writing unit tests for functions](https://shopify.dev/docs/apps/build/functions/test-debug-functions.md#writing-unit-tests-for-functions)
* [Writing Wasm integration tests for functions](https://shopify.dev/docs/apps/build/functions/test-debug-functions.md#writing-wasm-integration-tests-for-functions)
* [Debugging functions in production](https://shopify.dev/docs/apps/build/functions/test-debug-functions.md#debugging-functions-in-production)