docs: add E2E test documentation to README, CONTRIBUTING, and AGENTS (#84)

🖥️ IDE: [Cursor](https://cursor.sh)
🔌 Extension: [Claude Code](https://claude.ai/download)


Model-Raw: claude-opus-4-5-20251101

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: nullvariant

AGENTS.md

@@ -4,3 +4,64 @@
 - Scope: the entire monorepo (root-level AGENTS.md).
 - Keep changes minimal and consistent with existing project conventions.
 - Do not modify files unrelated to the requested task.
+
+## Branch Protection
+
+- **main branch**: Direct push is disabled. All changes must go through a Pull Request.
+- **CI checks**: The `build` check must pass before merging.
+- **Signed commits**: Required on main (handled by maintainers during merge).
+
+## Release Process
+
+Extensions are automatically published to VS Code Marketplace and Open VSX when a release tag is pushed.
+
+AI agents should NOT:
+
+- Push release tags
+- Modify version numbers in package.json without explicit instruction
+- Run `vsce publish` or similar commands
+
+Release tags follow the format: `git-id-switcher-v1.0.0`
+
+## Testing
+
+### Requirements
+
+- Node.js 20+
+
+### Running Tests
+
+```bash
+cd extensions/git-id-switcher
+
+# Unit tests (fast, no VS Code required)
+npm run test
+
+# E2E tests (requires VS Code download on first run)
+npm run test:e2e
+
+# All tests
+npm run test && npm run test:e2e
+```
+
+### Test Strategy
+
+| Test Type  | Target                                       | When to Use                |
+|------------|----------------------------------------------|----------------------------|
+| Unit Tests | Pure functions, utilities, validation        | Fast feedback, edge cases  |
+| E2E Tests  | VS Code API integration, extension lifecycle | Real behavior verification |
+
+### Adding E2E Tests
+
+E2E test files are in `extensions/git-id-switcher/src/test/e2e/`. Guidelines:
+
+1. **No mocks**: Use real VS Code APIs and Git commands
+2. **Cleanup**: Remove temporary files/repos after tests
+3. **Isolation**: Each test should be independent
+4. **Naming**: Use descriptive test names that explain the scenario
+
+### CI/CD
+
+- Unit tests: Must pass to merge PR
+- E2E tests: Run in parallel with build, currently non-blocking (`continue-on-error: true`)
+- E2E uses `xvfb-run` for headless execution on Linux

CONTRIBUTING.md

@@ -52,10 +52,52 @@ npm run watch
 
 ## Testing
 
+### Manual Testing
+
 1. Open the extension folder in VS Code
 2. Press `F5` to launch Extension Development Host
 3. Test your changes manually
 
+### Unit Tests
+
+```bash
+cd extensions/git-id-switcher
+npm run test
+```
+
+### E2E Tests
+
+E2E (End-to-End) tests run in an actual VS Code environment using `@vscode/test-electron` and verify the extension works correctly as a whole.
+
+#### Requirements
+
+- Node.js 20+
+- On first run, VS Code will be downloaded automatically (~100MB)
+
+#### Running E2E Tests
+
+```bash
+cd extensions/git-id-switcher
+npm run test:e2e
+```
+
+#### Adding E2E Tests
+
+E2E test files are located in `src/test/e2e/`. When adding new E2E tests:
+
+1. Create a test file in `src/test/e2e/` (e.g., `myFeature.test.ts`)
+2. Use the VS Code Test API (`@vscode/test-electron`)
+3. Test real extension behavior without mocks
+4. Clean up any test data after tests complete
+
+#### CI/CD Integration
+
+E2E tests run automatically in GitHub Actions CI:
+
+- Executed in parallel with the build job
+- Uses `xvfb-run` for headless execution on Linux
+- Currently set as non-blocking (`continue-on-error: true`)
+
 ## Pull Request Guidelines
 
 - Describe what your PR does

README.md

@@ -62,10 +62,30 @@ npm run package
 
 ### Testing locally
 
+#### Manual Testing
+
 1. Open the extension folder in VS Code
 2. Press `F5` to launch Extension Development Host
 3. Test the extension in the new window
 
+#### Unit Tests
+
+```bash
+cd extensions/git-id-switcher
+npm run test
+```
+
+#### E2E Tests
+
+E2E tests run in an actual VS Code environment using `@vscode/test-electron`:
+
+```bash
+cd extensions/git-id-switcher
+npm run test:e2e
+```
+
+> **Note**: On first run, VS Code will be downloaded automatically (~100MB). Subsequent runs use the cached version.
+
 ### Git Hooks Setup
 
 This repository uses custom git hooks for release safety. After cloning, run: