@sanity/cli-test 0.0.2-alpha.0 → 0.0.2-alpha.10

package/README.md

@@ -2,8 +2,161 @@
 
 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`:
+
+```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
+
+```ts
+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:**
+
+```ts
+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:
+
+```ts
+// 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/*'],
+  })
+}
+```
+
+```ts
+// 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:**
+
+```ts
+// 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.
@@ -30,3 +183,78 @@ mockApi({
   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:
+
+```ts
+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`):
+
+```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:**
+
+```ts
+// 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