# Config Precedence Unit Tests

**Task**: AZ-271_config_precedence_tests
**Name**: Config Precedence Tests
**Description**: A focused unit-test module that verifies the env > YAML > defaults precedence rule for at least 3 keys per layer (per epic AZ-246 AC-3) and the multi-file YAML merge order (later wins). Companion to AZ-269 / AZ-270.
**Complexity**: 2 points
**Dependencies**: AZ-269_config_loader, AZ-270_compose_root
**Component**: shared.config (cross-cutting; epic AZ-246 / E-CC-CONF)
**Tracker**: AZ-271
**Epic**: AZ-246 (E-CC-CONF)

### Document Dependencies

- `_docs/02_document/contracts/shared_config/composition_root_protocol.md` — the contract whose precedence invariant this test suite verifies.

## Problem

The composition_root_protocol contract declares a hard precedence rule. Without explicit, tabular tests covering at least 3 keys per layer, regressions in the loader silently flip precedence and cause field bugs that only show up in production deployments where env overrides matter most.

## Outcome

- A pytest module with clearly-named cases covering precedence for ≥3 keys at each layer.
- A multi-file YAML merge case proving later paths win over earlier paths.
- Failure messages name the layer (env / YAML / defaults) so on-call engineers can triage fast.

## Scope

### Included

- Precedence cases for ≥3 keys at each of: env > YAML, YAML > defaults, multi-file YAML merge order.
- One reachability case driving `compose_root` end-to-end with a stub Config to prove the loader and composition functions integrate cleanly.
- Test fixtures (in-memory YAML strings + env dict, no real files needed for precedence cases; one tmp_path for the multi-file case).

### Excluded

- Performance microbench — owned by AZ-269.
- Strategy/build-flag mismatch tests — owned by AZ-270.
- Per-component config block tests — owned by each component epic.

## Acceptance Criteria

**AC-1: env > YAML for at least 3 keys**
Given env sets `LOG_LEVEL`, `FDR_QUEUE_SIZE`, `MAVLINK_BAUD` and YAML sets all three to different values
When `load_config(env, [yaml])` runs
Then all three resolved values match env

**AC-2: YAML > defaults for at least 3 keys**
Given env is empty and YAML sets `log.level`, `fdr.queue_size`, `mavlink.baud`
When `load_config(env, [yaml])` runs
Then all three resolved values match YAML (not the documented defaults)

**AC-3: Defaults apply for at least 3 keys**
Given env is empty and YAML omits the three keys
When `load_config(env, [yaml])` runs
Then all three resolved values match the documented defaults

**AC-4: Multi-file YAML — later wins**
Given two YAML paths setting the same key to different values
When `load_config(env, [first, second])` runs
Then the resolved value matches the second file

**AC-5: Failure messages name the layer**
Given a precedence assertion fails
When pytest reports the failure
Then the assertion message names which layer's value was expected and which was found

## Non-Functional Requirements

**Reliability**
- Tests are hermetic: no real env vars consulted, no real YAML files outside tmp_path.

## Constraints

- Test file path is fixed at `tests/unit/shared/config/test_precedence.py` (mirrors the `tests/unit/<component>/` convention from module-layout.md Layout Rule 7 — `shared/config` is the component slug).
- Cases use the SAME 3 keys per layer to make the test matrix comparable across layers.