secret/TESTS_VERSION_SUPPORT.md

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:

go test ./internal/... -run "Test.*Version.*" -v

Run specific test suites:

# 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:

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