# Version Support Test Suite Documentation

This document describes the comprehensive test suite created for the versioned secrets functionality in the Secret Manager.

## Test Files Created

### 1. `internal/secret/version_test.go`
Core unit tests for version functionality:

- **TestGenerateVersionName**: Tests version name generation with date and serial format
- **TestGenerateVersionNameMaxSerial**: Tests the 999 versions per day limit
- **TestNewSecretVersion**: Tests secret version object creation
- **TestSecretVersionSave**: Tests saving a version with encryption
- **TestSecretVersionLoadMetadata**: Tests loading and decrypting version metadata
- **TestSecretVersionGetValue**: Tests retrieving and decrypting version values
- **TestListVersions**: Tests listing versions in reverse chronological order
- **TestGetCurrentVersion**: Tests retrieving the current version via symlink
- **TestSetCurrentVersion**: Tests updating the current version symlink
- **TestVersionMetadataTimestamps**: Tests timestamp pointer consistency

### 2. `internal/vault/secrets_version_test.go`
Integration tests for vault-level version operations:

- **TestVaultAddSecretCreatesVersion**: Tests that AddSecret creates proper version structure
- **TestVaultAddSecretMultipleVersions**: Tests creating multiple versions with force flag
- **TestVaultGetSecretVersion**: Tests retrieving specific versions and current version
- **TestVaultVersionTimestamps**: Tests timestamp logic (notBefore/notAfter) across versions
- **TestVaultGetNonExistentVersion**: Tests error handling for invalid versions
- **TestUpdateVersionMetadata**: Tests metadata update functionality

### 3. `internal/cli/version_test.go`
CLI command tests:

- **TestListVersionsCommand**: Tests `secret version list` command output
- **TestListVersionsNonExistentSecret**: Tests error handling for missing secrets
- **TestPromoteVersionCommand**: Tests `secret version promote` command
- **TestPromoteNonExistentVersion**: Tests error handling for invalid promotion
- **TestGetSecretWithVersion**: Tests `secret get --version` flag functionality
- **TestVersionCommandStructure**: Tests command structure and help text
- **TestListVersionsEmptyOutput**: Tests edge case with no versions

### 4. `internal/vault/integration_version_test.go`
Comprehensive integration tests:

- **TestVersionIntegrationWorkflow**: End-to-end workflow testing
  - Creating initial version with proper metadata
  - Creating multiple versions with timestamp updates
  - Retrieving specific versions by name
  - Promoting old versions to current
  - Testing version serial number limits (999/day)
  - Error cases and edge conditions

- **TestVersionConcurrency**: Tests concurrent read operations

- **TestVersionCompatibility**: Tests handling of legacy non-versioned secrets

## Key Test Scenarios Covered

### Version Creation
- First version gets `notBefore = epoch + 1 second`
- Subsequent versions update previous version's `notAfter` timestamp
- New version's `notBefore` equals previous version's `notAfter`
- Version names follow `YYYYMMDD.NNN` format
- Maximum 999 versions per day enforced

### Version Retrieval
- Get current version via symlink
- Get specific version by name
- Empty version parameter returns current
- Non-existent versions return appropriate errors

### Version Management
- List versions in reverse chronological order
- Promote any version to current
- Promotion doesn't modify timestamps
- Metadata remains encrypted and intact

### Data Integrity
- Each version has independent encryption keys
- Metadata encryption protects version history
- Long-term key required for all operations
- Concurrent reads handled safely

### Backward Compatibility
- Legacy secrets without versions detected
- Appropriate error messages for incompatible operations

## Test Utilities Created

### Helper Functions
- `createTestVaultWithKey()`: Sets up vault with long-term key for testing
- `setupTestVault()`: CLI test helper for vault initialization
- Mock implementations for isolated testing

### Test Environment
- Uses in-memory filesystem (afero.MemMapFs)
- Consistent test mnemonic for reproducible keys
- Proper cleanup and isolation between tests

## Running the Tests

Run all version-related tests:
```bash
go test ./internal/... -run "Test.*Version.*" -v
```

Run specific test suites:
```bash
# Core version tests
go test ./internal/secret -run "Test.*Version.*" -v

# Vault integration tests
go test ./internal/vault -run "Test.*Version.*" -v

# CLI tests
go test ./internal/cli -run "Test.*Version.*" -v
```

Run the comprehensive integration test:
```bash
go test ./internal/vault -run TestVersionIntegrationWorkflow -v
```

## Test Coverage Areas

1. **Functional Coverage**
   - Version CRUD operations
   - Timestamp management
   - Encryption/decryption
   - Symlink handling
   - Error conditions

2. **Integration Coverage**
   - Vault-secret interaction
   - CLI-vault interaction
   - End-to-end workflows

3. **Edge Cases**
   - Maximum versions per day
   - Empty version directories
   - Missing symlinks
   - Concurrent access
   - Legacy compatibility

4. **Security Coverage**
   - Encrypted metadata
   - Key isolation per version
   - Long-term key requirements