@sanity/cli-test

Provides test helpers for the Sanity CLI.

Quick Start

1. Set up vitest global setup

Add the cli-test vitest setup to your vitest.config.ts:

import {defineConfig} from 'vitest/config'

export default defineConfig({
  test: {
    globalSetup: ['@sanity/cli-test/vitest'],
  },
})

This will automatically copy and install dependencies for all bundled fixtures before tests run.

2. Use test fixtures in your tests

import {testFixture} from '@sanity/cli-test'
import {describe, test} from 'vitest'

describe('my test suite', () => {
  test('should work with basic-studio', async () => {
    const cwd = await testFixture('basic-studio')
    // The fixture is now available at `cwd` with dependencies installed
    // Tests that need built output should build explicitly:
    // await buildFixture(cwd)
  })
})

API

testFixture(fixtureName: string, options?: TestFixtureOptions): Promise<string>

Creates an isolated copy of a bundled fixture for testing. Returns the absolute path to the temporary directory containing the fixture.

Parameters:

• fixtureName - Name of the fixture to copy (e.g., 'basic-app', 'basic-studio')
• options.tempDir - Optional custom temp directory path (defaults to process.cwd()/tmp)

Returns: Absolute path to the temporary fixture directory

Available Fixtures:

• basic-app - Basic Sanity application
• basic-studio - Basic Sanity Studio
• multi-workspace-studio - Multi-workspace Sanity Studio
• worst-case-studio - Stress-test Sanity Studio

Example:

import {testFixture} from '@sanity/cli-test'

const cwd = await testFixture('basic-studio')
// Fixture is ready at `cwd` with dependencies installed
// Note: Fixtures are NOT built by default - tests should build if needed

setup(options?: SetupTestFixturesOptions): Promise<void>

Vitest global setup function that copies fixtures and installs dependencies. This is automatically called by vitest when using @sanity/cli-test/vitest in your globalSetup config.

Parameters:

• options.additionalFixtures - Glob patterns for additional fixture directories from your local repo to set up alongside the default bundled fixtures (e.g., ['fixtures/*', 'dev/*']). Only directories containing a package.json are included.
• options.tempDir - Custom temp directory path (defaults to process.cwd()/tmp)

Note: Fixtures are NOT built during setup. Tests that need built output should build explicitly.

Adding fixtures from your local repo:

If your repo has its own fixture directories that you want to test alongside the default bundled fixtures, use the additionalFixtures option to include them:

// vitest.setup.ts
import {setup as cliTestSetup, teardown} from '@sanity/cli-test/vitest'

export {teardown}

export async function setup(project) {
  return cliTestSetup(project, {
    additionalFixtures: ['fixtures/*', 'dev/*'],
  })
}

// vitest.config.ts
import {defineConfig} from 'vitest/config'

export default defineConfig({
  test: {
    globalSetup: ['vitest.setup.ts'],
  },
})

teardown(options?: TeardownTestFixturesOptions): Promise<void>

Vitest global teardown function that removes the temp directory. This is automatically called by vitest when using @sanity/cli-test/vitest.

Parameters:

• options.tempDir - Custom temp directory path (defaults to process.cwd()/tmp)

setupWorkerBuild(filePaths: string[]): Promise<void>

Utility function to compile TypeScript worker files (.worker.ts) to JavaScript for use in tests. Must be integrated into a custom vitest global setup file.

Parameters:

• filePaths - Array of paths to .worker.ts files to compile

Features:

• Compiles TypeScript to JavaScript using SWC for fast compilation
• Generates source maps for debugging
• Automatically watches for changes in watch mode (detects VITEST_WATCH=true or --watch flag)
• Handles files from both @sanity/cli and @sanity/cli-core packages

Note: This is a utility function, NOT automatically called. See the "Worker Files" section for integration examples.

Example:

// test/workerBuild.ts
import {setupWorkerBuild} from '@sanity/cli-test/vitest'
import {glob} from 'tinyglobby'

export async function setup() {
  const workerFiles = await glob('**/*.worker.ts', {
    ignore: ['**/node_modules/**', '**/dist/**'],
  })
  return setupWorkerBuild(workerFiles)
}

teardownWorkerBuild(): Promise<void>

Utility function to clean up worker build artifacts and close file watchers. Must be integrated into a custom vitest global setup file.

Features:

• Closes file watchers if in watch mode
• Deletes all compiled .js files that were generated from .worker.ts files
• Clears internal tracking of compiled files

Note: This is a utility function, NOT automatically called. See the "Worker Files" section for integration examples.

testCommand(command: Command, args?: string[])

Runs the given command with the given arguments and returns the output.

const {stdout} = await testCommand(DevCommand, ['--host', '0.0.0.0', '--port', '3000'])

mockApi(api: ApiClient)

Mocks the sanity/client calls.

mockApi({
  apiVersion: '2024-01-17',
  method: 'get',
  uri: '/users/me',
  query: {
    recordType: 'user',
  },
}).reply(200, {
  id: 'user-id',
  name: 'John Doe',
  email: 'john.doe@example.com',
})

How It Works

This package bundles pre-configured Sanity fixtures that can be used for testing. When you call testFixture():

1. It creates a unique temporary copy of the requested fixture
2. Symlinks the node_modules directory from the global setup version (for performance)
3. Returns the path to the isolated test directory

The fixtures work identically whether this package is used in a monorepo or installed from npm.

Building Fixtures

Fixtures are NOT built during global setup or when calling testFixture(). Tests that need built output should build explicitly:

import {exec} from 'node:child_process'
import {promisify} from 'node:util'

const execAsync = promisify(exec)

const cwd = await testFixture('basic-studio')
// Build the fixture before running tests that need it
await execAsync('npx sanity build --yes', {cwd})

Worker Files

Worker files (.worker.ts) are TypeScript files that run in separate threads or processes. This package provides utilities to compile these files for testing, but they must be integrated into a custom vitest global setup file.

Setting Up Worker Compilation

Step 1: Create a worker setup file (e.g., test/workerBuild.ts):

import {setupWorkerBuild, teardownWorkerBuild} from '@sanity/cli-test/vitest'
import {glob} from 'tinyglobby'

export async function setup() {
  // Find all .worker.ts files in your project
  const workerFiles = await glob('**/*.worker.ts', {
    cwd: process.cwd(),
    ignore: ['**/node_modules/**', '**/dist/**'],
  })

  return setupWorkerBuild(workerFiles)
}

export async function teardown() {
  return teardownWorkerBuild()
}

Step 2: Add to vitest config:

// vitest.config.ts
import {defineConfig} from 'vitest/config'

export default defineConfig({
  test: {
    globalSetup: [
      'test/workerBuild.ts', // Your worker setup
      '@sanity/cli-test/vitest', // Fixture setup
    ],
  },
})

Features:

• Compiles TypeScript to JavaScript using SWC for fast compilation
• Generates source maps for debugging
• Automatically watches for changes in watch mode (detects VITEST_WATCH=true or --watch flag)
• Cleans up compiled .js files after tests complete