@sanity/cli-test 0.0.2-alpha.4 → 0.0.2-alpha.6

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 examples before tests run.
+
+### 2. Use test examples in your tests
+
+```ts
+import {testExample} from '@sanity/cli-test'
+import {describe, test} from 'vitest'
+
+describe('my test suite', () => {
+  test('should work with basic-studio', async () => {
+    const cwd = await testExample('basic-studio')
+    // The example is now available at `cwd` with dependencies installed
+    // Tests that need built output should build explicitly:
+    // await buildExample(cwd)
+  })
+})
+```
+
 ## API
 
+### `testExample(exampleName: string, options?: TestExampleOptions): Promise<string>`
+
+Creates an isolated copy of a bundled example for testing. Returns the absolute path to the temporary directory containing the example.
+
+**Parameters:**
+
+- `exampleName` - Name of the example 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 example directory
+
+**Available Examples:**
+
+- `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 {testExample} from '@sanity/cli-test'
+
+const cwd = await testExample('basic-studio')
+// Example is ready at `cwd` with dependencies installed
+// Note: Examples are NOT built by default - tests should build if needed
+```
+
+### `setup(options?: SetupTestExamplesOptions): Promise<void>`
+
+Vitest global setup function that copies examples and installs dependencies. This is automatically called by vitest when using `@sanity/cli-test/vitest` in your globalSetup config.
+
+**Parameters:**
+
+- `options.additionalExamples` - Glob patterns for additional example directories from your local repo to set up alongside the default bundled examples (e.g., `['examples/*', 'dev/*']`). Only directories containing a `package.json` are included.
+- `options.tempDir` - Custom temp directory path (defaults to `process.cwd()/tmp`)
+
+**Note:** Examples are NOT built during setup. Tests that need built output should build explicitly.
+
+**Adding examples from your local repo:**
+
+If your repo has its own example directories that you want to test alongside the default bundled examples, use the `additionalExamples` 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, {
+    additionalExamples: ['examples/*', 'dev/*'],
+  })
+}
+```
+
+```ts
+// vitest.config.ts
+import {defineConfig} from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globalSetup: ['vitest.setup.ts'],
+  },
+})
+```
+
+### `teardown(options?: TeardownTestExamplesOptions): 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 examples that can be used for testing. When you call `testExample()`:
+
+1. It creates a unique temporary copy of the requested example
+2. Symlinks the node_modules directory from the global setup version (for performance)
+3. Returns the path to the isolated test directory
+
+The examples work identically whether this package is used in a monorepo or installed from npm.
+
+## Building Examples
+
+Examples are NOT built during global setup or when calling `testExample()`. 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 testExample('basic-studio')
+// Build the example 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', // Example 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

package/dist/index.d.ts

@@ -2,5 +2,8 @@ export * from './test/createTestClient.js';
 export * from './test/createTestToken.js';
 export * from './test/mockApi.js';
 export * from './test/mockSanityCommand.js';
+export * from './test/setupExamples.js';
 export * from './test/testCommand.js';
+export * from './test/testExample.js';
 export * from './test/testHook.js';
+export * from './utils/paths.js';

package/dist/index.js

@@ -2,7 +2,10 @@ export * from './test/createTestClient.js';
 export * from './test/createTestToken.js';
 export * from './test/mockApi.js';
 export * from './test/mockSanityCommand.js';
+export * from './test/setupExamples.js';
 export * from './test/testCommand.js';
+export * from './test/testExample.js';
 export * from './test/testHook.js';
+export * from './utils/paths.js';
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './test/createTestClient.js'\nexport * from './test/createTestToken.js'\nexport * from './test/mockApi.js'\nexport * from './test/mockSanityCommand.js'\nexport * from './test/testCommand.js'\nexport * from './test/testHook.js'\n"],"names":[],"mappings":"AAAA,cAAc,6BAA4B;AAC1C,cAAc,4BAA2B;AACzC,cAAc,oBAAmB;AACjC,cAAc,8BAA6B;AAC3C,cAAc,wBAAuB;AACrC,cAAc,qBAAoB"}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './test/createTestClient.js'\nexport * from './test/createTestToken.js'\nexport * from './test/mockApi.js'\nexport * from './test/mockSanityCommand.js'\nexport * from './test/setupExamples.js'\nexport * from './test/testCommand.js'\nexport * from './test/testExample.js'\nexport * from './test/testHook.js'\nexport * from './utils/paths.js'\n"],"names":[],"mappings":"AAAA,cAAc,6BAA4B;AAC1C,cAAc,4BAA2B;AACzC,cAAc,oBAAmB;AACjC,cAAc,8BAA6B;AAC3C,cAAc,0BAAyB;AACvC,cAAc,wBAAuB;AACrC,cAAc,wBAAuB;AACrC,cAAc,qBAAoB;AAClC,cAAc,mBAAkB"}

