Skip to content

Commit e461b3d

Browse files
jdaltonjdalton
committed
Add CI testing infrastructure documentation
Add CI_TESTING.md guide and update CLAUDE.md to reference socket-registry's centralized workflows
1 parent d126393 commit e461b3d

File tree

3 files changed

+257
-7
lines changed

3 files changed

+257
-7
lines changed

‎CLAUDE.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,12 @@ Each command follows consistent pattern:
103103
- Single file: ✅ CORRECT: `pnpm run testu src/commands/specific/cmd-file.test.mts`
104104
- ❌ WRONG: `pnpm run testu -- src/commands/specific/cmd-file.test.mts`
105105

106+
### CI Testing Infrastructure
107+
- **🚨 MANDATORY**: Use `SocketDev/socket-registry/.github/workflows/ci.yml@main` for consistent CI across Socket projects
108+
- **Reusable workflows**: Socket-registry provides centralized, reusable workflows for lint/type-check/test/coverage
109+
- **Benefits**: Parallel execution, consistent configuration, cross-platform testing
110+
- **Documentation**: See `docs/CI_TESTING.md` and `socket-registry/docs/CI_TESTING_TOOLS.md`
111+
106112
## 🎨 CLI-SPECIFIC CODE PATTERNS
107113

108114
### File Structure

