@@ -35,12 +35,14 @@ The tests create a temporary git repository, start a claude-sandbox instance, pe
3535## Running Tests
3636
3737### Quick Test (Recommended)
38+
3839``` bash
3940# Run core functionality tests
4041node core-functionality-test.js
4142```
4243
4344### Individual Tests
45+
4446``` bash
4547# Test repository to container sync
4648node repo-to-container-sync-test.js
@@ -53,6 +55,7 @@ node test-suite.js
5355```
5456
5557### Automated Test Runner
58+
5659``` bash
5760# Run all tests with cleanup
5861./run-tests.sh
@@ -67,11 +70,13 @@ node test-suite.js
6770## Test Process
6871
69721 . ** Setup Phase**
73+
7074 - Creates temporary git repository with dummy files
7175 - Starts claude-sandbox instance
7276 - Connects to web UI for monitoring sync events
7377
74782 . ** Test Execution**
79+
7580 - Performs file operations inside the container
7681 - Waits for synchronization to complete
7782 - Verifies shadow repository state
@@ -84,13 +89,15 @@ node test-suite.js
8489## Key Features Tested
8590
8691### Repository to Container Sync
92+
8793- ✅ One-to-one file mapping from test repo to container
8894- ✅ No extra files in container (only test repo files)
8995- ✅ File content integrity verification
9096- ✅ Git repository properly initialized
9197- ✅ Correct branch creation
9298
9399### File Synchronization
100+
94101- ✅ New file creation and content sync
95102- ✅ File modification and content updates
96103- ✅ File deletion and proper removal
@@ -99,12 +106,14 @@ node test-suite.js
99106- ✅ Special characters in filenames
100107
101108### Git Integration
109+
102110- ✅ Staging of additions (` A ` status)
103111- ✅ Tracking of modifications (` M ` status)
104112- ✅ Detection of deletions (` D ` status)
105113- ✅ Proper git commit workflow
106114
107115### Web UI Integration
116+
108117- ✅ Real-time sync event notifications
109118- ✅ Change summary reporting
110119- ✅ WebSocket communication
@@ -114,25 +123,30 @@ node test-suite.js
114123### Common Issues
115124
116125** Container startup timeout**
126+
117127- Increase timeout values in test framework
118128- Check Docker daemon is running
119129- Verify claude-sandbox image exists
120130
121131** Git lock conflicts**
132+
122133- Tests automatically handle concurrent git operations
123134- Temporary ` .git/index.lock ` files are cleaned up
124135
125136** Port conflicts**
137+
126138- Tests use dynamic port allocation
127139- Multiple tests can run sequentially
128140
129141** WebSocket connection issues**
142+
130143- Framework includes connection retry logic
131144- Fallback to polling if WebSocket fails
132145
133146### Test Failure Analysis
134147
135148Tests provide detailed error messages indicating:
149+
136150- Which specific operation failed
137151- Expected vs actual file states
138152- Git status differences
@@ -145,33 +159,36 @@ Tests provide detailed error messages indicating:
1451591 . Create test function in appropriate test file
1461602 . Use framework methods for file operations:
147161 ``` javascript
148- await framework .addFile (' path/file.txt' , ' content' );
149- await framework .modifyFile (' path/file.txt' , ' new content' );
150- await framework .deleteFile (' path/file.txt' );
162+ await framework .addFile (" path/file.txt" , " content" );
163+ await framework .modifyFile (" path/file.txt" , " new content" );
164+ await framework .deleteFile (" path/file.txt" );
151165 ```
1521663 . Verify results using assertion methods:
153167 ``` javascript
154- const exists = await framework .shadowFileExists (' file.txt' );
155- const content = await framework .getShadowFileContent (' file.txt' );
168+ const exists = await framework .shadowFileExists (" file.txt" );
169+ const content = await framework .getShadowFileContent (" file.txt" );
156170 const gitStatus = await framework .getGitStatus ();
157171 ```
158172
159173### Framework API
160174
161175** File Operations**
176+
162177- ` addFile(path, content) ` - Create new file
163- - ` modifyFile(path, content) ` - Update existing file
178+ - ` modifyFile(path, content) ` - Update existing file
164179- ` deleteFile(path) ` - Remove file
165180- ` moveFile(from, to) ` - Rename/move file
166181- ` createDirectory(path) ` - Create directory
167182
168183** Verification Methods**
184+
169185- ` shadowFileExists(path) ` - Check file existence
170186- ` getShadowFileContent(path) ` - Read file content
171187- ` getGitStatus() ` - Get git status output
172188- ` waitForSync() ` - Wait for synchronization
173189
174190** Event Monitoring**
191+
175192- ` receivedSyncEvents ` - Array of sync notifications
176193- WebSocket connection automatically established
177194
@@ -188,4 +205,4 @@ These tests are designed to run in automated environments:
188205 ./run-tests.sh
189206` ` `
190207
191- The tests provide proper exit codes (0 for success, 1 for failure) and detailed logging for debugging purposes.
208+ The tests provide proper exit codes (0 for success, 1 for failure) and detailed logging for debugging purposes.
0 commit comments