package/dist/test/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_EXAMPLES: readonly ["basic-app", "basic-studio", "multi-workspace-studio", "worst-case-studio"];
+export type ExampleName = (typeof DEFAULT_EXAMPLES)[number];

package/dist/test/constants.js

@@ -0,0 +1,8 @@
+export const DEFAULT_EXAMPLES = [
+    'basic-app',
+    'basic-studio',
+    'multi-workspace-studio',
+    'worst-case-studio'
+];
+
+//# sourceMappingURL=constants.js.map

package/dist/test/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/test/constants.ts"],"sourcesContent":["export const DEFAULT_EXAMPLES = [\n  'basic-app',\n  'basic-studio',\n  'multi-workspace-studio',\n  'worst-case-studio',\n] as const\n\nexport type ExampleName = (typeof DEFAULT_EXAMPLES)[number]\n"],"names":["DEFAULT_EXAMPLES"],"mappings":"AAAA,OAAO,MAAMA,mBAAmB;IAC9B;IACA;IACA;IACA;CACD,CAAS"}

package/dist/test/setupExamples.d.ts

@@ -0,0 +1,60 @@
+import { type TestProject } from 'vitest/node';
+/** Options for setupTestExamples */
+export interface SetupTestExamplesOptions {
+    /**
+     * Glob patterns for additional example directories to set up.
+     *
+     * Each pattern is matched against directories in the current working directory.
+     * Only directories containing a `package.json` file are included.
+     *
+     * @example
+     * ```typescript
+     * ['examples/*', 'dev/*']
+     * ```
+     */
+    additionalExamples?: string[];
+    /**
+     * Custom temp directory path. Defaults to process.cwd()/tmp
+     */
+    tempDir?: string;
+}
+/**
+ * Global setup function for initializing test examples.
+ *
+ * Copies examples from the bundled location to a temp directory
+ * and installs dependencies.
+ *
+ * Note: Examples are NOT built during setup. Tests that need built
+ * examples should build them as part of the test.
+ *
+ * This function is designed to be used with vitest globalSetup.
+ *
+ * @param options - Configuration options
+ * @example
+ * ```typescript
+ * // In vitest.config.ts
+ * export default defineConfig({
+ *   test: {
+ *     globalSetup: ['@sanity/cli-test/vitest']
+ *   }
+ * })
+ * ```
+ */
+export declare function setup(_: TestProject, options?: SetupTestExamplesOptions): Promise<void>;
+/** Options for teardownTestExamples */
+export interface TeardownTestExamplesOptions {
+    /**
+     * Custom temp directory path. Defaults to process.cwd()/tmp
+     */
+    tempDir?: string;
+}
+/**
+ * Teardown function to clean up test examples.
+ *
+ * Removes the temp directory created by setupTestExamples.
+ *
+ * This function is designed to be used with vitest globalSetup.
+ *
+ * @param options - Configuration options
+ */
+export declare function teardown(options?: TeardownTestExamplesOptions): Promise<void>;

package/dist/test/setupExamples.js

