xamxam/docs/test-plan.md

XAMXAM — Test Coverage Plan

Prerequisites (do these first, in order)

1. Add Composer — create composer.json if not present, ensure vendor/ is gitignored except for committed tools
2. Install PHPUnit — composer require --dev phpunit/phpunit ^11
3. Create phpunit.xml at project root:

   <?xml version="1.0"?>
   <phpunit bootstrap="tests/bootstrap.php" colors="true">
     <testsuites>
       <testsuite name="XAMXAM">
         <directory>tests/phpunit</directory>
       </testsuite>
     </testsuites>
   </phpunit>
   

4. Create tests/bootstrap.php — autoload classes under test, define any constants the app needs (DB credentials from env, app root path, etc.)
5. Create tests/phpunit/ directory — all new tests go here. The existing run-tests.php and its 8 test files are left untouched for now.

---

Phase 1 — Pure Logic (no DB, no filesystem, no network)

Goal: Cover all stateless classes and helper methods. These have zero external dependencies and should take 2–3 hours total. Every test here runs in milliseconds and needs no fixtures.

1.1 CryptoTest.php — HIGH PRIORITY

Cover:

• Encrypt → decrypt round-trip returns original plaintext
• Different plaintexts produce different ciphertexts (IV randomness)
• isEncrypted() correctly identifies encrypted vs plain strings
• Legacy fallback path decrypts values encrypted with the old scheme
• Empty string handling (encrypt/decrypt empty string without error)
• Invalid base64 input to decrypt throws or returns false gracefully
• Wrong key produces failure, not silent garbage

1.2 EmailObfuscatorTest.php — MEDIUM PRIORITY

Cover:

• encode() produces output with no literal @ character
• email() renders a working obfuscated mailto link
• mailto() builds correct href structure
• emailText() replaces inline email addresses in a block of text
• mailtoInText() wraps addresses in mailto links
• obfuscateHtml() reconstructs anchor tags correctly
• Edge cases: empty string, string with no emails, already-obfuscated content, multiple emails in one string

1.3 SystemControllerHelpersTest.php — HIGH VALUE, LOW EFFORT (~15 min)

Cover the static pure functions (no HTTP context needed):

• humanBytes() — 0, 1023, 1024, 1MB, 1GB boundaries
• diskColor() — thresholds (below warning, warning, critical)
• logLineClass() — maps log level strings to CSS class names
• nginxLineClass() — maps nginx status codes to classes
• statusLabel() / statusClass() — all defined statuses

1.4 StudentEmailTest.php — LOW EFFORT

Cover buildHtml():

• Returns a non-empty string containing key thesis fields (title, author)
• HTML-escapes special characters in thesis data
• Handles a thesis row with missing/null optional fields without error

1.5 TfeControllerOgTest.php

Cover buildOgTags():

• Returns array with all required OG keys (og:title, og:description, og:image, etc.)
• Falls back correctly when image is absent
• Long descriptions are truncated to meta limits

---

Phase 2 — Integration (requires test database)

Goal: Cover DB-layer methods not yet touched. Requires a dedicated test database seeded with fixtures, wiped between test runs.

Setup required before Phase 2

• Create a tests/fixtures/ directory with SQL seed files (one per test class or shared base)
• Add a TestDatabase helper class that boots a PDO connection to the test DB, runs migrations, seeds, and truncates on teardown
• Store test DB credentials in .env.test (never committed), read in bootstrap.php

2.1 DatabaseExtendedTest.php

High-value targets (cover these first):

• escapeLikeString() — percent signs, underscores, backslashes in input
• buildSearchConditions() — various combinations of filters produce correct WHERE clauses (check SQL structure, not just that it runs)
• findDuplicateThesis() — detects exact duplicate, misses near-duplicate, handles empty table
• generateThesisIdentifier() — format is correct, increments correctly, no collision on concurrent inserts
• getCoverPathsForTheses() — returns correct paths for known IDs, returns empty for unknown IDs
• findOrCreateAuthor() — idempotent (calling twice with same name returns same ID)
• deduplicateLanguages() / renameLanguage() / mergeLanguage() — data integrity after merge
• renameTag() / mergeTag() — same pattern

2.2 ShareLinkExtendedTest.php

Extend existing ShareLinkTest with:

• listActive() — only returns active links
• listArchived() — only returns archived
• findBySlug() — hit and miss cases
• setPassword() + getDecryptedPassword() round-trip
• update() — fields change, others don't

2.3 RateLimitExtendedTest.php

Extend existing RateLimitTest with:

• checkKey() — counts per key, not globally
• getRemaining() — decrements correctly
• getClientIdentifier() — produces consistent output for same input, ignores X-Forwarded-For

---

Phase 3 — Validation & Controller Logic

Goal: Cover the validation and sanitisation logic that lives inside controllers, tested by driving through the public interface rather than calling private methods directly.

3.1 ThesisCreateValidationTest.php

Drive ThesisCreateController through its handle() method with a mock HTTP POST:

• Valid submission creates a record
• Missing required fields (title, author, year) returns error, nothing written to DB
• Invalid year format (letters, future year beyond threshold, year 0) rejected
• Malformed URL in website field rejected
• Tag list with duplicates deduplicated before save
• XSS payload in title stored escaped, never executed

3.2 ThesisEditValidationTest.php

Same pattern for ThesisEditController:

• load() returns correct data for known ID, 404 for unknown
• collectJuryMembers() handles empty list, single member, duplicates
• handleWebsiteUrl() normalises http/https, rejects non-URLs

3.3 autofocusFieldForErrorTest.php

ThesisEditController has its own copy of this helper with different field names from CreateController. Verify:

• Returns correct field name for each known error key
• Returns null/default for unknown error key
• Does not leak CreateController field names

---

Phase 4 — Cleanup (no new tests, housekeeping)

Goal: Consolidate the two test systems.

• Migrate the 8 existing custom-runner tests to PHPUnit equivalents in tests/phpunit/
• Validate they all pass under vendor/bin/phpunit
• Remove run-tests.php and the old test files
• Add vendor/bin/phpunit to CI pipeline (or a Makefile target: make test)
• Generate a baseline coverage report: vendor/bin/phpunit --coverage-html coverage/
• Commit the coverage/ baseline so regressions are visible in future reports

---

What is explicitly out of scope

These classes are noted as hard to test and are not part of this plan. Do not attempt to test them without first adding dependency injection or a proper HTTP testing layer:

• App — session/header-heavy
• Dispatcher — requires full HTTP context
• FilepondHandler — requires $_FILES injection
• SmtpRelay — socket-level, needs mock SMTP server
• PeerTubeService — OAuth + HTTP, needs VCR-style mocking
• Parsedown — third-party, tested upstream

---

Summary

Phase	Scope	Effort	Requires
0 — Prerequisites	PHPUnit setup	~1h	Composer
1 — Pure logic	Crypto, Obfuscator, SystemController helpers, StudentEmail, OG tags	~2–3h	Nothing
2 — Integration	DB extended, ShareLink extended, RateLimit extended	~3–4h	Test DB
3 — Controller validation	Create/Edit validation paths	~2–3h	Test DB + HTTP mock
4 — Cleanup	Migrate old tests, CI, coverage report	~2h	Phase 1–3 done

Start with Phase 0 + Phase 1. They are fully unblocked and deliver the highest security-relevant coverage (Crypto, EmailObfuscator) with the least setup friction.