- add cargo fmt / clippy to actions build. - add common unit tests. -

improved security sanitization - security spcecific unit tests - add unit tests to workflow build - add unami analytics.
2025-11-30 01:37:07 -08:00
parent 9fb9d9ab50
commit 850cf32b50
15 changed files with 2678 additions and 40 deletions
@@ -0,0 +1,177 @@
+# WebTerm Test Suite
+
+This directory contains the unit and integration tests for the socktop webterm project.
+
+## Test Structure
+
+Tests are organized into separate files by module:
+
+### `event_tests.rs`
+Tests for the `event` module, covering:
+- **IO message creation**: Testing conversion from Bytes, String, and &str
+- **IO equality and cloning**: Verifying proper equality checks and clone behavior
+- **Binary and Unicode data**: Testing handling of binary data and Unicode strings
+- **ChildDied events**: Testing the ChildDied event structure
+
+**Total tests**: 11
+
+### `terminado_tests.rs`
+Comprehensive tests for the Terminado protocol implementation:
+- **Serialization**: Converting TerminadoMessage to JSON format
+  - `stdin`, `stdout`, and `set_size` (resize) messages
+  - Special characters, Unicode, and empty strings
+- **Deserialization**: Parsing JSON into TerminadoMessage
+  - Valid message formats
+  - Error handling for invalid JSON, wrong types, wrong lengths
+- **Round-trip testing**: Serialize → Deserialize → Compare
+- **Error cases**: Testing all failure modes
+  - Invalid JSON
+  - Wrong array lengths
+  - Non-string types where strings expected
+  - Unknown message types
+
+**Total tests**: 38
+
+### `config_tests.rs`
+Integration tests verifying configuration constants and relationships:
+- **Timeout values**: Heartbeat, client timeout, idle timeout
+- **Timeout relationships**: Ensuring timeouts have logical relationships
+- **PTY configuration**: Initial size, buffer sizes
+- **Path validation**: Template paths, static paths, endpoints
+- **Network configuration**: Default ports, hosts
+- **Size boundaries**: Terminal size limits and validation
+
+**Total tests**: 17
+
+### `security_tests.rs`
+Comprehensive security tests for command sanitization and validation:
+- **Command path validation**: Absolute paths, no path traversal, no shell metacharacters
+- **Shell injection prevention**: Detecting and rejecting injection attempts
+- **Environment variable security**: Sanitizing TERM and other env vars
+- **Whitelist enforcement**: Only allowing approved shell commands
+- **Path traversal prevention**: Blocking `..`, `./`, `~` patterns
+- **Input validation**: Length limits, null byte detection, control characters
+- **File descriptor security**: No redirection operators in commands
+- **Unicode and special characters**: ASCII-only enforcement
+- **Dangerous directory prevention**: Blocking execution from `/tmp`, `/var/tmp`, etc.
+- **Command execution logging**: Ensuring commands are safely loggable
+- **Integration with Command::new()**: Verifying safe process spawning
+- **Complete security checklist**: Comprehensive validation of all security requirements
+
+**Total tests**: 28 (plus 11 in `src/security.rs`)
+
+## Running Tests
+
+### Run all tests
+```bash
+cargo test --all-targets --all-features
+```
+
+### Run specific test file
+```bash
+cargo test --test event_tests
+cargo test --test terminado_tests
+cargo test --test config_tests
+```
+
+### Run with output
+```bash
+cargo test -- --nocapture
+```
+
+### Run specific test
+```bash
+cargo test test_serialize_resize
+```
+
+## Test Coverage
+
+Current test coverage includes:
+
+- ✅ **Event handling**: IO messages and ChildDied events
+- ✅ **Protocol parsing**: Terminado message serialization/deserialization
+- ✅ **Configuration validation**: Timeout relationships and constants
+- ✅ **Error handling**: Invalid input parsing and edge cases
+- ✅ **Data types**: Binary data, Unicode, special characters
+- ✅ **Security validation**: Command sanitization, injection prevention, whitelist enforcement
+
+## CI/CD Integration
+
+Tests run automatically in the Gitea Actions workflow:
+
+1. **Test Job**: Runs `cargo test --all-targets --all-features`
+2. **Lint Job**: Runs after tests pass
+3. **Build Job**: Runs after linting passes
+4. **Deploy Job**: Runs after build passes
+
+## Adding New Tests
+
+When adding new tests:
+
+1. Choose the appropriate test file based on the module being tested
+2. Follow the existing test naming convention: `test_<feature>_<scenario>`
+3. Group related tests together with comments
+4. Include both success and failure cases
+5. Test edge cases (empty strings, zero values, max values, etc.)
+6. Add documentation comments for complex test scenarios
+
+### Example Test Structure
+```rust
+#[test]
+fn test_feature_success_case() {
+    // Arrange
+    let input = setup_test_data();
+    
+    // Act
+    let result = function_under_test(input);
+    
+    // Assert
+    assert_eq!(result, expected_value);
+}
+
+#[test]
+fn test_feature_error_case() {
+    let invalid_input = "invalid";
+    let result = function_under_test(invalid_input);
+    assert!(result.is_err());
+}
+```
+
+## Test Guidelines
+
+- **Fast**: Unit tests should run in milliseconds
+- **Isolated**: Each test should be independent
+- **Deterministic**: Tests should always produce the same result
+- **Clear**: Test names should clearly describe what is being tested
+- **Comprehensive**: Test happy paths, error paths, and edge cases
+
+## Clippy Allowances
+
+Some tests use `#![allow(clippy::assertions_on_constants)]` because they document expected constant values for configuration. This is intentional and helps verify that constants maintain reasonable values.
+
+## Security Features
+
+The test suite includes comprehensive security validation to prevent:
+- Shell injection attacks
+- Path traversal attempts
+- Command injection via metacharacters
+- Null byte injection
+- Execution from untrusted directories
+- Unicode/encoding tricks
+- Environment variable injection
+
+The `security` module provides `validate_command()` and `validate_env_value()` functions that are used by the server to validate all commands before execution.
+
+## Total Test Count
+
+- **Unit tests** (in src/):
+  - terminado.rs: 6 tests
+  - security.rs: 11 tests
+- **Integration tests** (in tests/):
+  - event_tests.rs: 11 tests
+  - terminado_tests.rs: 38 tests
+  - config_tests.rs: 17 tests
+  - security_tests.rs: 28 tests
+- **Total**: 111 tests
+
+All tests must pass before code can be merged.