test: add workspaceUtils utility and refactor test paths

- Introduced `workspaceUtils` for consistent workspace directory resolution
- Added unit tests for `findWorkspaceRoot`, `getScriptPath`, `getWorkspacePath`, and `setupTestPaths`
- Refactored CLI and script integration tests to utilize `workspaceUtils`
- Updated `nx.json` and `package.json` with explicit `test:unit` and `test:integration` targets for granular control

Author: jonphipps

CLAUDE.md

@@ -56,7 +56,7 @@ The project uses a 5-group testing strategy optimized for efficiency and cost ma
 #### Group 3: Pre-Commit Tests (Git Hook - Fast Feedback)
 - **Automatic**: Runs on `git commit`
 - **Manual**: `pnpm test:pre-commit`
-- **What runs**: `nx affected --targets=typecheck,lint,test --parallel=3` + config validation
+- **What runs**: `nx affected --targets=typecheck,lint,test:unit --parallel=3` + config validation
 - **Target**: < 60 seconds
 
 #### Group 4: Pre-Push Tests (Git Hook - Deployment Focus)
@@ -144,9 +144,104 @@ standards-dev/
 - **Pre-commit**: TypeScript, ESLint, unit tests run automatically
 - **Pre-push**: Build regression tests (branch-aware) run automatically  
 - **Test runner**: Vitest for unit/integration tests
-- **E2E testing**: Puppeteer for interface testing when needed
+- **E2E testing**: Playwright for interface testing when needed
 - **Always test before commits**: Tests must pass before offering to commit
 
+## Test Placement Decision Tree (CRITICAL - Reference When Creating Tests)
+
+**ALWAYS use this decision tree when creating new tests to ensure they run in the correct scenario:**
+
+### 🎯 **Where to Put New Tests**
+
+```
+📁 Test Placement Decision Tree
+│
+├── 🔧 **Unit Tests** (Pure logic, no external deps)
+│   └── 📍 Location: `packages/theme/src/tests/components/ComponentName.test.tsx`
+│   └── 🎯 Target: Runs in `test:unit` (pre-commit) + `test` (comprehensive)
+│   └── ✅ Examples: Component rendering, pure functions, config parsing
+│
+├── 🔗 **Integration Tests** (External APIs, file system, CLI tools)
+│   ├── 📍 Scripts: `packages/theme/src/tests/scripts/`
+│   ├── 📍 External Services: `packages/theme/src/tests/deployment/`
+│   └── 🎯 Target: Only runs in `test:integration` (comprehensive testing)
+│   └── ✅ Examples: Google Sheets API, file operations, CLI execution
+│
+├── 🌐 **E2E Tests** (Browser automation, full user workflows)
+│   ├── 📍 Workspace: `/e2e/site-validation.spec.ts`
+│   ├── 📍 Site-specific: `standards/SITE/e2e/feature.e2e.test.ts`
+│   └── 🎯 Target: `nx run standards-dev:e2e` or `nx run SITE:e2e`
+│   └── ✅ Examples: Navigation, form submission, visual checks
+│
+└── 🎯 **Performance/Visual** (Screenshots, load testing)
+    └── 📍 Location: `/e2e/visual-regression-enhanced.spec.ts`
+    └── 🎯 Target: Specialized E2E runs
+```
+
+### 🚦 **Quick Decision Questions**
+
+**Ask yourself when creating a test:**
+
+1. **Does it make network calls or use external APIs?** → Integration test
+2. **Does it render in a browser or test user flows?** → E2E test  
+3. **Does it test component logic in isolation?** → Unit test
+4. **Does it validate file system operations?** → Integration test
+5. **Does it test configuration parsing only?** → Unit test
+
+### 📋 **Test Coverage by Scenario**
+
+| Scenario | Unit Tests | Integration Tests | E2E Tests | When It Runs |
+|----------|------------|-------------------|-----------|--------------|
+| **Pre-commit** | ✅ Fast feedback | ❌ Too slow | ❌ Too slow | Every `git commit` |
+| **Pre-push** | ✅ | ✅ | ❌ | Every `git push` |  
+| **Comprehensive** | ✅ | ✅ | ✅ | Manual/CI full runs |
+| **Affected** | ✅ Only changed | ✅ Only changed | ❌ | Development workflow |
+| **CI** | ✅ | ✅ | ✅ | Production deployments |
+
+### 🎪 **Examples of Correct Placement**
+
+```typescript
+// ✅ Unit Test - packages/theme/src/tests/components/
+describe('VocabularyTable', () => {
+  it('renders headers correctly', () => {
+    // Tests pure component logic
+  });
+});
+
+// ✅ Integration Test - packages/theme/src/tests/scripts/  
+describe('Google Sheets API', () => {
+  it('fetches vocabulary data', async () => {
+    // Tests external API integration
+  });
+});
+
+// ✅ E2E Test - /e2e/
+test('user can navigate between sites', async ({ page }) => {
+  // Tests full browser workflows
+});
+```
+
+**Key principle**: Unit tests run fast in pre-commit for immediate feedback, integration tests run in comprehensive scenarios, E2E tests validate complete user experiences.
+
+### 🛠️ **Test Utilities**
+
+For consistent directory handling in tests, use the `workspaceUtils` helper:
+
+```typescript
+import { findWorkspaceRoot, getScriptPath, setupTestPaths } from '../utils/workspaceUtils';
+
+// Get workspace root reliably (instead of process.cwd())
+const workspaceRoot = findWorkspaceRoot();
+
+// Get path to scripts
+const scriptPath = getScriptPath('vocabulary-comparison.mjs');
+
+// Get common test paths
+const { workspaceRoot, scriptsDir, tmpDir, packagesDir, themeDir } = setupTestPaths();
+```
+
+**Always use `workspaceUtils` instead of `process.cwd()` in integration tests** to ensure consistent directory resolution regardless of test execution context.
+
 ### Content and Navigation Rules
 - **Never hardcode URLs**: Always use SiteLink component or configuration-based URLs
 - **Broken links categorization**:

