test: add cohesive MacTrack suite

[somethingwithproof]

Summary

• add a Composer-independent runner that executes every existing MacTrack unit, integration, security, and static end-to-end test
• replace the non-runnable Pest 1.x split with one test entrypoint used directly and through Composer
• add fail-closed runner checks, production-helper contracts, a complete 22-table schema manifest, and clean-install Cacti 1.2.31 Docker coverage
• prevent repeated setup and reduce concurrent Default-site duplication while the database-scoped advisory lock is held, using a conditional insert, postcondition verification, lifecycle-safe web handling, an actionable CLI failure result, and web/poller recovery with backoff capped at one hour; durable name uniqueness remains tracked in bug: safely enforce MacTrack site-name uniqueness #360

Closes #357

Related to #355
Related to #356

Validation

• PHP 8.4 local suite: 16 test files, 0 failures
• CI fast matrix covers PHP 7.4 and PHP 8.1–8.4; its PHP 7.4 lane uses that runtime's parser to lint every tracked production PHP file
• clean Cacti 1.2.31 Docker install on MariaDB 10.11 and MySQL 8.0 with non-default database credentials: plugin install/enable, scanner-function rebuild, schema idempotency, held-lock timeout, an eight-process concurrent Default-site lifecycle, all 22 tables, and web smoke test
• SQL construction ratchets recognize function-built SQL while excluding object/static methods, with regression controls for sprintf(), str_replace(), helper calls, and method calls
• composer test and composer validate --strict
• actionlint .github/workflows/test-suite.yml
• shellcheck tests/e2e/*.sh
• git diff --check

Coordination

• fix: ship Net_DNS2 with the plugin again #345 changes dependency loading exercised by the same Docker smoke path. This PR deliberately does not duplicate that dependency fix and should be rebased if fix: ship Net_DNS2 with the plugin again #345 lands first.
• fix: make Composer runtime dependencies release-safe and prove scanner execution #343 owns the real-SNMP-agent and vendor-scanner fixture coverage; this PR uses deterministic boundary doubles plus real MariaDB/MySQL lifecycle tests and does not claim scanner protocol coverage.
• bug: make the 4.9 aggregated-port index migration safe and schema-consistent #359 tracks the separately discovered legacy 4.9 aggregated-port index migration defect, which needs representative legacy data and interruption testing before it is safe to change.
• bug: safely enforce MacTrack site-name uniqueness #360 tracks topology-independent site-name uniqueness and reconciliation of pre-existing duplicate names; this PR deliberately avoids reusing a deleted site's numeric ID because orphaned ARP/802.1X rows could then be misattributed.
• CLI plugin installer ignores plugin install-hook failure results cacti#8002 tracks the core 1.2 CLI installer ignoring a plugin install hook's strict false result; MacTrack therefore reports the incomplete Default-site setup and retries safely from the poller instead of risking a partially registered plugin by throwing.

[Copilot]

🟡 Changes recommended

The E2E runner’s DB readiness probe hard-codes credentials and can fail when DB_USER/DB_PASSWORD overrides are used, despite docker-compose supporting those overrides.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR introduces a cohesive, Composer-optional MacTrack test harness (unit/integration/security/static-e2e) and strengthens production lifecycle safety around Default-site seeding so database setup becomes idempotent and concurrency-safe.

Changes:

• Add tests/run.php standalone runner with inventory/fail-closed behavior plus supporting utilities (process runner, CLI guards, Git-tracked PHP manifesting, SQL-call analysis/ratchets, PHP 7.4 scanning).
• Add/expand integration and Docker E2E coverage (clean Cacti 1.2.31 install, schema manifest verification, schema idempotency, scanning-function rebuild, concurrent Default-site seeding).
• Update production Default-site handling: replace unconditional inserts with advisory-lock + conditional insert + postcondition verification, plus backoff-based retry and lifecycle-safe reporting in CLI/web/poller paths.

File summaries

File	Description
.gitattributes	Excludes tests/ from release archives via export-ignore.
.github/workflows/test-suite.yml	Adds CI workflow to run the cohesive suite across PHP versions plus Docker clean-install lanes.
CHANGELOG.md	Notes fix for #357 (Default site duplication on rerun).
README.md	Documents new standalone runner and Docker clean-install test path.
composer.json	Replaces Pest-based scripts with php tests/run.php ...; aligns platform to PHP 7.4.
composer.lock	Updates lockfile to reflect removal of Pest/PHPUnit dev dependencies and platform override.
includes/database.php	Implements idempotent/concurrency-safe Default-site seeding with advisory lock + retry/backoff helpers; seeds after full schema setup.
poller_mactrack.php	Invokes scheduled Default-site recovery (mactrack_retry_default_site) from the poller.
phpunit.xml.dist	Removes PHPUnit configuration (suite no longer runs via phpunit/pest).
setup.php	Propagates setup failure in CLI, uses prepared statements for plugin_config update, and triggers Default-site retry in upgrade checks.
tests/.htaccess	Denies web access to the tests/ tree.
tests/Integration/test_default_site_idempotency.php	Adds integration coverage for Default-site seeding idempotency, lock behavior, and backoff state machine.
tests/Integration/test_mactrack_filter_output_wiring.php	Adds CLI guard and improves assertion accounting/output.
tests/Integration/test_schema_definition.php	Verifies schema builder creates exactly the documented table set and critical schema elements.
tests/Pest/E2E/StaticEndpointSafetyTest.php	Removes obsolete Pest wrapper test.
tests/Pest/Integration/FilterOutputWiringTest.php	Removes obsolete Pest wrapper test.
tests/Pest/Unit/SecurityRegressionTest.php	Removes obsolete Pest wrapper test.
tests/Pest/Unit/XformMacAddressTest.php	Removes Pest-based unit tests superseded by standalone suite.
tests/Security/Php74CompatibilityTest.php	Replaces Pest tests with tracked-file PHP 7.4 scanner + php -l parse gate.
tests/Security/PreparedStatementConsistencyTest.php	Replaces simple “no raw DB calls” checks with SQL-call baselines/ratchets over tracked production PHP.
tests/Security/SetupStructureTest.php	Replaces Pest structure tests with standalone contract checks for setup.php.
tests/Security/WebExposureTest.php	Adds web-exposure gate for test harness (redirecting index, denied access, CLI guard enforcement).
tests/Security/WorkflowBranchCoverageTest.php	Ensures cohesive workflow branch coverage matches other workflows for push/PR events.
tests/Support/CactiStubs.php	Adds CLI guard and adjusts stubs to better match expected Cacti API signatures.
tests/Support/CliGuard.php	Adds token-based guard validator ensuring CLI-only tests exit early in web context.
tests/Support/E2eDatabaseGuard.php	Adds guard to prevent destructive DB operations outside disposable E2E DB naming.
tests/Support/Php74Scanner.php	Adds tokenizer-based detection of PHP 8+ functions/syntax tokens.
tests/Support/ProcessRunner.php	Adds a fail-closed process runner with safe environment handling (incl. Git env unsetting).
tests/Support/ProductionPhpManifest.php	Adds explicit production PHP manifest for tracked-file validation.
tests/Support/SchemaManifest.php	Adds schema manifest for table/column/index verification in tests.
tests/Support/SqlCallAnalyzer.php	Adds token-based SQL call analyzer to count raw/dynamic/prepared patterns.
tests/Support/StandaloneTest.php	Adds minimal assertion harness used by standalone test runner.
tests/Support/TestInventory.php	Adds inventory helper to enforce “no unclaimed PHP test files”.
tests/Support/TrackedPhpFiles.php	Adds Git-tracked PHP enumerator with fail-closed semantics when Git is unavailable/mismatched.
tests/Unit/test_device_type_sql_safety.php	Adds CLI guard and improves output to report assertion count.
tests/Unit/test_e2e_database_guard.php	Adds unit coverage for E2E DB disposable guard matching rules.
tests/Unit/test_filter_option_escaping.php	Removes old standalone XSS escaping check (covered elsewhere now).
tests/Unit/test_mactrack_functions.php	Adds standalone unit coverage for key production helper functions and key poller wiring expectations.
tests/Unit/test_runner_fail_closed.php	Adds runner self-test coverage for empty groups, silent tests, large stderr, and warnings.
tests/Unit/test_setup_failure_propagation.php	Adds unit coverage for setup failure propagation (CLI/web behaviors, backoff, logging, metadata writes).
tests/Unit/test_sql_call_analyzer.php	Adds unit coverage validating SQL analyzer behavior and error handling.
tests/Unit/test_tracked_php_files.php	Adds unit coverage asserting tracked PHP inventory/manifest behavior and fail-closed behavior without Git.
tests/bootstrap.php	Expands stubs and state capture for standalone testing (DB calls, config options, logs/messages).
tests/e2e/bootstrap-mactrack.sh	Adjusts clean-install bootstrap: imports cacti.sql via mysql client and runs destructive tests with guard validation.
tests/e2e/docker-compose.yml	Parameterizes DB image; uses disposable default DB name; updates healthcheck to mysqladmin ping.
tests/e2e/mactrack_concurrent_default_site.php	Adds destructive E2E concurrency/held-lock tests for Default-site seeding.
tests/e2e/mactrack_schema_idempotency.php	Adds destructive E2E test for schema setup idempotency and no Default resurrection.
tests/e2e/mactrack_scanning_functions.php	Adds destructive E2E test asserting scanning-function rebuild is idempotent.
tests/e2e/mactrack_smoke.php	Expands smoke test to validate schema manifest, core helper contracts, and Default seeded exactly once.
tests/e2e/run-mactrack-e2e.sh	Updates DB readiness probing and adds fail-closed timeout behavior before running bootstrap/smoke.
tests/e2e/test_mactrack_no_raw_filter_labels.php	Adds CLI guard and improves assertion accounting/output.
tests/fixtures/inventory/Security/ClaimedTest.php	Adds inventory fixture file for runner inventory testing.
tests/fixtures/inventory/Security/test_orphan.php	Adds orphan fixture file for inventory mismatch detection testing.
tests/fixtures/inventory/Unit/OrphanTest.php	Adds orphan fixture file for inventory mismatch detection testing.
tests/fixtures/inventory/Unit/test_claimed.php	Adds inventory fixture file for runner inventory testing.
tests/fixtures/no-tests/.gitkeep	Adds empty-dir keeper for inventory/runner fixtures.
tests/fixtures/test_large_stderr.php	Adds runner fixture emitting large stderr to validate runner doesn’t deadlock and fails actionable.
tests/fixtures/test_noop.php	Adds runner fixture to validate basic success reporting.
tests/fixtures/test_silent.php	Adds runner fixture to validate fail-closed on “no assertions completed” output.
tests/fixtures/test_warning.php	Adds runner fixture to validate fail-closed on stderr warnings even with 0 exit code.
tests/index.php	Redirects web requests away from tests (replaces Pest bootstrap config).
tests/run.php	Adds Composer-independent test entrypoint with group selection, inventory enforcement, and fail-closed execution rules.

Review details

• Files reviewed: 61/62 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.