Skip to content

Commit b69a377

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 60aa20e commit b69a377

File tree

2 files changed

+157
-0
lines changed

2 files changed

+157
-0
lines changed

‎CLAUDE.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,12 @@ Parsing and constructing package URLs, compiled to CommonJS for deployment.
7373
- ❌ WRONG: `pnpm test:unit -- path/to/file.test.js`
7474
- **Update snapshots**: `pnpm test:unit -u` or `pnpm testu`
7575

76+
### CI Testing Infrastructure
77+
- **🚨 MANDATORY**: Use `SocketDev/socket-registry/.github/workflows/ci.yml@main` for consistent CI across Socket projects
78+
- **Reusable workflows**: Socket-registry provides centralized, reusable workflows for lint/type-check/test/coverage
79+
- **Benefits**: Parallel execution, consistent configuration, cross-platform testing
80+
- **Documentation**: See `socket-registry/docs/CI_TESTING_TOOLS.md` for reference
81+
7682
## 📋 PURL-SPECIFIC RULES
7783

7884
### 1. Package URL Standards

‎docs/CI_TESTING.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
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+
node-versions: '[20, 22, 24]'
40+
os-versions: '["ubuntu-latest", "windows-latest"]'
41+
test-script: 'pnpm run test'
42+
lint-script: 'pnpm run check:lint'
43+
type-check-script: 'pnpm run check:tsc'
44+
timeout-minutes: 10
45+
```
46+
47+
**Note**: For projects still using local reusable workflows (`.github/workflows/_reusable-test.yml`), migrate to socket-registry's centralized workflow.
48+
49+
## Configuration Options
50+
51+
### Input Parameters
52+
53+
| Parameter | Description | Default |
54+
|-----------|-------------|---------|
55+
| `node-versions` | Array of Node.js versions to test | `[20, 22, 24]` |
56+
| `os-versions` | Array of operating systems | `["ubuntu-latest", "windows-latest"]` |
57+
| `test-script` | Test command to execute | `pnpm run test` |
58+
| `lint-script` | Lint command to execute | `pnpm run check:lint` |
59+
| `type-check-script` | Type check command to execute | `pnpm run check:tsc` |
60+
| `timeout-minutes` | Job timeout in minutes | `10` |
61+
| `upload-artifacts` | Upload test artifacts | `false` |
62+
| `fail-fast` | Cancel all jobs if one fails | `true` |
63+
| `max-parallel` | Maximum parallel jobs | `4` |
64+
| `continue-on-error` | Continue on job failure | `false` |
65+
66+
## Environment Variables
67+
68+
| Variable | Purpose |
69+
|----------|---------|
70+
| `CI` | Detect CI environment |
71+
| `NODE_OPTIONS` | Node.js runtime options |
72+
| `DEBUG` | Enable debug logging |
73+
74+
## Best Practices
75+
76+
### 1. Use Centralized Workflow
77+
78+
Always use socket-registry's centralized CI workflow for consistency:
79+
```yaml
80+
uses: SocketDev/socket-registry/.github/workflows/ci.yml@main
81+
```
82+
83+
### 2. Configure Timeouts
84+
85+
Set appropriate timeouts for your test suite:
86+
```yaml
87+
timeout-minutes: 10 # Adjust based on suite size
88+
```
89+
90+
### 3. Platform-Specific Tests
91+
92+
Use matrix exclude for platform-specific issues if needed.
93+
94+
### 4. Debug Mode
95+
96+
Enable debug mode for troubleshooting:
97+
```yaml
98+
debug: '1'
99+
```
100+
101+
## Local Testing
102+
103+
### Run Full Test Suite
104+
```bash
105+
pnpm test
106+
```
107+
108+
### Run with Coverage
109+
```bash
110+
pnpm coverage
111+
```
112+
113+
### Run Linting
114+
```bash
115+
pnpm check:lint
116+
```
117+
118+
### Run Type Checking
119+
```bash
120+
pnpm check:tsc
121+
```
122+
123+
### Run All Checks
124+
```bash
125+
pnpm check
126+
```
127+
128+
## Troubleshooting
129+
130+
### Test Timeouts
131+
132+
1. Increase `timeout-minutes` in workflow
133+
2. Review individual test timeouts
134+
3. Check for slow operations
135+
136+
### Coverage Gaps
137+
138+
1. Run `pnpm coverage` locally
139+
2. Review coverage reports
140+
3. Add tests for uncovered code paths
141+
142+
## Integration with socket-registry
143+
144+
This project uses socket-registry's centralized CI infrastructure:
145+
- **CI Workflow**: `SocketDev/socket-registry/.github/workflows/ci.yml@main`
146+
- **Cross-platform compatibility**: Follows socket-registry guidelines
147+
- **Memory optimization**: Aligned with socket-registry patterns
148+
149+
**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 purl projects. See `socket-registry/docs/CI_TESTING_TOOLS.md` and `socket-registry/docs/PACKAGE_TESTING_GUIDE.md` for details.
150+
151+
For consistency across Socket projects, follow the patterns established in socket-registry/CLAUDE.md and documented here.

0 commit comments

Comments
 (0)