nx.json

@@ -100,6 +100,30 @@
         "{projectRoot}/e2e/**/*",
         "{projectRoot}/**/*.e2e.{js,ts,jsx,tsx}"
       ]
+    },
+    "test:unit": {
+      "cache": true,
+      "outputs": ["{projectRoot}/coverage", "{projectRoot}/test-results"],
+      "inputs": [
+        "default",
+        "{projectRoot}/test/**/*",
+        "{projectRoot}/**/*.test.{js,ts,jsx,tsx}",
+        "{projectRoot}/**/*.spec.{js,ts,jsx,tsx}",
+        "{workspaceRoot}/vite.config.ts",
+        "{workspaceRoot}/vitest.config.*"
+      ]
+    },
+    "test:integration": {
+      "cache": true,
+      "outputs": ["{projectRoot}/coverage", "{projectRoot}/test-results"],
+      "inputs": [
+        "default",
+        "{projectRoot}/test/**/*",
+        "{projectRoot}/**/*.test.{js,ts,jsx,tsx}",
+        "{projectRoot}/**/*.spec.{js,ts,jsx,tsx}",
+        "{workspaceRoot}/vite.config.ts",
+        "{workspaceRoot}/vitest.config.*"
+      ]
     }
   },
   "plugins": [

package.json

@@ -137,7 +137,7 @@
     "test:full": "pnpm typecheck && pnpm lint --quiet && pnpm test && pnpm test:builds:config",
     "test:regression": "nx run standards-dev:regression:full",
     "test:regression:nx:fast": "nx run standards-dev:regression:fast",
-    "test:pre-commit": "nx affected --targets=typecheck,lint,test --parallel=3 && node scripts/test-site-builds-affected.js --env local --skip-build",
+    "test:pre-commit": "nx affected --targets=typecheck,lint,test:unit --parallel=3 && node scripts/test-site-builds-affected.js --env local --skip-build",
     "test:pre-push": "pnpm test:pre-commit && pnpm test:builds:critical",
     "test:pre-push:nx": "nx affected --target=lint && nx affected --target=typecheck && nx affected --target=test && nx affected --target=build",
     "test:e2e": "nx run standards-dev:e2e",

packages/theme/project.json

@@ -36,6 +36,45 @@
         "{workspaceRoot}/vitest.config.*"
       ]
     },