‎docs/CI_TESTING.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
# CI Testing Guide
2+
3+
## Overview
4+
5+
This project uses socket-registry's centralized CI testing infrastructure. The solution provides:
6+
7+
- **🚨 MANDATORY**: Use `SocketDev/socket-registry/.github/workflows/ci.yml@main` for consistent CI
8+
- **Multi-platform testing**: Linux, Windows, and macOS support
9+
- **Multi-version Node.js matrix**: Test across Node.js 20, 22, and 24
10+
- **Flexible configuration**: Customizable test scripts, timeouts, and artifact uploads
11+
- **Memory optimization**: Configured heap sizes for CI and local environments
12+
- **Cross-platform compatibility**: Handles Windows and POSIX path differences
13+
14+
**For socket-registry-specific package testing tools**, see `socket-registry/docs/CI_TESTING_TOOLS.md` and `socket-registry/docs/PACKAGE_TESTING_GUIDE.md`. These tools (`validate:packages`, `validate:ci`) are specific to socket-registry's package override structure.
15+
16+
## Workflow Structure
17+
18+
### Centralized CI Workflow
19+
20+
**🚨 MANDATORY**: Use `SocketDev/socket-registry/.github/workflows/ci.yml@main` for consistent CI across all Socket projects.
21+
22+
**Key Features:**
23+
- Matrix testing across Node.js versions and operating systems
24+
- Parallel execution of lint, type-check, test, and coverage
25+
- Configurable scripts for project-specific requirements
26+
- Artifact upload support for coverage reports
27+
- Debug mode for verbose logging
28+
- Timeout protection for long-running tests
29+
30+
### Main Test Workflow
31+
32+
Located at `.github/workflows/test.yml`, this workflow calls socket-registry's reusable CI workflow:
33+
34+
```yaml
35+
jobs:
36+
test:
37+
uses: SocketDev/socket-registry/.github/workflows/ci.yml@main
38+
with:
39+
setup-script: 'pnpm run build:dist:src'
40+
node-versions: '[20, 22, 24]'
41+
os-versions: '["ubuntu-latest", "windows-latest", "macos-latest"]'
42+
test-script: 'pnpm run test:unit'
43+
lint-script: 'pnpm run check:lint'
44+
type-check-script: 'pnpm run check:tsc'
45+
timeout-minutes: 15
46+
```
47+
48+
**Note**: For projects still using local reusable workflows (`.github/workflows/_reusable-test.yml`), migrate to socket-registry's centralized workflow.
49+
50+
## Configuration Options
51+
52+
### Input Parameters
53+
54+
| Parameter | Description | Default |
55+
|-----------|-------------|---------|
56+
| `node-versions` | Array of Node.js versions to test | `[20, 22, 24]` |
57+
| `os-versions` | Array of operating systems | `["ubuntu-latest", "windows-latest"]` |
58+
| `test-script` | Test command to execute | `pnpm run test:unit` |
59+
| `setup-script` | Pre-test setup command | `pnpm run build:dist:src` |
60+
| `lint-script` | Lint command to execute | `pnpm run check:lint` |
61+
| `type-check-script` | Type check command to execute | `pnpm run check:tsc` |
62+
| `timeout-minutes` | Job timeout in minutes | `15` |
63+
| `upload-artifacts` | Upload test artifacts | `false` |
64+
| `fail-fast` | Cancel all jobs if one fails | `true` |
65+
| `max-parallel` | Maximum parallel jobs | `4` |
66+
| `continue-on-error` | Continue on job failure | `false` |
67+
68+
## CLI-Specific Testing Requirements
69+
70+
### Build Before Tests
71+
72+
**🚨 CRITICAL**: Always build before running tests:
73+
```bash
74+
pnpm run build:dist:src
75+
```
76+
77+
The CLI relies on compiled TypeScript outputs in `dist/` directory. Tests will fail if build artifacts are missing or stale.
78+
79+
### Test File Patterns
80+
81+
- **Source tests**: `src/**/*.test.mts`
82+
- **Test naming**: Match source file (e.g., `cmd-scan.test.mts` for `cmd-scan.mts`)
83+
- **Update snapshots**: Use `pnpm run testu` (not `pnpm test -u`)
84+
85+
## Environment Variables
86+
87+
| Variable | Purpose |
88+
|----------|---------|
89+
| `CI` | Detect CI environment |
90+
| `NODE_OPTIONS` | Node.js runtime options |
91+
| `DEBUG` | Enable debug logging |
92+
93+
## Best Practices
94+
95+
### 1. Use Centralized Workflow
96+
97+
Always use socket-registry's centralized CI workflow for consistency:
98+
```yaml
99+
uses: SocketDev/socket-registry/.github/workflows/ci.yml@main
100+
```
101+
102+
### 2. Configure Timeouts
103+
104+
Set appropriate timeouts for your test suite:
105+
```yaml
106+
timeout-minutes: 15 # CLI tests may take longer
107+
```
108+
109+
### 3. Platform-Specific Tests
110+
111+
CLI tools need thorough cross-platform testing:
112+
- Linux: Primary development platform
113+
- Windows: Different path handling, shell behavior
114+
- macOS: Apple Silicon and Intel compatibility
115+
116+
### 4. Build Artifacts
117+
118+
Include `setup-script` to ensure fresh builds:
119+
```yaml
120+
setup-script: 'pnpm run build:dist:src'
121+
```
122+
123+
### 5. Debug Mode
124+
125+
Enable debug mode for troubleshooting:
126+
```yaml
127+
debug: '1'
128+
```
129+
130+
## Local Testing
131+
132+
### Full Test Flow
133+
```bash
134+
# Build source files
135+
pnpm run build:dist:src
136+
137+
# Run all tests
138+
pnpm run test:unit
139+
140+
# Run with coverage
141+
pnpm run coverage
142+
```
143+
144+
### Run Specific Tests
145+
```bash
146+
# Test single file (after build)
147+
pnpm run test:unit src/commands/scan/cmd-scan.test.mts
148+
```
149+
150+
### Update Snapshots
151+
```bash
152+
# Update all snapshots
153+
pnpm run testu
154+
155+
# Update specific file
156+
pnpm run testu src/commands/scan/cmd-scan.test.mts
157+
```
158+
159+
### Run Linting and Type Checking
160+
```bash
161+
# Lint
162+
pnpm run check:lint
163+
164+
# Type check (uses tsgo)
165+
pnpm run check:tsc
166+
167+
# Run all checks
168+
pnpm run check
169+
```
170+
171+
### Run CLI Locally
172+
```bash
173+
# Build and run
174+
pnpm run build && pnpm exec socket
175+
176+
# Quick build (source only) and run
177+
pnpm run bs
178+
179+
# Run without rebuild
180+
pnpm run s
181+
```
182+
183+
## Troubleshooting
184+
185+
### Build Artifacts Missing
186+
187+
**Problem**: Tests fail with module resolution errors
188+
189+
**Solution**: Run `pnpm run build:dist:src` before testing
190+
191+
---
192+
193+
### Test Timeouts
194+
195+
**Problem**: Tests timeout in CI
196+
197+
**Solution**:
198+
1. Increase `timeout-minutes` in workflow
199+
2. Check for slow operations or hanging promises
200+
3. Review snapshot update times
201+
202+
---
203+
204+
### Windows Path Issues
205+
206+
**Problem**: Tests fail on Windows only
207+
208+
**Solution**:
209+
1. Use `path.join()` instead of string concatenation
210+
2. Use `path.sep` instead of hard-coded `/` or `\`
211+
3. Check for POSIX-specific assumptions
212+
213+
---
214+
215+
### Coverage Gaps
216+
217+
**Problem**: Coverage reports show gaps
218+
219+
**Solution**:
220+
1. Run `pnpm coverage` locally
221+
2. Review untested code paths
222+
3. Add tests for edge cases
223+
224+
## Integration with socket-registry
225+
226+
This project uses socket-registry's centralized CI infrastructure:
227+
- **CI Workflow**: `SocketDev/socket-registry/.github/workflows/ci.yml@main`
228+
- **Cross-platform compatibility**: Follows socket-registry guidelines
229+
- **Memory optimization**: Aligned with socket-registry patterns
230+
- **Build requirements**: Pre-test builds are CLI-specific
231+
232+
**Socket-registry-specific tools**: The `validate:packages` and `validate:ci` scripts in socket-registry are specific to its package override structure and not applicable to CLI projects. See `socket-registry/docs/CI_TESTING_TOOLS.md` and `socket-registry/docs/PACKAGE_TESTING_GUIDE.md` for details.
233+
234+
For consistency across Socket projects, follow the patterns established in socket-registry/CLAUDE.md and documented here.
235+
236+
## CLI-Specific Notes
237+
238+
### Shadow Binaries
239+
240+
The `shadow-bin/` directory contains npm/npx wrapper scripts. These are not TypeScript files and don't require compilation.
241+
242+
### TypeScript Native Support
243+
244+
The `./sd` script uses Node.js 22+ native TypeScript support for faster local development iterations.
245+
246+
### Build Output
247+
248+
- **Source**: `dist/esm/` - Compiled TypeScript
249+
- **Types**: `dist/types/` - Type definitions
250+
- Both directories are required for tests to pass

‎test/paths.test.mts‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -137,13 +137,7 @@ describe('paths module', () => {
137137
it('should return CLI updater state JSON path', () => {
138138
const result = getSocketCliUpdaterStateJsonPath()
139139
expect(result).toBe(
140-
path.join(
141-
os.homedir(),
142-
'.socket',
143-
'_socket',
144-
'updater',
145-
'state.json',
146-
),
140+
path.join(os.homedir(), '.socket', '_socket', 'updater', 'state.json'),
147141
)
148142
})
149143

0 commit comments

Comments
 (0)