@@ -0,0 +1,129 @@
+import { exec as execNode } from 'node:child_process';
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
+import ora from 'ora';
+import { glob } from 'tinyglobby';
+import { fileExists } from '../utils/fileExists.js';
+import { getExamplesPath, getTempPath } from '../utils/paths.js';
+import { DEFAULT_EXAMPLES } from './constants.js';
+import { testCopyDirectory } from './testExample.js';
+const exec = promisify(execNode);
+async function getAdditionalExamplePaths(examples) {
+    const paths = await glob(examples, {
+        absolute: true,
+        ignore: [
+            '**/node_modules/**',
+            '**/dist/**'
+        ],
+        onlyDirectories: true
+    });
+    const additionalExamples = [];
+    for (const path of paths){
+        if (await fileExists(join(`${path}/package.json`))) {
+            additionalExamples.push({
+                example: basename(path),
+                fromPath: path
+            });
+        }
+    }
+    return additionalExamples;
+}
+/**
+ * Global setup function for initializing test examples.
+ *
+ * Copies examples from the bundled location to a temp directory
+ * and installs dependencies.
+ *
+ * Note: Examples are NOT built during setup. Tests that need built
+ * examples should build them as part of the test.
+ *
+ * This function is designed to be used with vitest globalSetup.
+ *
+ * @param options - Configuration options
+ * @example
+ * ```typescript
+ * // In vitest.config.ts
+ * export default defineConfig({
+ *   test: {
+ *     globalSetup: ['@sanity/cli-test/vitest']
+ *   }
+ * })
+ * ```
+ */ export async function setup(_, options = {}) {
+    const { additionalExamples, tempDir } = options;
+    const spinner = ora({
+        // Without this, the watch mode input is discarded
+        discardStdin: false,
+        text: 'Initializing test environment...'
+    }).start();
+    try {
+        const examplesDir = getExamplesPath();
+        const tempDirectory = getTempPath(tempDir);
+        const allExamplePaths = [];
+        // Add the default examples
+        for (const example of DEFAULT_EXAMPLES){
+            allExamplePaths.push({
+                example,
+                fromPath: join(examplesDir, example)
+            });
+        }
+        // Add the additional examples
+        if (additionalExamples && additionalExamples.length > 0) {
+            const additionalExamplePaths = await getAdditionalExamplePaths(additionalExamples);
+            if (additionalExamplePaths.length > 0) {
+                allExamplePaths.push(...additionalExamplePaths);
+            } else {
+                spinner.warn(`No additional examples found, check the glob pattern: ${additionalExamples.join(', ')}`);
+            }
+        }
+        for (const { example, fromPath } of allExamplePaths){
+            const toPath = join(tempDirectory, `example-${example}`);
+            // Copy the example, excluding node_modules and dist
+            await testCopyDirectory(fromPath, toPath, [
+                'node_modules',
+                'dist'
+            ]);
+            // Replace the package.json name with a temp name
+            const packageJsonPath = join(toPath, 'package.json');
+            const packageJson = await readFile(packageJsonPath, 'utf8');
+            const packageJsonData = JSON.parse(packageJson);
+            packageJsonData.name = `${packageJsonData.name}-test`;
+            await writeFile(packageJsonPath, JSON.stringify(packageJsonData, null, 2));
+            // Run pnpm install --no-lockfile in the temp directory
+            try {
+                await exec(`pnpm install --prefer-offline --no-lockfile`, {
+                    cwd: toPath
+                });
+            } catch (error) {
+                const execError = error;
+                spinner.fail('Failed to install dependencies');
+                console.error(execError.stderr || execError.stdout || execError.message);
+                throw new Error(`Error installing dependencies in ${toPath}: ${execError.stderr || execError.stdout || execError.message}`);
+            }
+        }
+        spinner.succeed('Test environment initialized');
+    } catch (error) {
+        spinner.fail('Failed to initialize test environment');
+        throw error;
+    }
+}
+/**
+ * Teardown function to clean up test examples.
+ *
+ * Removes the temp directory created by setupTestExamples.
+ *
+ * This function is designed to be used with vitest globalSetup.
+ *
+ * @param options - Configuration options
+ */ export async function teardown(options = {}) {
+    const { tempDir } = options;
+    const tempDirectory = getTempPath(tempDir);
+    // Remove the tmp directory
+    await rm(tempDirectory, {
+        force: true,
+        recursive: true
+    });
+}
+
+//# sourceMappingURL=setupExamples.js.map

