Shopify Functions WASM Testing Helpers

A JavaScript library that provides helpers for testing Shopify Functions WASM (WebAssembly) modules. This library provides utilities for loading fixtures, validating test assets, building functions, and running functions.

Installation

npm install @shopify/shopify-function-test-helpers

Or with pnpm:

pnpm add @shopify/shopify-function-test-helpers

Usage

Complete Test Example

For a full test suite that runs multiple fixtures using getFunctionInfo:

import path from "path";
import fs from "fs";
import {
  buildFunction,
  getFunctionInfo,
  loadFixture,
  runFunction,
  validateTestAssets,
  loadSchema,
  loadInputQuery,
} from "@shopify/shopify-function-test-helpers";

describe("Function Tests", () => {
  let schema;
  let functionDir;
  let functionInfo;

  beforeAll(async () => {
    functionDir = path.dirname(__dirname);
    await buildFunction(functionDir);

    // Get function information from Shopify CLI
    functionInfo = await getFunctionInfo(functionDir);

    // Load schema
    schema = await loadSchema(functionInfo.schemaPath);
  }, 20000);

  const fixturesDir = path.join(__dirname, "fixtures");
  const fixtureFiles = fs
    .readdirSync(fixturesDir)
    .filter((file) => file.endsWith(".json"))
    .map((file) => path.join(fixturesDir, file));

  fixtureFiles.forEach((fixtureFile) => {
    test(\`runs \${path.basename(fixtureFile)}\`, async () => {
      const fixture = await loadFixture(fixtureFile);

      // Get the correct input query for this fixture's target
      const targetInputQueryPath = functionInfo.targeting[fixture.target].inputQueryPath;
      const inputQueryAST = await loadInputQuery(targetInputQueryPath);

      // Validate test assets
      const validationResult = await validateTestAssets({
        schema,
        fixture,
        inputQueryAST,
      });

      expect(validationResult.inputQuery.errors).toHaveLength(0);
      expect(validationResult.inputFixture.errors).toHaveLength(0);
      expect(validationResult.outputFixture.errors).toHaveLength(0);

      // Run the function
      const runResult = await runFunction(
        fixture,
        functionInfo.functionRunnerPath,
        functionInfo.wasmPath,
        targetInputQueryPath,
        functionInfo.schemaPath
      );

      expect(runResult.error).toBeNull();
      expect(runResult.result.output).toEqual(fixture.expectedOutput);
    }, 10000);
  });
});

API Reference

Core Functions

• buildFunction - Build a Shopify function using the Shopify CLI
• getFunctionInfo - Get function information from Shopify CLI (paths, targets, etc.)
• loadFixture - Load a test fixture file
• loadSchema - Load a GraphQL schema from a file
• loadInputQuery - Load and parse a GraphQL input query
• validateTestAssets - Validate test assets (input query, fixture input/output, query-fixture match)
• runFunction - Run a Shopify function

See wasm-testing-helpers.ts for all exported types.

Development

Running Tests

Building

pnpm build

Linting

# Run linter
pnpm lint

# Fix linting issues
pnpm lint:fix

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

Create a tarball from a package

pnpm build
pnpm pack

This creates a .tgz file that can be installed in other projects:

{
  "devDependencies": {
    "@shopify/shopify-function-test-helpers": "file:../path/to/shopify-shopify-function-test-helpers-0.0.1.tgz"
  }
}

CI/CD

This project includes a comprehensive CI pipeline that runs on every push and pull request:

• Lint & Type-check: Ensures code quality and type safety
• Tests: Runs on multiple OS (Ubuntu, Windows, macOS) and Node versions (18.x, 20.x, 22.x)
• Build: Verifies the TypeScript compilation and creates the package

The CI configuration can be found in .github/workflows/ci.yml.

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Run the test suite (pnpm test)
6. Run the linter (pnpm lint)
7. Submit a pull request

For more details, see the test examples in this repository.