+    "test:unit": {
+      "executor": "@nx/vite:test",
+      "options": {
+        "config": "{workspaceRoot}/vite.config.ts",
+        "exclude": [
+          "**/scripts/**",
+          "**/deployment/**"
+        ]
+      },
+      "outputs": ["{projectRoot}/coverage"],
+      "cache": true,
+      "inputs": [
+        "default",
+        "{projectRoot}/src/**/*.{test,spec}.{js,ts,jsx,tsx}",
+        "!{projectRoot}/src/tests/scripts/**/*",
+        "!{projectRoot}/src/tests/deployment/**/*",
+        "{workspaceRoot}/vite.config.ts",
+        "{workspaceRoot}/vitest.config.*"
+      ]
+    },
+    "test:integration": {
+      "executor": "@nx/vite:test", 
+      "options": {
+        "config": "{workspaceRoot}/vite.config.ts",
+        "include": [
+          "**/scripts/**",
+          "**/deployment/**"
+        ]
+      },
+      "outputs": ["{projectRoot}/coverage"],
+      "cache": true,
+      "inputs": [
+        "default",
+        "{projectRoot}/src/tests/scripts/**/*",
+        "{projectRoot}/src/tests/deployment/**/*",
+        "{workspaceRoot}/vite.config.ts",
+        "{workspaceRoot}/vitest.config.*"
+      ]
+    },
     "typecheck": {
       "executor": "nx:run-commands",
       "options": {

packages/theme/src/tests/scripts/check-mediatype-languages.test.ts

@@ -3,6 +3,7 @@ import { exec } from 'child_process';
 import { promisify } from 'util';
 import path from 'path';
 import fs from 'fs/promises';
+import { getScriptPath, setupTestPaths } from '../utils/workspaceUtils';
 
 const execAsync = promisify(exec);
 
@@ -14,9 +15,8 @@ const mockEnv = {
 };
 
 describe('check-mediatype-languages.mjs', () => {
-  const projectRoot = path.resolve(__dirname, '../../../../..');
-  const scriptPath = path.join(projectRoot, 'scripts', 'check-mediatype-languages.mjs');
-  const tmpDir = path.join(projectRoot, 'tmp');
+  const scriptPath = getScriptPath('check-mediatype-languages.mjs');
+  const { workspaceRoot, tmpDir } = setupTestPaths();
 
   beforeEach(async () => {
     // Debug: Check current working directory

packages/theme/src/tests/scripts/vocabulary-comparison-cli.test.ts

@@ -5,12 +5,13 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { exec } from 'child_process';
 import { promisify } from 'util';
-import path from 'path';
+import { getScriptPath, setupTestPaths } from '../utils/workspaceUtils';
 
 const execAsync = promisify(exec);
 
 describe('Vocabulary Comparison CLI', () => {
-    const scriptPath = path.join(process.cwd(), '../../scripts/vocabulary-comparison.mjs');
+    const scriptPath = getScriptPath('vocabulary-comparison.mjs');
+    const { workspaceRoot } = setupTestPaths();
 
     // Skip these tests in CI environment
     if (process.env.CI) {

packages/theme/src/tests/utils/workspaceUtils.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import path from 'path';
+import fs from 'fs';
+import { findWorkspaceRoot, getScriptPath, getWorkspacePath, setupTestPaths } from './workspaceUtils';
+
+describe('workspaceUtils', () => {
+  describe('findWorkspaceRoot', () => {
+    it('should find the workspace root directory', () => {
+      const workspaceRoot = findWorkspaceRoot();
+      
+      // Should be an absolute path
+      expect(path.isAbsolute(workspaceRoot)).toBe(true);
+      
+      // Should contain a package.json with the correct name
+      const packageJsonPath = path.join(workspaceRoot, 'package.json');
+      expect(fs.existsSync(packageJsonPath)).toBe(true);
+      
+      const packageJson = require(packageJsonPath);
+      expect(packageJson.name).toBe('standards-dev');
+    });
+
+    it('should return the same path when called multiple times', () => {
+      const path1 = findWorkspaceRoot();
+      const path2 = findWorkspaceRoot();
+      
+      expect(path1).toBe(path2);
+    });
+  });
+
+  describe('getScriptPath', () => {
+    it('should return correct path for script files', () => {
+      const scriptPath = getScriptPath('vocabulary-comparison.mjs');
+      
+      expect(path.isAbsolute(scriptPath)).toBe(true);
+      expect(scriptPath).toContain('scripts');
+      expect(scriptPath).toContain('vocabulary-comparison.mjs');
+    });
+  });
+
+  describe('getWorkspacePath', () => {
+    it('should return correct path for relative workspace paths', () => {
+      const tmpPath = getWorkspacePath('tmp');
+      const packagesPath = getWorkspacePath('packages/theme');
+      
+      expect(path.isAbsolute(tmpPath)).toBe(true);
+      expect(path.isAbsolute(packagesPath)).toBe(true);
+      expect(tmpPath).toContain('tmp');
+      expect(packagesPath).toContain('packages');
+      expect(packagesPath).toContain('theme');
+    });
+  });
+
+  describe('setupTestPaths', () => {
+    it('should return all common test paths', () => {
+      const paths = setupTestPaths();
+      
+      expect(paths).toHaveProperty('workspaceRoot');
+      expect(paths).toHaveProperty('scriptsDir');
+      expect(paths).toHaveProperty('tmpDir');
+      expect(paths).toHaveProperty('packagesDir');
+      expect(paths).toHaveProperty('themeDir');
+      
+      // All paths should be absolute
+      Object.values(paths).forEach(pathValue => {
+        expect(path.isAbsolute(pathValue)).toBe(true);
+      });
+    });
+
+    it('should return paths that exist in the workspace', () => {
+      const { workspaceRoot, scriptsDir, packagesDir } = setupTestPaths();
+      
+      // These directories should exist
+      expect(fs.existsSync(workspaceRoot)).toBe(true);
+      expect(fs.existsSync(scriptsDir)).toBe(true);
+      expect(fs.existsSync(packagesDir)).toBe(true);
+    });
+  });
+});

packages/theme/src/tests/utils/workspaceUtils.ts

@@ -0,0 +1,77 @@
+/**
+ * Utility functions for test workspace management
+ * Provides consistent directory handling across all test files
+ */
+
+import path from 'path';
+import fs from 'fs';
+
+/**
+ * Finds the workspace root by looking for package.json with "name": "standards-dev"
+ * This is more reliable than process.cwd() which can vary depending on test execution context
+ * 
+ * @returns {string} Absolute path to the workspace root
+ * @throws {Error} If workspace root cannot be found
+ */
+export const findWorkspaceRoot = (): string => {
+  let currentDir = __dirname;
+  
+  while (currentDir !== path.dirname(currentDir)) {
+    const packageJsonPath = path.join(currentDir, 'package.json');
+    
+    if (fs.existsSync(packageJsonPath)) {
+      try {
+        const packageJson = require(packageJsonPath);
+        if (packageJson.name === 'standards-dev') {
+          return currentDir;
+        }
+      } catch (e) {
+        // Continue searching if package.json is malformed
+      }
+    }
+    
+    currentDir = path.dirname(currentDir);
+  }
+  
+  throw new Error('Could not find workspace root - no package.json with name "standards-dev" found');
+};
+
+/**
+ * Gets the absolute path to a script in the workspace scripts directory
+ * 
+ * @param scriptName - Name of the script file (e.g., 'vocabulary-comparison.mjs')
+ * @returns {string} Absolute path to the script
+ */
+export const getScriptPath = (scriptName: string): string => {
+  const workspaceRoot = findWorkspaceRoot();
+  return path.join(workspaceRoot, 'scripts', scriptName);
+};
+
+/**
+ * Gets the absolute path to a directory relative to workspace root
+ * 
+ * @param relativePath - Path relative to workspace root (e.g., 'tmp', 'packages/theme')
+ * @returns {string} Absolute path to the directory
+ */
+export const getWorkspacePath = (relativePath: string): string => {
+  const workspaceRoot = findWorkspaceRoot();
+  return path.join(workspaceRoot, relativePath);
+};
+
+/**
+ * Sets up common test environment paths
+ * Returns commonly used paths for integration tests
+ * 
+ * @returns {object} Object containing commonly used paths
+ */
+export const setupTestPaths = () => {
+  const workspaceRoot = findWorkspaceRoot();
+  
+  return {
+    workspaceRoot,
+    scriptsDir: path.join(workspaceRoot, 'scripts'),
+    tmpDir: path.join(workspaceRoot, 'tmp'),
+    packagesDir: path.join(workspaceRoot, 'packages'),
+    themeDir: path.join(workspaceRoot, 'packages', 'theme')
+  };
+};