package/dist/test/setupExamples.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/test/setupExamples.ts"],"sourcesContent":["import {exec as execNode} from 'node:child_process'\nimport {readFile, rm, writeFile} from 'node:fs/promises'\nimport {basename, join} from 'node:path'\nimport {promisify} from 'node:util'\n\nimport ora from 'ora'\nimport {glob} from 'tinyglobby'\nimport {type TestProject} from 'vitest/node'\n\nimport {fileExists} from '../utils/fileExists.js'\nimport {getExamplesPath, getTempPath} from '../utils/paths.js'\nimport {DEFAULT_EXAMPLES} from './constants.js'\nimport {testCopyDirectory} from './testExample.js'\n\nconst exec = promisify(execNode)\n\n/** Options for setupTestExamples */\nexport interface SetupTestExamplesOptions {\n  /**\n   * Glob patterns for additional example directories to set up.\n   *\n   * Each pattern is matched against directories in the current working directory.\n   * Only directories containing a `package.json` file are included.\n   *\n   * @example\n   * ```typescript\n   * ['examples/*', 'dev/*']\n   * ```\n   */\n  additionalExamples?: string[]\n\n  /**\n   * Custom temp directory path. Defaults to process.cwd()/tmp\n   */\n  tempDir?: string\n}\n\nasync function getAdditionalExamplePaths(examples: string[]): Promise<ExamplePath[]> {\n  const paths = await glob(examples, {\n    absolute: true,\n    ignore: ['**/node_modules/**', '**/dist/**'],\n    onlyDirectories: true,\n  })\n\n  const additionalExamples: ExamplePath[] = []\n\n  for (const path of paths) {\n    if (await fileExists(join(`${path}/package.json`))) {\n      additionalExamples.push({\n        example: basename(path),\n        fromPath: path,\n      })\n    }\n  }\n\n  return additionalExamples\n}\n\ninterface ExamplePath {\n  example: string\n  fromPath: string\n}\n/**\n * Global setup function for initializing test examples.\n *\n * Copies examples from the bundled location to a temp directory\n * and installs dependencies.\n *\n * Note: Examples are NOT built during setup. Tests that need built\n * examples should build them as part of the test.\n *\n * This function is designed to be used with vitest globalSetup.\n *\n * @param options - Configuration options\n * @example\n * ```typescript\n * // In vitest.config.ts\n * export default defineConfig({\n *   test: {\n *     globalSetup: ['@sanity/cli-test/vitest']\n *   }\n * })\n * ```\n */\nexport async function setup(_: TestProject, options: SetupTestExamplesOptions = {}): Promise<void> {\n  const {additionalExamples, tempDir} = options\n\n  const spinner = ora({\n    // Without this, the watch mode input is discarded\n    discardStdin: false,\n    text: 'Initializing test environment...',\n  }).start()\n\n  try {\n    const examplesDir = getExamplesPath()\n    const tempDirectory = getTempPath(tempDir)\n\n    const allExamplePaths: ExamplePath[] = []\n\n    // Add the default examples\n    for (const example of DEFAULT_EXAMPLES) {\n      allExamplePaths.push({\n        example,\n        fromPath: join(examplesDir, example),\n      })\n    }\n\n    // Add the additional examples\n    if (additionalExamples && additionalExamples.length > 0) {\n      const additionalExamplePaths = await getAdditionalExamplePaths(additionalExamples)\n\n      if (additionalExamplePaths.length > 0) {\n        allExamplePaths.push(...additionalExamplePaths)\n      } else {\n        spinner.warn(\n          `No additional examples found, check the glob pattern: ${additionalExamples.join(', ')}`,\n        )\n      }\n    }\n\n    for (const {example, fromPath} of allExamplePaths) {\n      const toPath = join(tempDirectory, `example-${example}`)\n      // Copy the example, excluding node_modules and dist\n      await testCopyDirectory(fromPath, toPath, ['node_modules', 'dist'])\n\n      // Replace the package.json name with a temp name\n      const packageJsonPath = join(toPath, 'package.json')\n      const packageJson = await readFile(packageJsonPath, 'utf8')\n      const packageJsonData = JSON.parse(packageJson)\n      packageJsonData.name = `${packageJsonData.name}-test`\n      await writeFile(packageJsonPath, JSON.stringify(packageJsonData, null, 2))\n\n      // Run pnpm install --no-lockfile in the temp directory\n      try {\n        await exec(`pnpm install --prefer-offline --no-lockfile`, {\n          cwd: toPath,\n        })\n      } catch (error) {\n        const execError = error as {message: string; stderr?: string; stdout?: string}\n        spinner.fail('Failed to install dependencies')\n        console.error(execError.stderr || execError.stdout || execError.message)\n        throw new Error(\n          `Error installing dependencies in ${toPath}: ${execError.stderr || execError.stdout || execError.message}`,\n        )\n      }\n    }\n\n    spinner.succeed('Test environment initialized')\n  } catch (error) {\n    spinner.fail('Failed to initialize test environment')\n    throw error\n  }\n}\n\n/** Options for teardownTestExamples */\nexport interface TeardownTestExamplesOptions {\n  /**\n   * Custom temp directory path. Defaults to process.cwd()/tmp\n   */\n  tempDir?: string\n}\n\n/**\n * Teardown function to clean up test examples.\n *\n * Removes the temp directory created by setupTestExamples.\n *\n * This function is designed to be used with vitest globalSetup.\n *\n * @param options - Configuration options\n */\nexport async function teardown(options: TeardownTestExamplesOptions = {}): Promise<void> {\n  const {tempDir} = options\n  const tempDirectory = getTempPath(tempDir)\n\n  // Remove the tmp directory\n  await rm(tempDirectory, {force: true, recursive: true})\n}\n"],"names":["exec","execNode","readFile","rm","writeFile","basename","join","promisify","ora","glob","fileExists","getExamplesPath","getTempPath","DEFAULT_EXAMPLES","testCopyDirectory","getAdditionalExamplePaths","examples","paths","absolute","ignore","onlyDirectories","additionalExamples","path","push","example","fromPath","setup","_","options","tempDir","spinner","discardStdin","text","start","examplesDir","tempDirectory","allExamplePaths","length","additionalExamplePaths","warn","toPath","packageJsonPath","packageJson","packageJsonData","JSON","parse","name","stringify","cwd","error","execError","fail","console","stderr","stdout","message","Error","succeed","teardown","force","recursive"],"mappings":"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"}

package/dist/test/testExample.d.ts

@@ -0,0 +1,46 @@
+import { type ExampleName } from './constants.js';
+/**
+ * Recursively copy a directory, skipping specified folders.
+ *
+ * @param srcDir - Source directory to copy from
+ * @param destDir - Destination directory to copy to
+ * @param skip - Array of directory/file names to skip (e.g., ['node_modules', 'dist'])
+ * @internal
+ */
+export declare function testCopyDirectory(srcDir: string, destDir: string, skip?: string[]): Promise<void>;
+/** Options for testExample */
+export interface TestExampleOptions {
+    /**
+     * Custom temp directory. Defaults to process.cwd()/tmp
+     */
+    tempDir?: string;
+}
+/**
+ * Clones an example directory into a temporary directory with an isolated copy.
+ *
+ * The function creates a unique temporary copy of the specified example with:
+ * - A random unique ID to avoid conflicts between parallel tests
+ * - Symlinked node_modules for performance (from the global setup version)
+ * - Modified package.json name to prevent conflicts
+ *
+ * The example is first looked up in the temp directory (if global setup ran),
+ * otherwise it falls back to the bundled examples in the package.
+ *
+ * @param exampleName - The name of the example to clone (e.g., 'basic-app', 'basic-studio')
+ * @param options - Configuration options
+ * @returns The absolute path to the temporary directory containing the example
+ *
+ * @example
+ * ```typescript
+ * import {testExample} from '@sanity/cli-test'
+ * import {describe, test} from 'vitest'
+ *
+ * describe('my test suite', () => {
+ *   test('should work with basic-studio', async () => {
+ *     const cwd = await testExample('basic-studio')
+ *     // ... run your tests in this directory
+ *   })
+ * })
+ * ```
+ */
+export declare function testExample(exampleName: ExampleName | (string & {}), options?: TestExampleOptions): Promise<string>;

package/dist/test/testExample.js

@@ -0,0 +1,93 @@
+import { randomBytes } from 'node:crypto';
+import { copyFile, mkdir, readdir, readFile, stat, symlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getExamplesPath, getTempPath } from '../utils/paths.js';
+/**
+ * Recursively copy a directory, skipping specified folders.
+ *
+ * @param srcDir - Source directory to copy from
+ * @param destDir - Destination directory to copy to
+ * @param skip - Array of directory/file names to skip (e.g., ['node_modules', 'dist'])
+ * @internal
+ */ export async function testCopyDirectory(srcDir, destDir, skip = []) {
+    await mkdir(destDir, {
+        recursive: true
+    });
+    const entries = await readdir(srcDir);
+    for (const entry of entries){
+        if (skip.includes(entry)) {
+            continue;
+        }
+        const srcPath = join(srcDir, entry);
+        const destPath = join(destDir, entry);
+        const stats = await stat(srcPath);
+        await (stats.isDirectory() ? testCopyDirectory(srcPath, destPath, skip) : copyFile(srcPath, destPath));
+    }
+}
+/**
+ * Clones an example directory into a temporary directory with an isolated copy.
+ *
+ * The function creates a unique temporary copy of the specified example with:
+ * - A random unique ID to avoid conflicts between parallel tests
+ * - Symlinked node_modules for performance (from the global setup version)
+ * - Modified package.json name to prevent conflicts
+ *
+ * The example is first looked up in the temp directory (if global setup ran),
+ * otherwise it falls back to the bundled examples in the package.
+ *
+ * @param exampleName - The name of the example to clone (e.g., 'basic-app', 'basic-studio')
+ * @param options - Configuration options
+ * @returns The absolute path to the temporary directory containing the example
+ *
+ * @example
+ * ```typescript
+ * import {testExample} from '@sanity/cli-test'
+ * import {describe, test} from 'vitest'
+ *
+ * describe('my test suite', () => {
+ *   test('should work with basic-studio', async () => {
+ *     const cwd = await testExample('basic-studio')
+ *     // ... run your tests in this directory
+ *   })
+ * })
+ * ```
+ */ export async function testExample(exampleName, options = {}) {
+    const { tempDir } = options;
+    const tempDirectory = getTempPath(tempDir);
+    // Examples are cloned in the tmp directory by the setup function
+    let tempExamplePath = join(tempDirectory, `example-${exampleName}`);
+    try {
+        const stats = await stat(tempExamplePath);
+        if (!stats.isDirectory()) {
+            throw new Error(`${tempExamplePath} is not a directory`);
+        }
+    } catch (e) {
+        // If the cloned example doesn't exist, copy from the bundled examples
+        if (e.code === 'ENOENT') {
+            tempExamplePath = join(getExamplesPath(), exampleName);
+        } else {
+            throw e;
+        }
+    }
+    const tempId = randomBytes(8).toString('hex');
+    const tempPath = join(tempDirectory, `example-${exampleName}-${tempId}`);
+    // Always skip node_modules (will be symlinked), dist (tests build if needed), and tmp
+    const skipDirs = [
+        'node_modules',
+        'dist',
+        'tmp'
+    ];
+    // Copy the example to the temp directory
+    await testCopyDirectory(tempExamplePath, tempPath, skipDirs);
+    // Symlink the node_modules directory for performance
+    await symlink(join(tempExamplePath, 'node_modules'), join(tempPath, 'node_modules'));
+    // Replace the package.json name with a temp name
+    const packageJsonPath = join(tempPath, 'package.json');
+    const packageJson = await readFile(packageJsonPath, 'utf8');
+    const packageJsonData = JSON.parse(packageJson);
+    packageJsonData.name = `${packageJsonData.name}-${tempId}`;
+    await writeFile(packageJsonPath, JSON.stringify(packageJsonData, null, 2));
+    return tempPath;
+}
+
+//# sourceMappingURL=testExample.js.map

package/dist/test/testExample.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/test/testExample.ts"],"sourcesContent":["import {randomBytes} from 'node:crypto'\nimport {copyFile, mkdir, readdir, readFile, stat, symlink, writeFile} from 'node:fs/promises'\nimport {join} from 'node:path'\n\nimport {getExamplesPath, getTempPath} from '../utils/paths.js'\nimport {type ExampleName} from './constants.js'\n\n/**\n * Recursively copy a directory, skipping specified folders.\n *\n * @param srcDir - Source directory to copy from\n * @param destDir - Destination directory to copy to\n * @param skip - Array of directory/file names to skip (e.g., ['node_modules', 'dist'])\n * @internal\n */\nexport async function testCopyDirectory(\n  srcDir: string,\n  destDir: string,\n  skip: string[] = [],\n): Promise<void> {\n  await mkdir(destDir, {recursive: true})\n\n  const entries = await readdir(srcDir)\n\n  for (const entry of entries) {\n    if (skip.includes(entry)) {\n      continue\n    }\n\n    const srcPath = join(srcDir, entry)\n    const destPath = join(destDir, entry)\n\n    const stats = await stat(srcPath)\n\n    await (stats.isDirectory()\n      ? testCopyDirectory(srcPath, destPath, skip)\n      : copyFile(srcPath, destPath))\n  }\n}\n\n/** Options for testExample */\nexport interface TestExampleOptions {\n  /**\n   * Custom temp directory. Defaults to process.cwd()/tmp\n   */\n  tempDir?: string\n}\n\n/**\n * Clones an example directory into a temporary directory with an isolated copy.\n *\n * The function creates a unique temporary copy of the specified example with:\n * - A random unique ID to avoid conflicts between parallel tests\n * - Symlinked node_modules for performance (from the global setup version)\n * - Modified package.json name to prevent conflicts\n *\n * The example is first looked up in the temp directory (if global setup ran),\n * otherwise it falls back to the bundled examples in the package.\n *\n * @param exampleName - The name of the example to clone (e.g., 'basic-app', 'basic-studio')\n * @param options - Configuration options\n * @returns The absolute path to the temporary directory containing the example\n *\n * @example\n * ```typescript\n * import {testExample} from '@sanity/cli-test'\n * import {describe, test} from 'vitest'\n *\n * describe('my test suite', () => {\n *   test('should work with basic-studio', async () => {\n *     const cwd = await testExample('basic-studio')\n *     // ... run your tests in this directory\n *   })\n * })\n * ```\n */\nexport async function testExample(\n  exampleName: ExampleName | (string & {}),\n  options: TestExampleOptions = {},\n): Promise<string> {\n  const {tempDir} = options\n\n  const tempDirectory = getTempPath(tempDir)\n\n  // Examples are cloned in the tmp directory by the setup function\n  let tempExamplePath = join(tempDirectory, `example-${exampleName}`)\n\n  try {\n    const stats = await stat(tempExamplePath)\n    if (!stats.isDirectory()) {\n      throw new Error(`${tempExamplePath} is not a directory`)\n    }\n  } catch (e) {\n    // If the cloned example doesn't exist, copy from the bundled examples\n    if ((e as NodeJS.ErrnoException).code === 'ENOENT') {\n      tempExamplePath = join(getExamplesPath(), exampleName)\n    } else {\n      throw e\n    }\n  }\n\n  const tempId = randomBytes(8).toString('hex')\n  const tempPath = join(tempDirectory, `example-${exampleName}-${tempId}`)\n\n  // Always skip node_modules (will be symlinked), dist (tests build if needed), and tmp\n  const skipDirs = ['node_modules', 'dist', 'tmp']\n\n  // Copy the example to the temp directory\n  await testCopyDirectory(tempExamplePath, tempPath, skipDirs)\n\n  // Symlink the node_modules directory for performance\n  await symlink(join(tempExamplePath, 'node_modules'), join(tempPath, 'node_modules'))\n\n  // Replace the package.json name with a temp name\n  const packageJsonPath = join(tempPath, 'package.json')\n  const packageJson = await readFile(packageJsonPath, 'utf8')\n  const packageJsonData = JSON.parse(packageJson)\n  packageJsonData.name = `${packageJsonData.name}-${tempId}`\n  await writeFile(packageJsonPath, JSON.stringify(packageJsonData, null, 2))\n\n  return tempPath\n}\n"],"names":["randomBytes","copyFile","mkdir","readdir","readFile","stat","symlink","writeFile","join","getExamplesPath","getTempPath","testCopyDirectory","srcDir","destDir","skip","recursive","entries","entry","includes","srcPath","destPath","stats","isDirectory","testExample","exampleName","options","tempDir","tempDirectory","tempExamplePath","Error","e","code","tempId","toString","tempPath","skipDirs","packageJsonPath","packageJson","packageJsonData","JSON","parse","name","stringify"],"mappings":"AAAA,SAAQA,WAAW,QAAO,cAAa;AACvC,SAAQC,QAAQ,EAAEC,KAAK,EAAEC,OAAO,EAAEC,QAAQ,EAAEC,IAAI,EAAEC,OAAO,EAAEC,SAAS,QAAO,mBAAkB;AAC7F,SAAQC,IAAI,QAAO,YAAW;AAE9B,SAAQC,eAAe,EAAEC,WAAW,QAAO,oBAAmB;AAG9D;;;;;;;CAOC,GACD,OAAO,eAAeC,kBACpBC,MAAc,EACdC,OAAe,EACfC,OAAiB,EAAE;IAEnB,MAAMZ,MAAMW,SAAS;QAACE,WAAW;IAAI;IAErC,MAAMC,UAAU,MAAMb,QAAQS;IAE9B,KAAK,MAAMK,SAASD,QAAS;QAC3B,IAAIF,KAAKI,QAAQ,CAACD,QAAQ;YACxB;QACF;QAEA,MAAME,UAAUX,KAAKI,QAAQK;QAC7B,MAAMG,WAAWZ,KAAKK,SAASI;QAE/B,MAAMI,QAAQ,MAAMhB,KAAKc;QAEzB,MAAOE,CAAAA,MAAMC,WAAW,KACpBX,kBAAkBQ,SAASC,UAAUN,QACrCb,SAASkB,SAASC,SAAQ;IAChC;AACF;AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BC,GACD,OAAO,eAAeG,YACpBC,WAAwC,EACxCC,UAA8B,CAAC,CAAC;IAEhC,MAAM,EAACC,OAAO,EAAC,GAAGD;IAElB,MAAME,gBAAgBjB,YAAYgB;IAElC,iEAAiE;IACjE,IAAIE,kBAAkBpB,KAAKmB,eAAe,CAAC,QAAQ,EAAEH,aAAa;IAElE,IAAI;QACF,MAAMH,QAAQ,MAAMhB,KAAKuB;QACzB,IAAI,CAACP,MAAMC,WAAW,IAAI;YACxB,MAAM,IAAIO,MAAM,GAAGD,gBAAgB,mBAAmB,CAAC;QACzD;IACF,EAAE,OAAOE,GAAG;QACV,sEAAsE;QACtE,IAAI,AAACA,EAA4BC,IAAI,KAAK,UAAU;YAClDH,kBAAkBpB,KAAKC,mBAAmBe;QAC5C,OAAO;YACL,MAAMM;QACR;IACF;IAEA,MAAME,SAAShC,YAAY,GAAGiC,QAAQ,CAAC;IACvC,MAAMC,WAAW1B,KAAKmB,eAAe,CAAC,QAAQ,EAAEH,YAAY,CAAC,EAAEQ,QAAQ;IAEvE,sFAAsF;IACtF,MAAMG,WAAW;QAAC;QAAgB;QAAQ;KAAM;IAEhD,yCAAyC;IACzC,MAAMxB,kBAAkBiB,iBAAiBM,UAAUC;IAEnD,qDAAqD;IACrD,MAAM7B,QAAQE,KAAKoB,iBAAiB,iBAAiBpB,KAAK0B,UAAU;IAEpE,iDAAiD;IACjD,MAAME,kBAAkB5B,KAAK0B,UAAU;IACvC,MAAMG,cAAc,MAAMjC,SAASgC,iBAAiB;IACpD,MAAME,kBAAkBC,KAAKC,KAAK,CAACH;IACnCC,gBAAgBG,IAAI,GAAG,GAAGH,gBAAgBG,IAAI,CAAC,CAAC,EAAET,QAAQ;IAC1D,MAAMzB,UAAU6B,iBAAiBG,KAAKG,SAAS,CAACJ,iBAAiB,MAAM;IAEvE,OAAOJ;AACT"}

package/dist/utils/fileExists.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Checks if a file exists and can be "accessed".
+ * Prone to race conditions, but good enough for our use cases.
+ *
+ * @param filePath - The path to the file to check
+ * @returns A promise that resolves to true if the file exists, false otherwise
+ * @internal
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;