tests(theme): expand PHPUnit coverage of functions.php

[JohnRDOrazio]

Background

Following the Codecov rollout in #91 / #92, the wordpress-theme flag is currently at ~1% coverage. The theme PHPUnit <source> correctly includes both functions.php (~4900 lines) and includes/ (~80 lines), but only RelationshipHandlerTest.php exists — covering ~80 lines of includes/handlers/relationship.php. Everything in functions.php is uncovered.

This is the biggest single needle-mover for the project coverage number.

Suggested scope

Add Brain Monkey + Mockery tests for the REST endpoints currently registered in functions.php, using RelationshipHandlerTest.php as the pattern. In rough order of value (lines covered × user-facing impact):

• /cdcf/v1/team-member — cdcf_rest_create_team_member() (~180 lines). Cover happy path, the four council branches (board / ecclesial / technical / academic), the collab_post_id validation for academic_council, and the no-council "project-only member" branch.
• /cdcf/v1/community-channel, /cdcf/v1/local-group, /cdcf/v1/academic-collaboration — all three follow the same translate-then-link-to-Community-page pattern. One helper test plus per-endpoint specifics.
• /cdcf/v1/translate — OpenAI call should be mocked at the HTTP layer (Patchwork or wp_remote_post stub).
• /cdcf/v1/maintenance — Redis flag set/clear, capability check, duration_seconds clamping.
• /cdcf/v1/update-disposable-domains — GitHub fetch mocked, file-write side effect stubbed.
• The Polylang admin-language seeding hook + the Team Members council submenu / pre_get_posts filter (added in feat(theme): group admin CPTs and polish admin UX #99).

Out of scope here

• ACF field-group registration (configuration, not branching logic)
• The acf/init REST-meta bridging hook (covered indirectly by any write-path test)
• Admin sidebar menu structure (visual; testing it via Brain Monkey is high-effort, low-value)

Why now

The Codecov plumbing is in place but the theme number is misleading without more tests. Each REST endpoint test added moves the wordpress-theme flag by ~3-5% and exercises the most user-facing PHP in the repo.

Related

• ci(test): aggregate coverage via Codecov #91 — Codecov aggregation (Phase 1 merged in ci(test): aggregate Vitest + PHPUnit coverage via Codecov (Phase 1, refs #91) #92, Phase 2 still open)
• feat(test): PHPUnit + Brain Monkey suites for plugin and theme (Refs #63) #88 — original PHPUnit suite setup that produced RelationshipHandlerTest.php

[JohnRDOrazio]

First endpoint landed in #102 — cdcf_rest_create_team_member extracted to includes/handlers/team-member.php and tested across all 17 branches. Theme suite: 14 → 35 tests, 29 → 84 assertions. Project coverage moved 6.21% → 9.13%.

Patch coverage on #102: 96.19%. The 4 lines flagged as missing:

• functions.php (1 line) — the new require_once for the extracted handler. Structurally untestable from PHPUnit without bootstrapping the whole theme.
• team-member.php (3 lines) — the wp-cron fallback branch. Tested by test_falls_back_to_wp_cron_when_enqueue_helper_missing (verified wp_schedule_single_event × 5 + spawn_cron × 5) but the test uses #[RunInSeparateProcess] because Brain Monkey eval-declares cdcf_enqueue_translation into PHP's symbol table on first stub, making the absence path unreachable in the parent process. PCOV doesn't always merge coverage data from child PHPUnit processes back into the parent's clover XML, so the lines show as uncovered.

Remaining work tracked here:

• /cdcf/v1/community-channel (cdcf_rest_create_community_channel)
• /cdcf/v1/local-group (cdcf_rest_create_local_group)
• /cdcf/v1/academic-collaboration (cdcf_rest_create_academic_collaboration)
• /cdcf/v1/translate
• /cdcf/v1/maintenance
• /cdcf/v1/update-disposable-domains
• Polylang admin-language seed hook + Team Members council pre_get_posts filter

The channel/group/collab trio follows the same translate-then-link pattern as team-member and should share most of the test scaffolding.

[JohnRDOrazio]

Closed by the final chunk merging in #106. Summary of the work:

Endpoint / Hook	PR	Notes
/cdcf/v1/team-member	#102	17 branches across 4 council variants + project-only mode
/cdcf/v1/community-channel, /local-group, /academic-collaboration	#103	Shared via CommunityHandlerTestBase
/cdcf/v1/update-disposable-domains	#104	+ fixed a latent PHP 8.4 fsync warning firing on every successful refresh
/cdcf/v1/translate	#105	Enqueue + post-resolution + parent propagation + attachment metadata copy
Polylang seed hook + Team Members council pre_get_posts filter	#106	The remaining admin-side hooks from #99
/cdcf/v1/maintenance	—	Already covered by the plugin's MaintenanceHandlerTest

Theme PHPUnit suite (from issue open → close):

• Tests: 14 → 116 (+102)
• Assertions: 29 → 269 (+240)
• wordpress-theme Codecov flag: 1% → 16% on the branch (will land on the main badge after this merges to main and Codecov re-evaluates)

functions.php shrank by ~600 lines as each handler / hook moved into includes/handlers/ or includes/admin/ — making them individually testable and easier to read.

Reusable scaffolding produced along the way:

• Brain Monkey stub-ordering pattern (declare stubs before overriding function_exists) documented in every test class
• CommunityHandlerTestBase abstract class for the three Community-page handlers
• WP_Query / WP_REST_Response / WP_REST_Request / WP_Error shims in tests/bootstrap.php
• Process-isolated wp-cron-fallback test pattern (#[RunInSeparateProcess] + #[PreserveGlobalState(false)]) — used in both TeamMemberHandlerTest and TranslateHandlerTest
• Patchwork redefinable-internals registry now includes file_put_contents + rename for the filesystem-failure tests in UpdateDisposableDomainsHandlerTest
• CDCF_DISPOSABLE_DOMAINS_FILE constant as a single source of truth for the blocklist path (both reader and writer)

The remaining 10 lines flagged as missing across the work are all structurally untestable from PHPUnit:

• functions.php require_once + hook-registration calls (execute at WP load time, not under the test bootstrap)
• The if (defined('ABSPATH') === false) { return; } guard inside each handler file (the bootstrap defines ABSPATH before requiring any of them, so the return; is unreachable)