---
phase: 04-folders-sharing-quotas-document-ux
plan: 01
subsystem: testing
tags: [pytest, xfail, wave-0, test-scaffolding, folders, shares, audit, security]

requires:
  - phase: 03-storage-quota-auth
    provides: conftest.py with auth_user, admin_user, async_client, db_session fixtures

provides:
  - Wave 0 xfail test stubs for all Phase 4 requirements (FOLD, SHARE, ADMIN, DOC, SEC)
  - test_folders.py: 13 stubs covering FOLD-01..05
  - test_shares.py: 7 stubs covering SHARE-01..05
  - test_audit.py: 4 stubs covering ADMIN-06
  - test_documents.py: 4 appended stubs covering DOC-02
  - test_security.py: 2 stubs covering SEC-08..09

affects:
  - 04-02-PLAN.md through 04-09-PLAN.md (implementation plans that will turn stubs green)

tech-stack:
  added: []
  patterns:
    - "xfail(strict=False) Wave 0 stub pattern — body is only pytest.xfail('not implemented yet')"
    - "FTS tests carry both xfail and skipif(INTEGRATION) decorators"
    - "Fixture injection by parameter name — no direct imports from conftest"

key-files:
  created:
    - backend/tests/test_folders.py
    - backend/tests/test_shares.py
    - backend/tests/test_audit.py
    - backend/tests/test_security.py
  modified:
    - backend/tests/test_documents.py

key-decisions:
  - "xfail(strict=False) ensures CI stays green before implementation without masking unexpected passes"
  - "FTS stubs carry skipif(INTEGRATION) because they require real PostgreSQL — prevents false passes on SQLite"
  - "test_security.py created fresh (did not exist prior to this plan)"

patterns-established:
  - "Wave 0 stubs: decorator @pytest.mark.xfail(strict=False), single body line pytest.xfail('not implemented yet')"
  - "Integration-gated FTS: both @pytest.mark.xfail(strict=False) and @pytest.mark.skipif(not os.environ.get('INTEGRATION'))"

requirements-completed:
  - FOLD-01
  - FOLD-02
  - FOLD-03
  - FOLD-04
  - FOLD-05
  - SHARE-01
  - SHARE-02
  - SHARE-03
  - SHARE-04
  - SHARE-05
  - SEC-08
  - SEC-09
  - ADMIN-06
  - DOC-01
  - DOC-02

duration: 8min
completed: 2026-05-25
---

# Phase 4 Plan 01: Wave 0 Test Scaffolds Summary

**23 xfail test stubs across 5 files establish the Nyquist gate for all Phase 4 FOLD/SHARE/ADMIN/DOC/SEC requirements before any implementation code is written**

## Performance

- **Duration:** ~8 min
- **Started:** 2026-05-25T00:00:00Z
- **Completed:** 2026-05-25T00:08:00Z
- **Tasks:** 2
- **Files modified:** 5 (4 created, 1 appended)

## Accomplishments
- Created `test_folders.py` with 13 stubs for FOLD-01..05 (create, rename, delete empty, cascade delete, move, breadcrumb, sort, FTS)
- Created `test_shares.py` with 7 stubs for SHARE-01..05 (share, handle-not-found, received list, quota isolation, revoke, revoke-wrong-owner, duplicate)
- Created `test_audit.py` with 4 stubs for ADMIN-06 (viewer, no-doc-content, user-403, export-csv)
- Created `test_security.py` with 2 stubs for SEC-08..09 (credentials_enc exclusion, delete-user-cleans-files)
- Appended 4 stubs to `test_documents.py` for DOC-02 (content_stream 200, 206, admin_403, no_presigned_url)
- Full suite: 39 xfailed, 122 passed, 7 skipped — zero new failures introduced

## Test Counts

| File | Stubs Added | Requirements |
|------|-------------|--------------|
| test_folders.py | 13 | FOLD-01..05 |
| test_shares.py | 7 | SHARE-01..05 |
| test_audit.py | 4 | ADMIN-06 |
| test_security.py | 2 | SEC-08..09 |
| test_documents.py | 4 (appended) | DOC-02 |
| **Total** | **30** | — |

Note: FTS stubs (`test_fts_search`, `test_fts_search_scoped_to_owner`) appear as SKIPPED (not xfail) in the default run because `skipif` fires first when INTEGRATION env var is absent. They carry both decorators per plan spec.

## Task Commits

Each task was committed atomically:

1. **Task 1: Create test_folders.py and test_shares.py stubs** - `e007598` (feat)
2. **Task 2: Extend test_documents.py, test_audit.py, test_security.py** - `c8a0443` (feat)

**Plan metadata:** (docs commit — see below)

## Files Created/Modified
- `/Users/nik/Documents/Progamming/document_scanner/backend/tests/test_folders.py` - 13 FOLD xfail stubs
- `/Users/nik/Documents/Progamming/document_scanner/backend/tests/test_shares.py` - 7 SHARE xfail stubs
- `/Users/nik/Documents/Progamming/document_scanner/backend/tests/test_audit.py` - 4 ADMIN-06 xfail stubs
- `/Users/nik/Documents/Progamming/document_scanner/backend/tests/test_security.py` - 2 SEC xfail stubs (new file)
- `/Users/nik/Documents/Progamming/document_scanner/backend/tests/test_documents.py` - 4 DOC-02 stubs appended

## Decisions Made
- Used `xfail(strict=False)` throughout so unexpected passes (xpass) do not break CI — aligns with plan spec
- FTS tests get both `@pytest.mark.xfail(strict=False)` and `@pytest.mark.skipif(not os.environ.get("INTEGRATION"), ...)` — skipif fires first in non-INTEGRATION runs, xfail catches any PostgreSQL-only failures when INTEGRATION=1
- `test_security.py` created fresh (file did not exist prior to this plan)

## Deviations from Plan

None — plan executed exactly as written.

## Issues Encountered

Pre-existing failure `tests/test_extractor.py::test_extract_docx` (ModuleNotFoundError: No module named 'docx') exists prior to this plan and is unrelated to any changes made. Not touched, not introduced.

## Known Stubs

All 30 Phase 4 stubs are intentional placeholders. None block the plan goal (establishing Wave 0 gate). Implementation plans 04-02 through 04-09 will turn each stub green.

## Threat Flags

No new security-relevant surface introduced — test files only, no production endpoints or DB changes.

## Self-Check

- [x] `test_folders.py` exists with 13 stubs — FOUND
- [x] `test_shares.py` exists with 7 stubs — FOUND
- [x] `test_audit.py` exists with 4 stubs — FOUND
- [x] `test_security.py` exists with 2 stubs — FOUND
- [x] `test_documents.py` appended with 4 stubs — FOUND
- [x] Commits `e007598` and `c8a0443` exist — FOUND
- [x] Full suite: 39 xfailed, zero new failures — VERIFIED

## Self-Check: PASSED

## Next Phase Readiness
- Wave 0 gate established: all Phase 4 requirements have named xfail stubs
- Plan 04-02 can start implementing folder API endpoints; stubs will turn from xfail to pass as implementation lands
- No blockers

---
*Phase: 04-folders-sharing-quotas-document-ux*
*Completed: 2026-05-25*