@commerce-klaus/vitest-sfcc

Cartridge-aware SFCC runtime and dependency mocking for Vitest.

Highlights

• Resolves dw/*, */, ~/, cartridge aliases, relative modules, and module.superModule
• Infers cartridge order from configuration, environment, jsconfig, or site.xml
• Filters test cartridge paths through central architecture assignments
• Provides typed, inspectable SFCC globals and focused runtime modules and harnesses
• Loads effective Custom API operations from api.json and OAS metadata
• Loads effective hooks from project metadata with typed invocation for known Salesforce hooks
• Replaces module dependencies without proxyquire
• Exposes runtime APIs and types through @commerce-klaus/vitest-sfcc/runtime

When to use this package

Use this package when cartridge code must run in Vitest. It includes SFCC module resolution, CommonJS transformation, platform-module fallbacks, dependency mocking, and test harnesses.

Use @commerce-klaus/vite-plugin-sfcc-modules only when another Vite-based tool needs cartridge-aware module resolution without the test runtime. You do not need to install or configure that plugin alongside vitest-sfcc.

Install

pnpm add -D @commerce-klaus/vitest-sfcc vitest

npm install -D @commerce-klaus/vitest-sfcc vitest

yarn add -D @commerce-klaus/vitest-sfcc vitest

vp install -D @commerce-klaus/vitest-sfcc vitest

Usage

import sfccVitest from "@commerce-klaus/vitest-sfcc"
import { defineConfig } from "vite-plus"

export default defineConfig({
  plugins: [
    sfccVitest({
      basePath: "./cartridges",
      cartridgePath: ["app_custom", "app_storefront_base"],
    }),
  ],
})

Register a dependency replacement before dynamically importing the subject:

import { getSfccRuntime } from "@commerce-klaus/vitest-sfcc"

getSfccRuntime().mock("*/cartridge/scripts/provider", providerMock)
const subject = await import("../cartridge/scripts/subject.js")

Runtime-only APIs and types are also available from the lightweight subpath:

import { resetSfccRuntime, type SfccModule } from "@commerce-klaus/vitest-sfcc/runtime"

Load the implementation selected by Custom API metadata and cartridge precedence:

import { loadSfccCustomApi } from "@commerce-klaus/vitest-sfcc"

const api = await loadSfccCustomApi("products", "getProduct")
const result = await api.invoke({
  pathParameters: { productId: "sample-product" },
})

Load and invoke the implementation selected by hooks.json and cartridge precedence:

import { loadSfccHook } from "@commerce-klaus/vitest-sfcc"

const hook = await loadSfccHook("app.payment.authorize")
const result = hook.call("authorize", "payment-1")

Consumer projects only need to install @commerce-klaus/vitest-sfcc; its framework-independent runtime remains an internal dependency.

Documentation

See the complete configuration and testing reference.

License

MIT