# Unlock Workflow Tests

**Task**: 04_test_unlock
**Name**: Unlock Workflow Tests
**Description**: Implement blackbox tests for the Docker image unlock workflow including state machine transitions
**Complexity**: 5 points
**Dependencies**: 01_test_infrastructure, 02_test_health_auth
**Component**: Blackbox Tests
**Tracker**: pending
**Epic**: pending

## Problem

The Docker unlock workflow is the most complex flow in the system — it involves authentication, key fragment download, archive decryption, and Docker image loading. No test coverage exists.

## Outcome

- Unlock starts and transitions through all states (FT-P-06)
- Unlock detects already-loaded images (FT-P-07)
- Unlock status polling works (FT-P-08)
- Missing archive returns 404 (FT-N-05)
- Concurrent unlock requests handled correctly (NFT-RES-LIM-02)

## Scope

### Included
- FT-P-06: Unlock starts background workflow (full state cycle)
- FT-P-07: Unlock detects already-loaded images
- FT-P-08: Unlock status poll (idle state)
- FT-N-05: Unlock without encrypted archive
- NFT-RES-LIM-02: Concurrent unlock requests

### Excluded
- Resource download/upload tests
- Performance benchmarking

## Acceptance Criteria

**AC-1: Unlock starts background workflow**
Given encrypted test archive at IMAGES_PATH and mock API configured
When POST /unlock with valid credentials
Then response contains state field and status transitions to "ready"

**AC-2: Unlock detects loaded images**
Given all API_SERVICES Docker images present with correct tags
When POST /unlock
Then immediate response with state="ready"

**AC-3: Unlock status returns current state**
Given no unlock has been started
When GET /unlock/status
Then HTTP 200 with state="idle" and error=null

**AC-4: Missing archive returns 404**
Given no file at IMAGES_PATH and images not loaded
When POST /unlock
Then HTTP 404 with "Encrypted archive not found"

**AC-5: Concurrent unlock handled**
Given unlock is in progress
When a second POST /unlock is sent
Then second request returns current in-progress state without starting duplicate

## Blackbox Tests

| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|------------------------|-------------|-------------------|----------------|
| AC-1 | Archive exists, mock API | POST /unlock + poll | States → ready | — |
| AC-2 | Images loaded | POST /unlock | Immediate ready | — |
| AC-3 | Idle state | GET /unlock/status | idle, null error | — |
| AC-4 | No archive, no images | POST /unlock | 404 | — |
| AC-5 | Unlock in progress | POST /unlock (2nd) | Returns current state | NFT-RES-LIM-02 |

## Risks & Mitigation

**Risk 1: Docker daemon required in test environment**
- *Risk*: Unlock tests need a real Docker daemon for docker load/inspect
- *Mitigation*: Mount Docker socket in test container; use small test images

**Risk 2: Test archive generation**
- *Risk*: Need a valid encrypted archive + matching key fragment
- *Mitigation*: Pre-generate a small test archive using the same AES-256-CBC scheme