diff --git a/notes/bf-2ntve.md b/notes/bf-2ntve.md new file mode 100644 index 0000000..d44e081 --- /dev/null +++ b/notes/bf-2ntve.md @@ -0,0 +1,132 @@ +# bf-2ntve: Encryption Test Module Location Research + +## Summary + +Identified the appropriate test module locations for encryption-related error tests in the pdftract CLI. + +## Findings + +### Existing Test Structure + +The pdftract project uses a dual-level test structure: + +1. **Workspace-level integration tests**: `/home/coding/pdftract/tests/` + - Contains general integration tests shared across the workspace + - Example: `tests/encryption_errors.rs` (7,018 bytes) + +2. **CLI-specific integration tests**: `/home/coding/pdftract/crates/pdftract-cli/tests/` + - Contains tests specific to the pdftract CLI binary + - More extensive test fixtures and CLI-specific behavior + +### Encryption Test Files Already Present + +#### 1. CLI-specific encryption tests + +**File**: `/home/coding/pdftract/crates/pdftract-cli/tests/test_encryption_errors.rs` (12,690 bytes) +- **Purpose**: Comprehensive encryption error testing for pdftract CLI +- **Structure**: Well-organized module with: + - `unsupported_handlers` module - Tests for Adobe LiveCycle unsupported handler + - `supported_encryption` module - Tests for RC4/AES decryption with passwords + - `password_errors` module - Tests for wrong/missing password handling + - `fixture_validation` module - Validates encrypted PDF fixtures + - `integration_tests` module - Placeholder for complete workflow tests +- **Fixtures**: Uses `tests/fixtures/encrypted/` directory +- **References**: Cites plan lines 258, 732, 1132, 1149 + +**File**: `/home/coding/pdftract/crates/pdftract-cli/tests/test_encryption_unsupported.rs` (2,828 bytes) +- **Purpose**: Focused test for ENCRYPTION_UNSUPPORTED exit code +- **Tests**: Two specific tests for livecycle.pdf behavior +- **Functionality**: Verifies exit code 3 and error message content + +#### 2. Workspace-level encryption tests + +**File**: `/home/coding/pdftract/tests/encryption_errors.rs` (7,018 bytes) +- **Purpose**: Encryption error integration tests +- **Feature flag**: `#![cfg(feature = "decrypt")]` +- **Tests**: + - `test_encryption_unsupported_livecycle()` - Verifies ENCRYPTION_UNSUPPORTED diagnostic + - `test_exit_code_3_no_password()` - Exit code verification + - `test_wrong_password_encryption_unsupported()` - Wrong password handling + - `test_encryption_error_consistency()` - Parameterized test across fixtures + +## Target File Paths for New Encryption Tests + +### For CLI-specific encryption tests +``` +/home/coding/pdftract/crates/pdftract-cli/tests/test_encryption_errors.rs +``` +**Rationale**: This is the primary location for CLI-specific encryption error tests. It already contains: +- Comprehensive module structure +- Fixture validation infrastructure +- Password handling tests +- Exit code verification + +### For general integration tests +``` +/home/coding/pdftract/tests/encryption_errors.rs +``` +**Rationale**: This location is appropriate for: +- Cross-cutting integration tests +- Tests that don't require CLI-specific behavior +- Tests gated by feature flags (e.g., `decrypt` feature) + +## Module Structure Pattern + +The test structure follows these conventions: + +1. **CLI tests**: `crates/pdftract-cli/tests/test__.rs` + - Examples: `test_encryption_errors.rs`, `test_encryption_unsupported.rs` + - Uses direct binary execution via `Command::new(pdftract_bin())` + +2. **Workspace tests**: `tests/_.rs` + - Examples: `encryption_errors.rs` + - May use feature gates: `#![cfg(feature = "decrypt")]` + +## Encrypted Fixtures Location + +``` +/home/coding/pdftract/tests/fixtures/encrypted/ +``` + +**Fixture files**: +- `EC-04-rc4-encrypted.pdf` - RC4 encryption +- `EC-05-aes128-encrypted.pdf` - AES-128 encryption +- `EC-06-aes256-encrypted.pdf` - AES-256 encryption +- `EC-empty-password.pdf` - Empty password +- `livecycle.pdf` - Unsupported Adobe.APS handler + +## References + +- Plan line 258: Failure Mode Taxonomy - ENCRYPTION_UNSUPPORTED +- Plan line 732: Input | Encryption-unsupported diagnostic and CLI exit code 3 +- Plan line 1132: RC4 and AES-128/256 decryption implementation +- Plan line 1149: Encrypted file with unknown handler error handling +- Parent bead: bf-56jda + +## Recommendation + +For new encryption-related error tests, the appropriate location is: + +**Primary location**: `/home/coding/pdftract/crates/pdftract-cli/tests/test_encryption_errors.rs` + +This file already contains: +- Module structure for different encryption scenarios +- Fixture validation infrastructure +- Exit code verification patterns +- Password handling tests (some marked as `[ignore]` pending implementation) + +**Secondary location** (for feature-flagged or general integration tests): +`/home/coding/pdftract/tests/encryption_errors.rs` + +## Acceptance Criteria Status + +✅ **Target test file path identified**: +- Primary: `crates/pdftract-cli/tests/test_encryption_errors.rs` +- Secondary: `tests/encryption_errors.rs` + +✅ **Module structure understood**: +- CLI tests use `test__.rs` naming +- Modular structure with sub-modules for different scenarios +- Fixture-based testing with validation + +✅ **Path documented in verification note**: This file documents all findings