@sfdc-webapps/cli 1.0.2

package/test/e2e/E2E_TEST_FIXTURES.md

@@ -0,0 +1,509 @@
+# E2E Test Fixtures and Gold Files - Current State
+
+**Last Updated:** 2025-12-15
+
+## Overview
+
+This document provides a comprehensive, accurate summary of all E2E test fixtures, test cases, and gold files in `packages/cli/test/e2e/`.
+
+### Quick Stats
+
+- **Total Fixtures:** 55 feature fixtures + 1 base app = 56 total
+- **Test Suites:** 16 describe blocks
+- **Test Cases:** 36 individual tests
+- **Gold File Directories:** 6
+- **Fixture Categories:** 13
+
+---
+
+## Directory Structure
+
+```
+packages/cli/test/e2e/
+├── apply-patches.spec.ts          # Main test file (36 tests)
+├── E2E_TEST_FIXTURES.md           # This file
+├── fixtures/                      # All test fixtures (56 total)
+│   ├── base-app/                  # Base React app (1)
+│   ├── basic-operations/          # Renamed original fixtures (4)
+│   ├── composition-5-features/    # Multi-feature composition (5)
+│   ├── composition-append/        # Multiple append operations (3)
+│   ├── composition-inherit-modify/# Inherit + modify pattern (2)
+│   ├── composition-prepend/       # Multiple prepend operations (3)
+│   ├── dep-chain-long/           # Long dependency chain (4)
+│   ├── dep-circular/             # Circular dependency detection (2)
+│   ├── dep-complex-graph/        # Complex multi-branch deps (7)
+│   ├── dep-diamond/              # Diamond dependency pattern (3)
+│   ├── edges/                    # Edge cases and error handling (9)
+│   ├── scenarios/                # Real-world feature scenarios (3)
+│   ├── single-operations/        # Single operation tests (5)
+│   └── watch/                    # Watch mode tests (4)
+└── gold/                         # Expected output for regression tests (6)
+    ├── dep-chain-linear-apply/
+    ├── dep-chain-long-apply/
+    ├── dep-complex-graph-apply/
+    ├── feature-file-inherit-route-add-apply/
+    ├── feature-file-prepend-append-apply/
+    └── feature-file-route-delete-apply/
+```
+
+---
+
+## Fixture Categories
+
+### 1. Base App (1 fixture)
+
+**Location:** `fixtures/base-app/`
+
+- **base-app** - Base React application used as the starting point for all tests
+  - Contains: `src/appLayout.tsx`, `src/home.tsx`, `src/old-page.tsx`, `src/routes.tsx`, `src/styles/global.css`, `package.json`
+
+### 2. Basic Operations (4 fixtures)
+
+**Location:** `fixtures/basic-operations/`
+
+These are the original fixtures that were renamed for clarity:
+
+- **dep-chain-linear** - Tests linear dependency resolution (depends on feature-file-inherit-route-add)
+  - Adds: `src/contact.tsx` and contact route
+  - Gold File: ✅ `dep-chain-linear-apply/`
+
+- **feature-file-inherit-route-add** - Tests file inheritance (`__inherit__`) and route addition
+  - Adds: `src/about.tsx`, modifies `src/routes.tsx`
+  - Gold File: ✅ `feature-file-inherit-route-add-apply/`
+
+- **feature-file-prepend-append** - Tests `__prepend__` and `__append__` operations
+  - Prepends to: `src/index.tsx`
+  - Appends to: `src/styles/global.css`
+  - Inherits: `src/appLayout.tsx`
+  - Adds: `src/settings.tsx`
+  - Gold File: ✅ `feature-file-prepend-append-apply/`
+
+- **feature-file-route-delete** - Tests file and route deletion with `__delete__`
+  - Deletes: `src/old-page.tsx` and its route
+  - Gold File: ✅ `feature-file-route-delete-apply/`
+
+### 3. Single Operations (5 fixtures)
+
+**Location:** `fixtures/single-operations/`
+
+Each fixture tests ONE specific CLI operation in isolation:
+
+- **feature-file-append** - Only tests `__append__` prefix
+  - Appends to: `src/styles/global.css`
+  - Gold File: ❌ (test uses inline verification)
+
+- **feature-file-inherit** - Only tests `__inherit__` prefix
+  - Inherits: `src/appLayout.tsx`, `src/home.tsx`
+  - Gold File: ❌ (test uses inline verification)
+
+- **feature-file-prepend** - Only tests `__prepend__` prefix
+  - Prepends to: `src/index.tsx`
+  - Gold File: ❌ (test uses inline verification)
+
+- **feature-import-merge** - Tests import statement merging
+  - Modifies: `src/routes.tsx` with merged imports
+  - Adds: `src/settings.tsx`
+  - Gold File: ❌ (test uses inline verification)
+
+- **feature-route-add** - Only tests route addition
+  - Adds: `src/services.tsx` and service route
+  - Gold File: ❌ (test uses inline verification)
+
+### 4. Dependency Resolution Tests
+
+#### 4a. Long Chain (4 fixtures)
+
+**Location:** `fixtures/dep-chain-long/`
+
+Tests deep dependency chains: A → B → C → D
+
+- **dep-chain-a** - Top of chain (depends on dep-chain-b)
+  - Adds: `src/page-a.tsx`
+- **dep-chain-b** - Second level (depends on dep-chain-c)
+  - Adds: `src/page-b.tsx`
+- **dep-chain-c** - Third level (depends on dep-chain-d)
+  - Adds: `src/page-c.tsx`
+- **dep-chain-d** - Base of chain (no dependencies)
+  - Adds: `src/page-d.tsx`
+- Gold File: ✅ `dep-chain-long-apply/`
+
+#### 4b. Diamond Pattern (3 fixtures)
+
+**Location:** `fixtures/dep-diamond/`
+
+Tests shared dependencies: left → shared ← right
+
+- **dep-diamond-shared** - Shared base dependency
+  - Adds: `src/shared-utils.tsx`
+- **dep-diamond-left** - Left branch (depends on shared)
+  - Adds: `src/left-page.tsx`
+- **dep-diamond-right** - Right branch (depends on shared)
+  - Adds: `src/right-page.tsx`
+- Gold File: ❌ (test verifies both branches separately)
+
+#### 4c. Circular Dependencies (2 fixtures)
+
+**Location:** `fixtures/dep-circular/`
+
+Tests circular dependency detection and error handling:
+
+- **dep-circular-a** - Depends on dep-circular-b
+- **dep-circular-b** - Depends on dep-circular-a (creates cycle)
+- Gold File: ❌ (test expects error/rejection)
+
+#### 4d. Complex Multi-Branch Graph (7 fixtures)
+
+**Location:** `fixtures/dep-complex-graph/`
+
+Tests complex dependency graph with multiple branches and transitive dependencies:
+
+```
+dep-complex-graph (parent)
+  ├─→ dep-complex-graph-auth (depends on utils, types)
+  ├─→ dep-complex-graph-dashboard (depends on utils, components)
+  └─→ dep-complex-graph-profile (depends on components, types)
+
+Shared dependencies:
+  ├─ dep-complex-graph-shared-utils
+  ├─ dep-complex-graph-shared-types
+  └─ dep-complex-graph-shared-components (depends on utils + types)
+```
+
+- **dep-complex-graph** - Parent/meta feature
+- **dep-complex-graph-auth** - Auth feature with login, signup
+- **dep-complex-graph-dashboard** - Dashboard with analytics, reports
+- **dep-complex-graph-profile** - Profile with edit functionality
+- **dep-complex-graph-shared-utils** - Shared utilities
+- **dep-complex-graph-shared-types** - Shared types
+- **dep-complex-graph-shared-components** - Shared components
+- Gold File: ✅ `dep-complex-graph-apply/`
+
+### 5. Composition Tests
+
+Tests multiple features working together on the same codebase.
+
+#### 5a. Multiple Appends (3 fixtures)
+
+**Location:** `fixtures/composition-append/`
+
+- **composition-append-1** - Appends CSS class 1 to `global.css`
+- **composition-append-2** - Appends CSS class 2 to `global.css`
+- **composition-append-3** - Appends CSS class 3 to `global.css`
+- Gold File: ❌ (test applies sequentially and verifies each)
+
+#### 5b. Multiple Prepends (3 fixtures)
+
+**Location:** `fixtures/composition-prepend/`
+
+- **composition-prepend-1** - Prepends code 1 to `index.tsx`
+- **composition-prepend-2** - Prepends code 2 to `index.tsx`
+- **composition-prepend-3** - Prepends code 3 to `index.tsx`
+- Gold File: ❌ (test applies sequentially and verifies each)
+
+#### 5c. Inherit Then Modify (2 fixtures)
+
+**Location:** `fixtures/composition-inherit-modify/`
+
+- **composition-inherit-layout** - Inherits `appLayout.tsx`
+- **composition-modify-layout** - Appends to `appLayout.tsx`
+- Gold File: ❌ (test verifies pattern works)
+
+#### 5d. Five Features Together (5 fixtures)
+
+**Location:** `fixtures/composition-5-features/`
+
+Tests integration of 5 different features:
+
+- **5-features-about** - Adds about page
+- **5-features-analytics** - Adds analytics
+- **5-features-footer** - Adds footer component
+- **5-features-navigation** - Adds navigation
+- **5-features-theme** - Adds theming
+- Gold File: ❌ (test applies all and verifies existence)
+
+### 6. Real-World Scenarios (3 fixtures)
+
+**Location:** `fixtures/scenarios/`
+
+Complete, production-ready feature implementations:
+
+- **scenario-authentication** - Full authentication system
+  - Components: `AuthContext.tsx`, `LoginForm.tsx`, `login.tsx`
+  - Routes: Login route with auth context
+  - Gold File: ❌ (test verifies all components exist)
+
+- **scenario-crud-contacts** - Complete CRUD contacts feature
+  - Components: `ContactList.tsx`, `ContactDetail.tsx`, `ContactForm.tsx`
+  - API: `contactsApi.ts` with mock CRUD operations
+  - Routes: Nested routes for `/contacts`, `/contacts/:id`, `/contacts/new`, `/contacts/:id/edit`
+  - Styles: Contact list and form styling
+  - Gold File: ❌ (test verifies all components and routes)
+
+- **scenario-navigation-menu** - Dynamic navigation menu
+  - Components: `NavigationMenu.tsx`
+  - Modifies: `appLayout.tsx` to include navigation
+  - Gold File: ❌ (test verifies component exists and integration)
+
+### 7. Edge Cases (9 fixtures)
+
+**Location:** `fixtures/edges/`
+
+Tests error handling, validation, and edge cases:
+
+- **edge-binary-files** - Tests copying binary files (PNG images) with `__inherit__`
+  - Gold File: ❌ (test verifies binary file copied correctly)
+
+- **edge-conflicting-prefixes** - Tests validation catches conflicting prefixes (`__inherit__` + `__delete__`)
+  - Gold File: ❌ (test expects error)
+
+- **edge-empty-feature** - Tests "meta-feature" with only dependencies, no template files
+  - Gold File: ❌ (test verifies dependencies applied)
+
+- **edge-invalid-routes** - Tests validation of route operations (deleting non-existent routes)
+  - Gold File: ❌ (test expects error)
+
+- **edge-line-endings** - Tests CRLF vs LF line ending handling in prepend/append
+  - Gold File: ❌ (test verifies no content corruption)
+
+- **edge-missing-base-files** - Tests error when trying to prepend/append/inherit non-existent files
+  - Gold File: ❌ (test expects error)
+
+- **edge-package-json-conflicts-a** - Feature with `react@18.0.0`
+- **edge-package-json-conflicts-b** - Feature with `react@18.2.0` (creates conflict)
+  - Gold File: ❌ (test expects version conflict error)
+
+- **edge-performance-many** - Tests performance with 12 features applied together
+  - Gold File: ❌ (test verifies completion under 5 seconds)
+
+### 8. Watch Mode (4 fixtures)
+
+**Location:** `fixtures/watch/`
+
+Fixtures for watch mode testing (tests not yet implemented in apply-patches.spec.ts):
+
+- **watch-add-delete-files** - Tests file addition/deletion detection
+- **watch-basic** - Basic watch mode test
+- **watch-debounce** - Tests debouncing of rapid changes
+- **watch-multiple-files** - Tests watching changes across multiple files
+
+**Note:** These fixtures exist but corresponding tests are not yet implemented in `apply-patches.spec.ts`.
+
+---
+
+## Test Suites (16 total)
+
+Test suites are organized in `apply-patches.spec.ts`:
+
+1. **Simple feature application** (2 tests)
+   - Basic feature apply
+   - File existence verification
+
+2. **File deletion** (2 tests)
+   - Delete files with `__delete__`
+   - Clean up imports from deleted files
+
+3. **Route deletion** (1 test)
+   - Delete routes marked with `__delete__`
+
+4. **Dependency resolution** (1 test)
+   - Apply features in dependency order
+
+5. **Complex operations** (2 tests)
+   - Handle `__inherit__`, `__prepend__`, `__append__`
+   - Verify inherited files
+
+6. **Error handling** (2 tests)
+   - Non-existent feature path
+   - Delete non-existent file
+
+7. **Idempotency** (1 test)
+   - Apply patches multiple times safely
+
+8. **Long dependency chains** (1 test)
+   - A → B → C → D chain resolution
+
+9. **Diamond dependencies** (1 test)
+   - Shared dependency applied once
+
+10. **Circular dependencies** (1 test)
+    - Detect and reject circular deps
+
+11. **Complex dependency graph** (1 test)
+    - Multi-branch with transitive deps
+
+12. **Phase 2: Single feature tests** (5 tests)
+    - Prepend-only
+    - Append-only
+    - Route-add
+    - Inherit-only
+    - Import-merge
+
+13. **Phase 4: Composition tests** (5 tests)
+    - Multiple appends to same file
+    - Multiple prepends to same file
+    - Five features together
+    - Inherit then modify
+    - Multiple prepends in order
+
+14. **Phase 5: Real-world scenarios** (3 tests)
+    - Navigation menu feature
+    - Authentication feature
+    - CRUD contacts feature
+
+15. **Phase 6: Edge cases** (9 tests)
+    - Empty feature with dependencies
+    - Conflicting prefixes
+    - Missing base files
+    - Package.json version conflicts
+    - Invalid route operations
+    - Binary files
+    - Line endings (CRLF vs LF)
+    - Performance with many features
+
+**Total: 36 test cases**
+
+---
+
+## Gold Files (6 directories)
+
+Gold files provide expected output for regression testing. When tests run with `UPDATE_GOLD=1`, they regenerate these files.
+
+### Existing Gold Files
+
+1. **dep-chain-linear-apply/** - Expected output for linear dependency chain
+2. **dep-chain-long-apply/** - Expected output for long dependency chain (A→B→C→D)
+3. **dep-complex-graph-apply/** - Expected output for complex dependency graph
+4. **feature-file-inherit-route-add-apply/** - Expected output for inherit + route add
+5. **feature-file-prepend-append-apply/** - Expected output for prepend + append
+6. **feature-file-route-delete-apply/** - Expected output for file/route deletion
+
+### Gold Files Not Yet Created
+
+The following tests could benefit from gold files but currently use inline assertions:
+
+- Single operation tests (5 tests)
+- Diamond dependency tests
+- Composition tests (multiple appends, prepends, etc.)
+- Real-world scenario tests (3 tests)
+- Edge case tests (most use error assertions)
+
+---
+
+## Test Execution
+
+### Run All Tests
+
+```bash
+cd packages/cli
+npm test apply-patches.spec.ts
+# or
+yarn test apply-patches.spec.ts
+```
+
+### Update/Generate Gold Files
+
+```bash
+cd packages/cli
+UPDATE_GOLD=1 npm test apply-patches.spec.ts
+```
+
+### Run Specific Test Suite
+
+```bash
+cd packages/cli
+npm test apply-patches.spec.ts -t "Complex dependency graph"
+```
+
+### Run Specific Test
+
+```bash
+cd packages/cli
+npm test apply-patches.spec.ts -t "should apply a simple feature correctly"
+```
+
+---
+
+## Coverage Analysis
+
+### What's Well Tested ✅
+
+- ✅ Basic file operations (inherit, prepend, append, delete)
+- ✅ Route operations (add, delete, merge)
+- ✅ Import merging
+- ✅ Linear dependency chains
+- ✅ Long dependency chains (4 levels)
+- ✅ Diamond dependency patterns
+- ✅ Circular dependency detection
+- ✅ Complex multi-branch dependencies
+- ✅ Feature composition (multiple features together)
+- ✅ Real-world scenarios (auth, CRUD, navigation)
+- ✅ Edge cases (binary files, line endings, performance)
+- ✅ Error handling and validation
+
+### What's Not Yet Tested ❌
+
+- ❌ Watch mode functionality (fixtures exist, tests don't)
+- ❌ Some edge cases may need additional gold files
+- ❌ Package.json merging edge cases
+- ❌ Concurrent feature application
+
+### Gold File Coverage
+
+- **With Gold Files:** 6/36 tests (17%)
+- **Without Gold Files:** 30/36 tests (83%) - use inline assertions
+
+**Note:** Most tests use inline assertions rather than gold files. This is intentional for tests that verify specific behaviors (errors, validation) rather than complete output snapshots.
+
+---
+
+## Fixture Naming Conventions
+
+Fixtures follow consistent naming patterns:
+
+- `basic-operations/` - Original fixtures, renamed for clarity
+- `single-operations/feature-*` - Single operation tests
+- `dep-*` - Dependency resolution tests
+- `composition-*` - Multiple feature composition tests
+- `scenario-*` - Real-world feature scenarios
+- `edge-*` - Edge cases and error handling
+- `watch-*` - Watch mode tests
+- Numbers: `5-features-*`, `composition-append-1/2/3` - Sequential/grouped fixtures
+
+---
+
+## Adding New Fixtures
+
+When adding new fixtures:
+
+1. **Create fixture directory** in appropriate category
+2. **Add `feature.ts`** with configuration and dependencies
+3. **Add template files** in `template/digitalExperiences/webApplications/[feature-name]/`
+4. **Add test case** in `apply-patches.spec.ts`
+5. **Consider gold files** if testing complete output (not just specific behaviors)
+6. **Update this document** with new fixture details
+
+---
+
+## Maintenance Notes
+
+### Last Major Changes
+
+- Restructured from 5 original fixtures to 55 organized fixtures
+- Added comprehensive dependency resolution tests
+- Added real-world scenario fixtures
+- Added extensive edge case coverage
+
+### Known Issues
+
+- Watch mode fixtures exist but tests not implemented yet
+- Some tests could benefit from gold files for better regression testing
+- Package.json conflict testing is basic, could be expanded
+
+---
+
+## References
+
+- Main test file: `packages/cli/test/e2e/apply-patches.spec.ts`
+- Fixtures: `packages/cli/test/e2e/fixtures/`
+- Gold files: `packages/cli/test/e2e/gold/`
+- Test helpers: `packages/cli/test/helpers/`