re-uploading work
This commit is contained in:
333
docs/webhooks/webhook-testing.md
Normal file
333
docs/webhooks/webhook-testing.md
Normal file
@@ -0,0 +1,333 @@
|
||||
# Webhook Testing Documentation
|
||||
|
||||
This document describes the comprehensive test suite for the Attune webhook system, covering both Phase 2 (basic functionality) and Phase 3 (advanced security features).
|
||||
|
||||
## Test Files
|
||||
|
||||
### 1. `crates/common/tests/webhook_tests.rs`
|
||||
Repository-level integration tests for webhook database operations.
|
||||
|
||||
**Coverage:**
|
||||
- Webhook enable/disable functionality
|
||||
- Webhook key generation and uniqueness
|
||||
- Webhook key regeneration
|
||||
- Finding triggers by webhook key
|
||||
- Idempotent webhook enabling
|
||||
|
||||
**Key Tests:**
|
||||
- `test_webhook_enable` - Verifies webhook can be enabled and generates valid key
|
||||
- `test_webhook_disable` - Verifies webhook can be disabled while preserving key
|
||||
- `test_webhook_key_regeneration` - Tests key rotation functionality
|
||||
- `test_find_by_webhook_key` - Tests lookup by webhook key
|
||||
- `test_webhook_key_uniqueness` - Ensures unique keys across triggers
|
||||
- `test_enable_webhook_idempotent` - Verifies enabling twice returns same key
|
||||
|
||||
### 2. `crates/api/tests/webhook_api_tests.rs`
|
||||
API endpoint integration tests for webhook management and basic receiving.
|
||||
|
||||
**Coverage:**
|
||||
- Webhook management endpoints (enable/disable/regenerate)
|
||||
- Basic webhook receiving
|
||||
- Authentication requirements
|
||||
- Error handling for invalid keys
|
||||
|
||||
**Key Tests:**
|
||||
- `test_enable_webhook` - Tests enabling webhooks via API
|
||||
- `test_disable_webhook` - Tests disabling webhooks via API
|
||||
- `test_regenerate_webhook_key` - Tests key regeneration via API
|
||||
- `test_receive_webhook` - Tests successful webhook reception
|
||||
- `test_receive_webhook_invalid_key` - Tests invalid key handling
|
||||
- `test_receive_webhook_disabled` - Tests disabled webhook rejection
|
||||
- `test_webhook_requires_auth_for_management` - Tests auth enforcement
|
||||
- `test_receive_webhook_minimal_payload` - Tests minimal payload acceptance
|
||||
|
||||
### 3. `crates/api/tests/webhook_security_tests.rs`
|
||||
Comprehensive security feature tests (Phase 3).
|
||||
|
||||
**Coverage:**
|
||||
- HMAC signature verification (SHA256, SHA512, SHA1)
|
||||
- Rate limiting
|
||||
- IP whitelisting (IPv4, IPv6, CIDR)
|
||||
- Payload size limits
|
||||
- Event logging
|
||||
- Combined security features
|
||||
- Error scenarios
|
||||
|
||||
## Test Categories
|
||||
|
||||
### HMAC Signature Tests
|
||||
|
||||
#### `test_webhook_hmac_sha256_valid`
|
||||
Verifies SHA256 HMAC signature validation works correctly.
|
||||
- Enables HMAC with SHA256 algorithm
|
||||
- Generates valid signature
|
||||
- Confirms webhook is accepted (200 OK)
|
||||
|
||||
#### `test_webhook_hmac_sha512_valid`
|
||||
Verifies SHA512 HMAC signature validation.
|
||||
- Uses SHA512 algorithm
|
||||
- Tests stronger hashing algorithm support
|
||||
|
||||
#### `test_webhook_hmac_invalid_signature`
|
||||
Tests rejection of invalid signatures.
|
||||
- Sends webhook with malformed signature
|
||||
- Expects 401 Unauthorized response
|
||||
|
||||
#### `test_webhook_hmac_missing_signature`
|
||||
Tests rejection when signature is required but missing.
|
||||
- HMAC enabled but no signature header provided
|
||||
- Expects 401 Unauthorized response
|
||||
|
||||
#### `test_webhook_hmac_wrong_secret`
|
||||
Tests rejection when signature uses wrong secret.
|
||||
- Generates signature with incorrect secret
|
||||
- Expects 401 Unauthorized response
|
||||
|
||||
### Rate Limiting Tests
|
||||
|
||||
#### `test_webhook_rate_limit_enforced`
|
||||
Verifies rate limiting prevents excessive requests.
|
||||
- Configures limit of 3 requests per 60 seconds
|
||||
- Sends 3 successful requests
|
||||
- 4th request returns 429 Too Many Requests
|
||||
|
||||
#### `test_webhook_rate_limit_disabled`
|
||||
Confirms webhooks work without rate limiting.
|
||||
- Sends 10 consecutive requests
|
||||
- All succeed when rate limiting disabled
|
||||
|
||||
### IP Whitelisting Tests
|
||||
|
||||
#### `test_webhook_ip_whitelist_allowed`
|
||||
Tests IP whitelist allows configured IPs.
|
||||
- Configures whitelist with CIDR and exact IP
|
||||
- Tests both CIDR range match (192.168.1.100 in 192.168.1.0/24)
|
||||
- Tests exact IP match (10.0.0.1)
|
||||
- Both return 200 OK
|
||||
|
||||
#### `test_webhook_ip_whitelist_blocked`
|
||||
Tests IP whitelist blocks non-whitelisted IPs.
|
||||
- Sends request from IP not in whitelist (8.8.8.8)
|
||||
- Expects 403 Forbidden response
|
||||
|
||||
### Payload Size Limit Tests
|
||||
|
||||
#### `test_webhook_payload_size_limit_enforced`
|
||||
Verifies payload size limits are enforced.
|
||||
- Sets 1 KB limit
|
||||
- Sends 2 KB payload
|
||||
- Expects 400 Bad Request response
|
||||
|
||||
#### `test_webhook_payload_size_within_limit`
|
||||
Tests payloads within limit are accepted.
|
||||
- Sets 10 KB limit
|
||||
- Sends small payload
|
||||
- Expects 200 OK response
|
||||
|
||||
### Event Logging Tests
|
||||
|
||||
#### `test_webhook_event_logging_success`
|
||||
Verifies successful webhooks are logged.
|
||||
- Sends successful webhook
|
||||
- Checks log entry exists
|
||||
- Validates log contains status code, IP, user agent
|
||||
|
||||
#### `test_webhook_event_logging_failure`
|
||||
Verifies failed webhooks are logged.
|
||||
- Sends failing webhook (HMAC failure)
|
||||
- Checks log entry with error details
|
||||
- Validates failure reason recorded
|
||||
|
||||
### Combined Security Tests
|
||||
|
||||
#### `test_webhook_all_security_features_pass`
|
||||
Tests webhook passing all security checks.
|
||||
- Enables HMAC, rate limiting, IP whitelist, size limit
|
||||
- Sends properly authenticated, allowed webhook
|
||||
- Verifies all checks pass and event created
|
||||
- Validates log shows all features verified
|
||||
|
||||
#### `test_webhook_multiple_security_failures`
|
||||
Tests multiple security feature failures.
|
||||
- Enables multiple features
|
||||
- Sends webhook failing multiple checks
|
||||
- Verifies first failure prevents further processing
|
||||
|
||||
### Error Scenario Tests
|
||||
|
||||
#### `test_webhook_malformed_json`
|
||||
Tests handling of malformed JSON payloads.
|
||||
- Sends invalid JSON
|
||||
- Expects 400 Bad Request response
|
||||
|
||||
#### `test_webhook_empty_payload`
|
||||
Tests handling of empty payloads.
|
||||
- Sends empty body
|
||||
- Expects 400 Bad Request response
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Run All Tests
|
||||
```bash
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
### Run Specific Test Suite
|
||||
```bash
|
||||
# Repository tests
|
||||
cargo test -p attune-common webhook_tests
|
||||
|
||||
# API tests
|
||||
cargo test -p attune-api webhook_api_tests
|
||||
|
||||
# Security tests
|
||||
cargo test -p attune-api webhook_security_tests
|
||||
```
|
||||
|
||||
### Run Ignored Tests (Requires Database)
|
||||
```bash
|
||||
cargo test --workspace -- --ignored
|
||||
```
|
||||
|
||||
### Run Specific Test
|
||||
```bash
|
||||
cargo test -p attune-api test_webhook_hmac_sha256_valid -- --ignored
|
||||
```
|
||||
|
||||
## Test Environment Setup
|
||||
|
||||
Tests require:
|
||||
1. **PostgreSQL Database** - Running on localhost:5432 (or configured via `DATABASE_URL`)
|
||||
2. **Test User** - Username: `test_user`, Password: `test_password`
|
||||
3. **Migrations Applied** - All database migrations must be up to date
|
||||
|
||||
### Setup Commands
|
||||
```bash
|
||||
# Set database URL
|
||||
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/attune"
|
||||
|
||||
# Run migrations
|
||||
sqlx migrate run
|
||||
|
||||
# Create test user (if not exists)
|
||||
psql $DATABASE_URL -c "
|
||||
INSERT INTO attune.identity (username, email, password_hash, enabled)
|
||||
VALUES ('test_user', 'test@example.com', '$argon2id$...', true)
|
||||
ON CONFLICT (username) DO NOTHING;
|
||||
"
|
||||
```
|
||||
|
||||
## Test Coverage Summary
|
||||
|
||||
| Feature | Test Count | Status |
|
||||
|---------|-----------|--------|
|
||||
| Basic Webhook Management | 8 | ✅ Complete |
|
||||
| HMAC Verification | 5 | ✅ Complete |
|
||||
| Rate Limiting | 2 | ✅ Complete |
|
||||
| IP Whitelisting | 2 | ✅ Complete |
|
||||
| Payload Size Limits | 2 | ✅ Complete |
|
||||
| Event Logging | 2 | ✅ Complete |
|
||||
| Combined Security | 2 | ✅ Complete |
|
||||
| Error Scenarios | 2 | ✅ Complete |
|
||||
| **Total** | **25** | **✅ Complete** |
|
||||
|
||||
## Security Test Matrix
|
||||
|
||||
| HMAC | Rate Limit | IP Whitelist | Size Limit | Expected Result |
|
||||
|------|-----------|--------------|------------|-----------------|
|
||||
| ✅ Valid | ✅ OK | ✅ Allowed | ✅ OK | 200 OK |
|
||||
| ❌ Invalid | N/A | N/A | N/A | 401 Unauthorized |
|
||||
| ⚠️ Missing | N/A | N/A | N/A | 401 Unauthorized |
|
||||
| ✅ Valid | ❌ Exceeded | N/A | N/A | 429 Too Many Requests |
|
||||
| ✅ Valid | ✅ OK | ❌ Blocked | N/A | 403 Forbidden |
|
||||
| ✅ Valid | ✅ OK | ✅ Allowed | ❌ Too Large | 400 Bad Request |
|
||||
|
||||
## Known Test Limitations
|
||||
|
||||
1. **Rate Limit Window Tests** - Tests don't verify time-based window expiry (would require time manipulation)
|
||||
2. **Concurrent Rate Limiting** - No tests for concurrent request handling
|
||||
3. **IPv6 Whitelist** - Limited IPv6 testing coverage
|
||||
4. **Webhook Retry** - Not yet implemented (Phase 4 feature)
|
||||
5. **Performance Tests** - No load/stress tests included
|
||||
|
||||
## Future Test Additions
|
||||
|
||||
### Phase 4 Features (Planned)
|
||||
- Webhook retry logic tests
|
||||
- Payload transformation tests
|
||||
- Multiple webhook keys per trigger
|
||||
- Webhook health check tests
|
||||
- Analytics and metrics tests
|
||||
|
||||
### Additional Coverage Needed
|
||||
- Concurrent webhook processing
|
||||
- Database connection failure handling
|
||||
- Message queue failure scenarios
|
||||
- Performance benchmarks
|
||||
- Security penetration testing
|
||||
|
||||
## Debugging Failed Tests
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Test fails with "Failed to connect to database"**
|
||||
```bash
|
||||
# Check database is running
|
||||
pg_isready -h localhost -p 5432
|
||||
|
||||
# Verify DATABASE_URL
|
||||
echo $DATABASE_URL
|
||||
|
||||
# Test connection
|
||||
psql $DATABASE_URL -c "SELECT 1"
|
||||
```
|
||||
|
||||
**Test fails with "Trigger not found"**
|
||||
- Ensure migrations are up to date: `sqlx migrate run`
|
||||
- Check schema exists: `psql $DATABASE_URL -c "\dn"`
|
||||
|
||||
**Test fails with "Authentication required"**
|
||||
- Verify test user exists in database
|
||||
- Check JWT_SECRET environment variable is set
|
||||
|
||||
**Rate limit test fails unexpectedly**
|
||||
- Database state may have rate limit entries from previous tests
|
||||
- Clear webhook_event_log table between test runs
|
||||
|
||||
## Manual Testing
|
||||
|
||||
For manual testing instructions, see [webhook-manual-testing.md](webhook-manual-testing.md).
|
||||
|
||||
## Continuous Integration
|
||||
|
||||
Tests are configured to run in CI/CD pipeline with:
|
||||
- PostgreSQL service container
|
||||
- Test database initialization
|
||||
- Migration application
|
||||
- Test user creation
|
||||
- Parallel test execution
|
||||
|
||||
See `.github/workflows/test.yml` (if configured) for CI setup.
|
||||
|
||||
## Test Maintenance
|
||||
|
||||
### Adding New Tests
|
||||
1. Follow existing test structure and naming conventions
|
||||
2. Use test helpers (`setup_test_state`, `create_test_pack`, etc.)
|
||||
3. Clean up test data after test completion
|
||||
4. Mark as `#[ignore]` if requires external dependencies
|
||||
5. Document test purpose and expected behavior
|
||||
6. Add test to this documentation
|
||||
|
||||
### Updating Tests for New Features
|
||||
1. Update relevant test files
|
||||
2. Add new test categories if needed
|
||||
3. Update test coverage summary
|
||||
4. Update security test matrix if applicable
|
||||
5. Document any new test requirements
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-01-20
|
||||
**Test Suite Version:** 1.0
|
||||
**Phase Completion:** Phase 3 ✅
|
||||
Reference in New Issue
Block a user