From e5e419de71a0301b46a42bd540d48f0944b2d9e0 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Sun, 20 Sep 2026 10:04:52 -0400
Subject: [PATCH 1/7] fix: prevent repeated database setup from duplicating the
 Default site

Ports the Default-site concurrency/idempotency fix from PR #361 (by
Thomas Vincent / somethingwithproof) forward onto current develop.

mactrack_setup_database()/mactrack_database_upgrade() used a racy
check-then-insert ('if no rows, INSERT') to guarantee a Default site
existed, so two workers initializing at once (install + poller,
concurrent web requests) could both pass the check and insert
duplicate Default sites.

Adds mactrack_ensure_default_site(), which:
- takes a database-scoped GET_LOCK() advisory lock before the
  conditional INSERT ... SELECT ... WHERE NOT EXISTS, closing most of
  the race (durable name-level uniqueness is tracked separately in
  #360, since a reconnect can release the advisory lock)
- verifies the site actually exists after seeding/after failing to
  acquire the lock, rather than trusting the insert's own result
- tracks failed attempts with backoff (60s/5m/15m/30m/1h) via
  mt_default_site_seed_* config options, retried from
  plugin_mactrack_check_config() and the poller, instead of throwing
  and leaving the plugin partially registered

plugin_mactrack_install()/mactrack_setup_table_new() take an
 flag so an operator-triggered (re)install always
clears prior backoff state, while an automatic upgrade check preserves
it. plugin_mactrack_uninstall() cleans up the tracking settings.

Also hardens mactrack_check_upgrade()'s plugin_config UPDATE to use
prepared statements.

Closes #357
---
 CHANGELOG.md          |   1 +
 includes/database.php | 139 +++++++++++++++++++++++++++++++++++++++---
 poller_mactrack.php   |   3 +
 setup.php             |  46 ++++++++++----
 4 files changed, 169 insertions(+), 20 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 60e70930..43e0160e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 --- develop ---
 
+* issue#357: Prevent repeated database setup from duplicating the Default site
 * security: Restrict Net_DNS2 cache deserialization to DNS response classes
 * docs: Align the documented PHP floor with the PHP 7.4 compatibility contract
 * issue: Return the unformatted MAC when mt_mac_format is unset rather than a null address
diff --git a/includes/database.php b/includes/database.php
index 838bdcaf..1dbfb329 100644
--- a/includes/database.php
+++ b/includes/database.php
@@ -710,13 +710,138 @@ function mactrack_database_upgrade() {
 		db_execute("UPDATE mac_track_oui_database SET vendor_mac = REPLACE(vendor_mac, ':', '')");
 	}
 
-	// default site must exist
-	if (!db_fetch_cell('SELECT count(*) FROM mac_track_sites')) {
-		db_execute("INSERT INTO mac_track_sites (site_name, site_info) VALUES ('Default','Default site')");
+	mactrack_ensure_default_site();
+}
+
+function mactrack_site_configuration_exists(): bool {
+	$site_count = db_fetch_cell_prepared('SELECT COUNT(*) FROM mac_track_sites');
+
+	return is_numeric($site_count) && (int) $site_count > 0;
+}
+
+function mactrack_seed_default_site(?int $lock_timeout = null): bool {
+	global $database_default;
+
+	if (mactrack_site_configuration_exists()) {
+		return true;
+	}
+
+	$lock_timeout = $lock_timeout ?? (PHP_SAPI === 'cli' ? 10 : 2);
+	$lock_timeout = max(0, $lock_timeout);
+	// This advisory lock improves the legacy check-then-insert behavior, but a
+	// reconnect can release it. Database-enforced name uniqueness needs the
+	// duplicate-safe legacy migration tracked in #360.
+	$lock_name = 'mactrack.default.' . sha1((string) $database_default);
+	$locked    = db_fetch_cell_prepared('SELECT GET_LOCK(?, ?)', [$lock_name, $lock_timeout]);
+
+	if ((string) $locked !== '1') {
+		if (mactrack_site_configuration_exists()) {
+			return true;
+		}
+
+		cacti_log('Unable to acquire the MacTrack Default-site setup lock', false, 'MACTRACK');
+
+		return false;
+	}
+
+	try {
+		$inserted = (bool) db_execute_prepared(
+			'INSERT INTO mac_track_sites (site_name, site_info)
+			SELECT ?, ? FROM DUAL WHERE NOT EXISTS (SELECT 1 FROM mac_track_sites)',
+			['Default', 'Default site']
+		);
+
+		if (mactrack_site_configuration_exists()) {
+			return true;
+		}
+
+		cacti_log($inserted ? 'MacTrack site seeding completed without creating a site' : 'Unable to insert the default MacTrack site', false, 'MACTRACK');
+
+		return false;
+	} finally {
+		$released = db_fetch_cell_prepared('SELECT RELEASE_LOCK(?)', [$lock_name]);
+
+		if ((string) $released !== '1') {
+			cacti_log('MacTrack Default-site setup lock was not owned when release was attempted', false, 'MACTRACK');
+		}
 	}
 }
 
-function mactrack_setup_database() {
+function mactrack_reset_default_site_retry(): void {
+	set_config_option('mt_default_site_seed_pending', 'off');
+	set_config_option('mt_default_site_seed_attempts', '0');
+	set_config_option('mt_default_site_seed_next_retry', '0');
+}
+
+function mactrack_raise_default_site_error(int $attempts): void {
+	if ($attempts >= 5) {
+		$message = __('MacTrack could not initialize its Default site after repeated attempts. Review the Cacti log before continuing.', 'mactrack');
+	} else {
+		$message = __('MacTrack could not initialize its Default site. Review the Cacti log before continuing.', 'mactrack');
+	}
+
+	raise_message('mactrack_default_site_seed_failed', $message, MESSAGE_LEVEL_ERROR);
+}
+
+function mactrack_ensure_default_site(?bool $notify_operator = null, bool $notify_immediately = false): bool {
+	$notify_operator = $notify_operator ?? (PHP_SAPI !== 'cli');
+	$pending = read_config_option('mt_default_site_seed_pending', true) === 'on';
+	$attempts = max(0, (int) read_config_option('mt_default_site_seed_attempts', true));
+	$next_retry = max(0, (int) read_config_option('mt_default_site_seed_next_retry', true));
+
+	if ($pending && $next_retry > time()) {
+		// Another request or an administrator may have repaired the site while
+		// this worker was throttled. Clear stale retry state without taking the
+		// seed lock or attempting another insert.
+		if (mactrack_site_configuration_exists()) {
+			mactrack_reset_default_site_retry();
+
+			return true;
+		}
+
+		if ($notify_operator && ($notify_immediately || $attempts >= 5)) {
+			mactrack_raise_default_site_error($attempts);
+		}
+
+		return false;
+	}
+
+	try {
+		$seeded = mactrack_seed_default_site();
+	} catch (Throwable $exception) {
+		cacti_log('MacTrack Default-site initialization failed: ' . $exception->getMessage(), false, 'MACTRACK');
+		$seeded = false;
+	}
+
+	if ($seeded) {
+		mactrack_reset_default_site_retry();
+
+		return true;
+	}
+
+	$retry_delays = [60, 300, 900, 1800, 3600];
+	$attempts = min(5, $attempts + 1);
+	$delay = $retry_delays[$attempts - 1];
+	set_config_option('mt_default_site_seed_pending', 'on');
+	set_config_option('mt_default_site_seed_attempts', (string) $attempts);
+	set_config_option('mt_default_site_seed_next_retry', (string) (time() + $delay));
+
+	if ($notify_operator && ($notify_immediately || $attempts >= 5)) {
+		mactrack_raise_default_site_error($attempts);
+	}
+
+	return false;
+}
+
+function mactrack_retry_default_site(): bool {
+	if (read_config_option('mt_default_site_seed_pending', true) !== 'on') {
+		return true;
+	}
+
+	return mactrack_ensure_default_site();
+}
+
+function mactrack_setup_database(bool $notify_seed_failure = false) {
 	$data                  = [];
 	$data['columns'][]     = ['name' => 'row_id', 'unsigned' => true, 'type' => 'int(10)', 'NULL' => false, 'auto_increment' => true];
 	$data['columns'][]     = ['name' => 'site_id', 'unsigned' => true, 'type' => 'int(10)', 'NULL' => false, 'default' => '0'];
@@ -1121,9 +1246,6 @@ function mactrack_setup_database() {
 	$data['comment']   = '';
 	api_plugin_db_table_create('mactrack', 'mac_track_sites', $data);
 
-	// default site must exist
-	db_execute("INSERT INTO mac_track_sites (site_name, site_info) VALUES ('Default','Default site')");
-
 	$data              = [];
 	$data['columns'][] = ['name' => 'id', 'unsigned' => true, 'type' => 'int(10)', 'NULL' => false, 'auto_increment' => true];
 	$data['columns'][] = ['name' => 'name', 'type' => 'varchar(100)', 'NULL' => false, 'default' => ''];
@@ -1380,4 +1502,7 @@ function mactrack_setup_database() {
 			(description, vendor, device_type, sysDescr_match, sysObjectID_match, scanning_function, ip_scanning_function, dot1x_scanning_function, serial_number_oid, lowPort, highPort, disabled)
 			VALUES ('92xx Switch-default','Cisco','1','*CAT9K_LITE_IOSXE*','','get_IOS_dot1dTpFdbEntry_ports','get_standard_arp_table','0','',0,0,'on')");
 	}
+
+	// Seed only after the complete schema and built-in device types exist.
+	return mactrack_ensure_default_site($notify_seed_failure, $notify_seed_failure);
 }
diff --git a/poller_mactrack.php b/poller_mactrack.php
index 987f12ae..9f71a1da 100644
--- a/poller_mactrack.php
+++ b/poller_mactrack.php
@@ -47,8 +47,11 @@
 
 include('./include/cli_check.php');
 include_once($config['base_path'] . '/lib/poller.php');
+include_once($config['base_path'] . '/plugins/mactrack/includes/database.php');
 include_once($config['base_path'] . '/plugins/mactrack/lib/mactrack_functions.php');
 
+mactrack_retry_default_site();
+
 // install signal handlers for UNIX only
 if (function_exists('pcntl_signal')) {
 	pcntl_signal(SIGTERM, 'sig_handler');
diff --git a/setup.php b/setup.php
index b24f3492..83bd1cd1 100644
--- a/setup.php
+++ b/setup.php
@@ -22,7 +22,7 @@
  +-------------------------------------------------------------------------+
 */
 
-function plugin_mactrack_install() {
+function plugin_mactrack_install($operator_initiated = true) {
 	api_plugin_register_hook('mactrack', 'top_header_tabs',       'mactrack_show_tab',             'setup.php');
 	api_plugin_register_hook('mactrack', 'top_graph_header_tabs', 'mactrack_show_tab',             'setup.php');
 	api_plugin_register_hook('mactrack', 'config_arrays',         'mactrack_config_arrays',        'setup.php');
@@ -45,10 +45,21 @@ function plugin_mactrack_install() {
 	api_plugin_register_realm('mactrack', 'mactrack_view_ips.php,mactrack_view_arp.php,mactrack_view_macs.php,mactrack_view_dot1x.php,mactrack_view_sites.php,mactrack_view_devices.php,mactrack_view_interfaces.php,mactrack_view_graphs.php,mactrack_ajax.php', 'Mactrack Viewer', 1);
 	api_plugin_register_realm('mactrack', 'mactrack_ajax_admin.php,mactrack_devices.php,mactrack_snmp.php,mactrack_sites.php,mactrack_device_types.php,mactrack_utilities.php,mactrack_macwatch.php,mactrack_macauth.php,mactrack_vendormacs.php', 'Mactrack Administrator', 1);
 
-	mactrack_setup_table_new();
+	$site_ready = mactrack_setup_table_new($operator_initiated);
+
+	if (!$site_ready && PHP_SAPI === 'cli') {
+		fwrite(STDERR, "WARNING: MacTrack installed without a Default site; review the Cacti log. The poller will retry with backoff.\n");
+	}
+
+	return $site_ready;
 }
 
 function plugin_mactrack_uninstall() {
+	db_execute_prepared(
+		'DELETE FROM settings WHERE name IN (?, ?, ?)',
+		['mt_default_site_seed_pending', 'mt_default_site_seed_attempts', 'mt_default_site_seed_next_retry']
+	);
+
 	return true;
 }
 
@@ -94,7 +105,7 @@ function mactrack_check_upgrade() {
 		// if the plugin is installed and/or active
 		if (!cacti_sizeof($old) || $old['status'] == 1 || $old['status'] == 4) {
 			// re-register the hooks
-			plugin_mactrack_install();
+			plugin_mactrack_install(false);
 
 			if (api_plugin_is_enabled('mactrack')) {
 				// may sound ridiculous, but enables new hooks
@@ -133,15 +144,18 @@ function mactrack_check_upgrade() {
 
 		// update the plugin information
 		$info = plugin_mactrack_version();
-		$id   = db_fetch_cell("SELECT id FROM plugin_config WHERE directory='mactrack'");
-
-		db_execute("UPDATE plugin_config
-			SET name='" . $info['longname'] . "',
-			author='" . $info['author'] . "',
-			webpage='" . $info['homepage'] . "',
-			version='" . $info['version'] . "'
-			WHERE id='$id'");
+		$id   = db_fetch_cell_prepared('SELECT id FROM plugin_config WHERE directory = ?', ['mactrack']);
+
+		db_execute_prepared('UPDATE plugin_config
+			SET name = ?,
+			author = ?,
+			webpage = ?,
+			version = ?
+			WHERE id = ?',
+			[$info['longname'], $info['author'], $info['homepage'], $info['version'], $id]);
 	}
+
+	mactrack_retry_default_site();
 }
 
 function mactrack_db_table_exists($table) {
@@ -228,12 +242,18 @@ function mactrack_check_dependencies() {
 	return true;
 }
 
-function mactrack_setup_table_new() {
+function mactrack_setup_table_new($operator_initiated = true) {
 	global $config;
 
 	include_once($config['base_path'] . '/plugins/mactrack/includes/database.php');
 
-	mactrack_setup_database();
+	// Preserve a prior failed seed's backoff when an incomplete upgrade causes
+	// Cacti to re-enter this hook on a later request.
+	if ($operator_initiated || read_config_option('mt_default_site_seed_pending', true) !== 'on') {
+		mactrack_reset_default_site_retry();
+	}
+
+	return mactrack_setup_database(PHP_SAPI !== 'cli');
 }
 
 function mactrack_page_head() {

From f9b375a1b86f81e50e48c9f1afc7eb2d4fd12c9c Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Sun, 20 Sep 2026 10:22:38 -0400
Subject: [PATCH 2/7] test: adopt the shared Cacti plugin test framework (Pest
 + PHP 8.2 floor)

Replaces the plugin's ad-hoc snake_case standalone-script test suite and
its custom .github/workflows/test-suite.yml with the framework used
across other Cacti plugins (modeled on plugin_evidence): Pest via
Cacti's own Composer-managed vendor tree, tests/bootstrap-unit.php,
tests/TestCase.php, tests/Pest.php, tests/.cacti-version, and
phpunit.xml, run through .github/workflows/plugin-ci-workflow.yml
(PHP 8.2-8.4, CACTI/COMPOSER_ALLOW_SUPERUSER env vars, sudo composer
throughout, SHA-pinned actions).

Removes tests/Support/CactiStubs.php, the tests/e2e/ Docker harness,
and every snake_case test_*.php file, reorganizing coverage into
tests/Security, tests/Unit, and tests/Integration with PascalCase Pest
files:

- Security/Php82CompatibilityTest.php: renamed and adapted from
  test_php74_compatibility.php now that the plugin's floor is PHP 8.2,
  scanning for 8.3/8.4-only syntax instead of 8.0+ syntax.
- Security/PreparedStatementConsistencyTest.php: the raw-SQL-call
  ratchet from test_prepared_statement_consistency.php, rebaselined
  against current source.
- Security/SetupStructureTest.php: standard hook/realm/INFO structural
  checks, new to this plugin.
- Security/NetDns2SecurityTest.php: converted from
  test_net_dns2_cache_security.php + test_net_dns2_precedence.php.
- Security/SqlSafetyAndOutputEscapingTest.php: converted from
  test_device_type_sql_safety.php, re-verified against current source.
- Unit/MacFormattingTest.php, Unit/XformMacAddressTest.php: converted
  from test_mac_formatting.php and rewritten as PHPUnit data-provider
  tests covering xform_mac_address()'s ASCII/HEX-/binary paths.
- Unit/IgnorePortsPatternTest.php: converted from
  test_ignore_ports_pattern.php.
- Unit/DefaultSiteSeedingTest.php, Integration/DefaultSiteIdempotencyTest.php:
  new coverage for the mactrack_ensure_default_site()/
  mactrack_seed_default_site() advisory-lock seeding and retry/backoff
  state machine added in the prior commit (issue#357), including the
  install/upgrade entry points that call it.
- Integration/FilterOutputWiringTest.php: converted from
  test_mactrack_filter_output_wiring.php.

tests/bootstrap-unit.php extends the plugin_evidence model with an
in-memory config-option store (mactrack's retry state lives entirely in
read_config_option()/set_config_option()) and CactiStubs-style
SQL-fragment-matched return values for db_fetch_cell_prepared(), needed
to exercise the GET_LOCK/RELEASE_LOCK advisory-locking path.
---
 .github/workflows/plugin-ci-workflow.yml      | 166 +++---
 phpunit.xml                                   |  35 ++
 tests/.cacti-version                          |   1 +
 .../DefaultSiteIdempotencyTest.php            | 117 +++++
 tests/Integration/FilterOutputWiringTest.php  |  42 ++
 .../test_mactrack_filter_output_wiring.php    |  36 --
 tests/Pest.php                                |  14 +
 tests/Security/NetDns2SecurityTest.php        | 101 ++++
 tests/Security/Php82CompatibilityTest.php     | 113 +++++
 .../PreparedStatementConsistencyTest.php      |  80 +++
 tests/Security/SetupStructureTest.php         |  71 +++
 .../SqlSafetyAndOutputEscapingTest.php        | 116 +++++
 tests/Support/CactiStubs.php                  |  85 ----
 tests/TestCase.php                            |  48 ++
 tests/Unit/DefaultSiteSeedingTest.php         | 190 +++++++
 tests/Unit/IgnorePortsPatternTest.php         | 139 +++++
 tests/Unit/MacFormattingTest.php              |  67 +++
 tests/Unit/XformMacAddressTest.php            |  77 +++
 tests/Unit/test_device_type_sql_safety.php    | 161 ------
 tests/Unit/test_filter_option_escaping.php    |  19 -
 tests/Unit/test_ignore_ports_pattern.php      | 105 ----
 tests/Unit/test_mac_formatting.php            |  54 --
 tests/Unit/test_net_dns2_cache_security.php   |  66 ---
 tests/Unit/test_net_dns2_precedence.php       |  45 --
 tests/Unit/test_php74_compatibility.php       |  47 --
 .../test_prepared_statement_consistency.php   |  76 ---
 tests/bootstrap-unit.php                      | 474 ++++++++++++++++++
 tests/e2e/Dockerfile                          |  12 -
 tests/e2e/bootstrap-mactrack.sh               |  32 --
 tests/e2e/docker-compose.yml                  |  47 --
 tests/e2e/mactrack_smoke.php                  |  37 --
 tests/e2e/run-mactrack-e2e.sh                 |  28 --
 .../test_mactrack_no_raw_filter_labels.php    |  36 --
 33 files changed, 1765 insertions(+), 972 deletions(-)
 create mode 100644 phpunit.xml
 create mode 100644 tests/.cacti-version
 create mode 100644 tests/Integration/DefaultSiteIdempotencyTest.php
 create mode 100644 tests/Integration/FilterOutputWiringTest.php
 delete mode 100644 tests/Integration/test_mactrack_filter_output_wiring.php
 create mode 100644 tests/Pest.php
 create mode 100644 tests/Security/NetDns2SecurityTest.php
 create mode 100644 tests/Security/Php82CompatibilityTest.php
 create mode 100644 tests/Security/PreparedStatementConsistencyTest.php
 create mode 100644 tests/Security/SetupStructureTest.php
 create mode 100644 tests/Security/SqlSafetyAndOutputEscapingTest.php
 delete mode 100644 tests/Support/CactiStubs.php
 create mode 100644 tests/TestCase.php
 create mode 100644 tests/Unit/DefaultSiteSeedingTest.php
 create mode 100644 tests/Unit/IgnorePortsPatternTest.php
 create mode 100644 tests/Unit/MacFormattingTest.php
 create mode 100644 tests/Unit/XformMacAddressTest.php
 delete mode 100644 tests/Unit/test_device_type_sql_safety.php
 delete mode 100644 tests/Unit/test_filter_option_escaping.php
 delete mode 100644 tests/Unit/test_ignore_ports_pattern.php
 delete mode 100644 tests/Unit/test_mac_formatting.php
 delete mode 100644 tests/Unit/test_net_dns2_cache_security.php
 delete mode 100644 tests/Unit/test_net_dns2_precedence.php
 delete mode 100644 tests/Unit/test_php74_compatibility.php
 delete mode 100644 tests/Unit/test_prepared_statement_consistency.php
 create mode 100644 tests/bootstrap-unit.php
 delete mode 100644 tests/e2e/Dockerfile
 delete mode 100755 tests/e2e/bootstrap-mactrack.sh
 delete mode 100644 tests/e2e/docker-compose.yml
 delete mode 100644 tests/e2e/mactrack_smoke.php
 delete mode 100755 tests/e2e/run-mactrack-e2e.sh
 delete mode 100644 tests/e2e/test_mactrack_no_raw_filter_labels.php

diff --git a/.github/workflows/plugin-ci-workflow.yml b/.github/workflows/plugin-ci-workflow.yml
index de55df0d..3365987f 100644
--- a/.github/workflows/plugin-ci-workflow.yml
+++ b/.github/workflows/plugin-ci-workflow.yml
@@ -31,16 +31,20 @@ on:
       - main
       - develop
 
+env:
+  CACTI: 1.2.x
+  COMPOSER_ALLOW_SUPERUSER: 1
+
 jobs:
   integration-test:
     runs-on: ${{ matrix.os }}
-    
+
     strategy:
       fail-fast: false
       matrix:
-        php: ['8.1', '8.2', '8.3', '8.4']
+        php: ['8.2', '8.3', '8.4']
         os: [ubuntu-latest]
-    
+
     services:
       mariadb:
         image: mariadb:10.6
@@ -56,43 +60,44 @@ jobs:
           --health-interval=10s
           --health-timeout=5s
           --health-retries=3
-    
+
     name: PHP ${{ matrix.php }} Integration Test on ${{ matrix.os }}
-    
+
     steps:
     - name: Checkout Cacti
-      uses: actions/checkout@v7
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       with:
         repository: Cacti/cacti
-        ref: release/1.2.31
+        ref: ${{ env.CACTI }}
         path: cacti
-    
-    - name: Checkout mactrack Plugin
-      uses: actions/checkout@v7
+
+    - name: Checkout MacTrack Plugin
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       with:
         path: cacti/plugins/mactrack
-    
+
     - name: Install PHP ${{ matrix.php }}
-      uses: shivammathur/setup-php@v2
+      uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
       with:
         php-version: ${{ matrix.php }}
-        extensions: intl, mysql, gd, ldap, gmp, xml, curl, json, mbstring
+        extensions: intl, mysql, gd, ldap, gmp, xml, curl, json, mbstring, snmp
         ini-values: "post_max_size=256M, max_execution_time=60, date.timezone=America/New_York"
-    
+        coverage: xdebug
+
     - name: Check PHP version
       run: php -v
-    
+
     - name: Run apt-get update
       run: sudo apt-get update
-    
+
     - name: Install System Dependencies
       run: sudo apt-get install -y apache2 snmp snmpd rrdtool fping
-    
+
     - name: Start SNMPD Agent and Test
       run: |
         sudo systemctl start snmpd
         sudo snmpwalk -c public -v2c -On localhost .1.3.6.1.2.1.1
-    
+
     - name: Setup Permissions
       run: |
         sudo chown -R www-data:runner ${{ github.workspace }}/cacti
@@ -100,12 +105,12 @@ jobs:
         sudo find ${{ github.workspace }}/cacti -type f -exec chmod 664 {} \;
         sudo chmod +x ${{ github.workspace }}/cacti/cmd.php
         sudo chmod +x ${{ github.workspace }}/cacti/poller.php
-    
+
     - name: Create MySQL Config
       run: |
         echo -e "[client]\nuser = root\npassword = cactiroot\nhost = 127.0.0.1\n" > ~/.my.cnf
         cat ~/.my.cnf
-    
+
     - name: Initialize Cacti Database
       env:
         MYSQL_AUTH_USR: '--defaults-file=~/.my.cnf'
@@ -117,21 +122,29 @@ jobs:
         mysql $MYSQL_AUTH_USR -e "FLUSH PRIVILEGES;"
         mysql $MYSQL_AUTH_USR cacti < ${{ github.workspace }}/cacti/cacti.sql
         mysql $MYSQL_AUTH_USR -e "INSERT INTO settings (name, value) VALUES ('path_php_binary', '/usr/bin/php')" cacti
-    
+
     - name: Validate composer files
       run: |
         cd ${{ github.workspace }}/cacti
         if [ -f composer.json ]; then
-          composer validate --strict || true
+          sudo composer validate --strict || true
         fi
-    
+
     - name: Install Composer Dependencies
       run: |
         cd ${{ github.workspace }}/cacti
         if [ -f composer.json ]; then
-          sudo composer install --prefer-dist --no-progress
+          sudo composer config --no-plugins allow-plugins.pestphp/pest-plugin true
+          sudo composer require --no-progress --no-interaction "pestphp/pest: ^3" "pestphp/pest-plugin-drift: ^3.0"
+          sudo rm -f composer.lock
+          sudo composer install --dev --no-progress
         fi
-    
+
+    - name: Restore vendor ownership for Pest
+      run: |
+        cd ${{ github.workspace }}/cacti
+        sudo chown -R runner:runner include/vendor composer.lock
+
     - name: Create Cacti config.php
       run: |
         cat ${{ github.workspace }}/cacti/include/config.php.dist | \
@@ -140,96 +153,88 @@ jobs:
         sed -r "s/'cactiuser'/'cactiuser'/g" | \
         sed -r "s/'cactiuser'/'cactiuser'/g" > ${{ github.workspace }}/cacti/include/config.php
         sudo chmod 664 ${{ github.workspace }}/cacti/include/config.php
-    
+
     - name: Configure Apache
       run: |
         cat << 'EOF' | sed 's#GITHUB_WORKSPACE#${{ github.workspace }}#g' > /tmp/cacti.conf
         <VirtualHost *:80>
           ServerAdmin webmaster@localhost
           DocumentRoot GITHUB_WORKSPACE/cacti
-          
+
           <Directory GITHUB_WORKSPACE/cacti>
             Options Indexes FollowSymLinks
             AllowOverride All
             Require all granted
           </Directory>
-          
+
           ErrorLog ${APACHE_LOG_DIR}/error.log
           CustomLog ${APACHE_LOG_DIR}/access.log combined
         </VirtualHost>
         EOF
         sudo cp /tmp/cacti.conf /etc/apache2/sites-available/000-default.conf
         sudo systemctl restart apache2
-    
+
     - name: Install Cacti via CLI
       run: |
         cd ${{ github.workspace }}/cacti
         sudo php cli/install_cacti.php --accept-eula --install --force
 
-    - name: Install Mactrack Composer Dependencies
-      run: |
-        cd ${{ github.workspace }}/cacti/plugins/mactrack
-        if [ -f composer.json ]; then
-          sudo composer install --no-dev --prefer-dist --no-progress --no-interaction
-        fi
-    
-    - name: Install mactrack Plugin
+    - name: Install MacTrack Plugin
       run: |
         cd ${{ github.workspace }}/cacti
         sudo php cli/plugin_manage.php --plugin=mactrack --install --enable
 
-#    - name: import mactrack Plugin Sample Data
-#      run: |
-#        cd ${{ github.workspace }}/cacti/plugins/mactrack
-#        sudo php cli_import.php --filename=.github/workflows/mactrack_sample_data.xml
-#        if [ $? -ne 0 ]; then
-#          echo "Failed to import Thold sample data"
-#          exit 1
-#        fi
-    
     - name: Check PHP Syntax for Plugin
       run: |
         cd ${{ github.workspace }}/cacti/plugins/mactrack
-        find . -path './vendor' -prune -o -name '*.php' -print0 | xargs -0 -n1 php -l
+        if find . -name '*.php' -exec php -l {} 2>&1 \; | grep -iv 'no syntax errors detected'; then
+          echo "Syntax errors found!"
+          exit 1
+        fi
 
-    # Cacti 1.2.31 has no .phpstan.neon / lint scripts; only touch them when present.
-    - name: Remove the plugins directory exclusion from the .phpstan.neon
+    - name: Set expected Cacti version for unit tests
+      run: echo -n "${{ env.CACTI }}" | sudo tee ${{ github.workspace }}/cacti/plugins/mactrack/tests/.cacti-version > /dev/null
+
+    - name: Run Pest Unit Tests
+      env:
+        COMPOSER_ROOT_VERSION: 1.3.0-dev
       run: |
-        if [ -f .phpstan.neon ]; then
-          sed '/plugins/d' -i .phpstan.neon
-        else
-          echo '.phpstan.neon not present; skipping'
-        fi
+        cd ${{ github.workspace }}/cacti
+        include/vendor/bin/pest --configuration=plugins/mactrack/phpunit.xml \
+          --coverage-clover=plugins/mactrack/coverage/clover.xml
+
+    - name: Upload coverage report
+      if: always()
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+      with:
+        name: coverage-php${{ matrix.php }}
+        path: ${{ github.workspace }}/cacti/plugins/mactrack/coverage/
+        if-no-files-found: warn
+
+    - name: Remove the plugins directory exclusion from the .phpstan.neon
+      if: ${{ env.CACTI != '1.2.x' }}
+      run: sed '/plugins/d' -i .phpstan.neon
       working-directory: ${{ github.workspace }}/cacti
 
     - name: Mark composer scripts executable
-      run: |
-        if [ -d "${{ github.workspace }}/cacti/include/vendor/bin" ]; then
-          sudo find "${{ github.workspace }}/cacti/include/vendor/bin" -maxdepth 1 -type f -exec chmod +x {} +
-        fi
+      if: ${{ env.CACTI != '1.2.x' }}
+      run: sudo chmod +x ${{ github.workspace }}/cacti/include/vendor/bin/*
 
     - name: Run Linter on base code
-      run: |
-        if composer run-script --list | grep -qE '^  lint'; then
-          composer run-script lint ${{ github.workspace }}/cacti/plugins/mactrack
-        else
-          echo 'Composer lint script is not defined; skipping.'
-        fi
+      if: ${{ env.CACTI != '1.2.x' }}
+      run: sudo composer run-script lint ${{ github.workspace }}/cacti/plugins/mactrack
       working-directory: ${{ github.workspace }}/cacti
 
     - name: Checking coding standards on base code
-      run: |
-        if composer run-script --list | grep -qE '^  phpcsfixer'; then
-          composer run-script phpcsfixer ${{ github.workspace }}/cacti/plugins/mactrack
-        else
-          echo 'Composer phpcsfixer script is not defined; skipping.'
-        fi
+      if: ${{ env.CACTI != '1.2.x' }}
+      run: sudo composer run-script phpcsfixer ${{ github.workspace }}/cacti/plugins/mactrack
+      working-directory: ${{ github.workspace }}/cacti
+
+    - name: Run PHPStan at Level 6 on base code outside of Composer due to technical issues
+      if: ${{ env.CACTI != '1.2.x' }}
+      run: sudo ./include/vendor/bin/phpstan analyze --level 6 ${{ github.workspace }}/cacti/plugins/mactrack
       working-directory: ${{ github.workspace }}/cacti
 
-#    - name: Run PHPStan at Level 6 on base code outside of Composer due to technical issues
-#      run: ./include/vendor/bin/phpstan analyze --level 6 ${{ github.workspace }}/cacti/plugins/mactrack
-#      working-directory: ${{ github.workspace }}/cacti
-    
     - name: Re-apply web user ownership before polling
       run: |
         # Ancestor directories above the checkout (e.g. /home/runner, .../work)
@@ -251,23 +256,12 @@ jobs:
       run: |
         cd ${{ github.workspace }}/cacti
         sudo -u www-data php poller.php --poller=1 --force --debug
+
         if ! grep -q "SYSTEM STATS" log/cacti.log; then
           echo "Cacti poller did not finish successfully"
           cat log/cacti.log
           exit 1
         fi
-    
-    # The e2e scripts need the live Cacti and database this job already built.
-    - name: Run plugin e2e tests
-      run: |
-        rc=0
-        for f in tests/e2e/*.php; do
-          [ -f "$f" ] || continue
-          printf '%s: ' "$f"
-          php "$f" || rc=1
-        done
-        exit $rc
-      working-directory: ${{ github.workspace }}/cacti/plugins/mactrack
 
     - name: View Cacti Logs
       if: always()
diff --git a/phpunit.xml b/phpunit.xml
new file mode 100644
index 00000000..6564cb42
--- /dev/null
+++ b/phpunit.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../include/vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="tests/bootstrap-unit.php"
+         cacheDirectory=".phpunit.cache"
+         colors="true"
+         failOnWarning="true"
+         failOnNotice="true"
+         failOnDeprecation="true"
+         beStrictAboutOutputDuringTests="false">
+    <php>
+        <ini name="error_reporting" value="-1"/>
+        <env name="CACTI_TEST_BOOTSTRAP" value="1"/>
+    </php>
+    <testsuites>
+        <testsuite name="Plugin MacTrack">
+            <directory>tests/Security</directory>
+            <directory>tests/Unit</directory>
+            <directory>tests/Integration</directory>
+        </testsuite>
+    </testsuites>
+
+    <!--
+        Pest reads this PHPUnit-compatible configuration through Cacti's
+        Composer-managed vendor tree, checked out alongside this plugin by
+        the CI workflow (see .github/workflows/plugin-ci-workflow.yml).
+    -->
+    <source>
+        <include>
+            <file>setup.php</file>
+            <file>includes/database.php</file>
+            <file>lib/mactrack_functions.php</file>
+        </include>
+    </source>
+</phpunit>
diff --git a/tests/.cacti-version b/tests/.cacti-version
new file mode 100644
index 00000000..c971a7a8
--- /dev/null
+++ b/tests/.cacti-version
@@ -0,0 +1 @@
+1.2.x
diff --git a/tests/Integration/DefaultSiteIdempotencyTest.php b/tests/Integration/DefaultSiteIdempotencyTest.php
new file mode 100644
index 00000000..f2562f31
--- /dev/null
+++ b/tests/Integration/DefaultSiteIdempotencyTest.php
@@ -0,0 +1,117 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/**
+ * End-to-end coverage of the install/upgrade entry points that wire into
+ * mactrack_ensure_default_site() (issue#357): a full mactrack_setup_database()
+ * run (every table, plus device-type seeding) followed by the Default-site
+ * seed, exercised the way plugin_mactrack_install()/mactrack_check_upgrade()
+ * actually call it, rather than the seeding function in isolation.
+ */
+final class DefaultSiteIdempotencyTest extends TestCase {
+	/**
+	 * @return void
+	 */
+	public static function setUpBeforeClass(): void {
+		self::loadPluginSource('includes/database.php');
+		self::loadPluginSource('setup.php');
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testOperatorInitiatedInstallSeedsTheDefaultSiteOnce(): void {
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'GET_LOCK', '1');
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'RELEASE_LOCK', '1');
+		mactrack_test_queue_return('db_fetch_cell_prepared', '0');
+		mactrack_test_queue_return('db_fetch_cell_prepared', '1');
+		mactrack_test_queue_return('db_execute_prepared', true);
+
+		$this->assertTrue(mactrack_setup_table_new(true));
+		$this->assertSame('off', read_config_option('mt_default_site_seed_pending'));
+
+		$inserted = array_filter(
+			array_column($GLOBALS['__test_db_calls'], 'sql'),
+			static fn ($sql) => strpos($sql, 'INSERT INTO mac_track_sites') !== false
+		);
+		$this->assertCount(1, $inserted, 'Exactly one Default-site insert should have been attempted');
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testReenteringUpgradeAfterASuccessfulSeedDoesNotInsertAgain(): void {
+		// The site already exists (e.g. install already succeeded); a later
+		// automatic upgrade check must not attempt another insert.
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'COUNT(*) FROM mac_track_sites', '1');
+
+		$this->assertTrue(mactrack_setup_table_new(false));
+
+		foreach ($GLOBALS['__test_db_calls'] as $call) {
+			$this->assertStringNotContainsString('INSERT INTO mac_track_sites', $call['sql']);
+			$this->assertStringNotContainsString('GET_LOCK', $call['sql']);
+		}
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testAnOperatorInitiatedReinstallClearsAPriorBackoffEvenWhileThrottled(): void {
+		set_config_option('mt_default_site_seed_pending', 'on');
+		set_config_option('mt_default_site_seed_attempts', '4');
+		set_config_option('mt_default_site_seed_next_retry', (string) (time() + 3600));
+
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'GET_LOCK', '1');
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'RELEASE_LOCK', '1');
+		mactrack_test_queue_return('db_fetch_cell_prepared', '0');
+		mactrack_test_queue_return('db_fetch_cell_prepared', '1');
+		mactrack_test_queue_return('db_execute_prepared', true);
+
+		$this->assertTrue(mactrack_setup_table_new(true));
+		$this->assertSame('off', read_config_option('mt_default_site_seed_pending'));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testAnAutomaticUpgradePreservesAPriorBackoffWindow(): void {
+		$future = (string) (time() + 3600);
+		set_config_option('mt_default_site_seed_pending', 'on');
+		set_config_option('mt_default_site_seed_attempts', '2');
+		set_config_option('mt_default_site_seed_next_retry', $future);
+
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'COUNT(*) FROM mac_track_sites', '0');
+
+		$this->assertFalse(mactrack_setup_table_new(false));
+		$this->assertSame('on', read_config_option('mt_default_site_seed_pending'));
+		$this->assertSame($future, read_config_option('mt_default_site_seed_next_retry'));
+
+		foreach ($GLOBALS['__test_db_calls'] as $call) {
+			$this->assertStringNotContainsString('GET_LOCK', $call['sql']);
+		}
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testInstallReturnsTheSeedResultForTheCallerToAct(): void {
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'GET_LOCK', '0');
+		mactrack_test_queue_return('db_fetch_cell_prepared', '0');
+
+		$this->assertFalse(plugin_mactrack_install());
+		$this->assertSame('on', read_config_option('mt_default_site_seed_pending'));
+	}
+}
diff --git a/tests/Integration/FilterOutputWiringTest.php b/tests/Integration/FilterOutputWiringTest.php
new file mode 100644
index 00000000..488b817b
--- /dev/null
+++ b/tests/Integration/FilterOutputWiringTest.php
@@ -0,0 +1,42 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/*
+ * Confirms the filter-driven views actually wire their labels through
+ * html_escape() before rendering, rather than only asserting that
+ * html_escape() exists somewhere in the plugin.
+ */
+describe('filter output escaping wiring in mactrack', function () {
+	$checks = [
+		'mactrack_view_macs.php' => [
+			"html_escape(\$site['site_name'])",
+			"html_escape(\$filter_device['device_name'] . '(' . \$filter_device['hostname'] . ')')",
+		],
+		'mactrack_device_types.php' => [
+			"html_escape(\$type['vendor'])",
+		],
+	];
+
+	foreach ($checks as $file => $patterns) {
+		foreach ($patterns as $pattern) {
+			it("renders {$pattern} in {$file}", function () use ($file, $pattern) {
+				$source = plugin_test_read_source($file);
+
+				expect($source)->toContain($pattern);
+			});
+		}
+	}
+});
diff --git a/tests/Integration/test_mactrack_filter_output_wiring.php b/tests/Integration/test_mactrack_filter_output_wiring.php
deleted file mode 100644
index 8738ef70..00000000
--- a/tests/Integration/test_mactrack_filter_output_wiring.php
+++ /dev/null
@@ -1,36 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- +-------------------------------------------------------------------------+
- | Cacti: The Complete RRDTool-based Graphing Solution                     |
- +-------------------------------------------------------------------------+
-*/
-
-$checks = [
-	__DIR__ . '/../../mactrack_view_macs.php' => [
-		"html_escape(\$site['site_name'])",
-		"html_escape(\$filter_device['device_name'] . '(' . \$filter_device['hostname'] . ')')",
-	],
-	__DIR__ . '/../../mactrack_device_types.php' => [
-		"html_escape(\$type['vendor'])",
-	],
-];
-
-foreach ($checks as $path => $patterns) {
-	$contents = file_get_contents($path);
-
-	if ($contents === false) {
-		fwrite(STDERR, "Unable to read {$path}\n");
-		exit(1);
-	}
-
-	foreach ($patterns as $pattern) {
-		if (strpos($contents, $pattern) === false) {
-			fwrite(STDERR, "Missing expected escaped output: {$pattern}\n");
-			exit(1);
-		}
-	}
-}
-
-print "OK\n";
diff --git a/tests/Pest.php b/tests/Pest.php
new file mode 100644
index 00000000..c639e23b
--- /dev/null
+++ b/tests/Pest.php
@@ -0,0 +1,14 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+*/
+
+/*
+ * Pest configuration file. The bootstrap is loaded via phpunit.xml's
+ * bootstrap attribute (tests/bootstrap-unit.php), which requires Cacti's
+ * own Composer-managed vendor tree checked out by the CI workflow.
+ */
diff --git a/tests/Security/NetDns2SecurityTest.php b/tests/Security/NetDns2SecurityTest.php
new file mode 100644
index 00000000..ddfe9e5f
--- /dev/null
+++ b/tests/Security/NetDns2SecurityTest.php
@@ -0,0 +1,101 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+require_once __DIR__ . '/../../Net/DNS2.php';
+
+class MactrackNetDns2TestCache extends Net_DNS2_Cache {
+	public function seed($key, $value) {
+		$this->cache_serializer = 'serialize';
+		$this->cache_data[$key] = ['object' => serialize($value)];
+	}
+}
+
+class MactrackNetDns2UnserializeProbe {
+	public static $awakened = false;
+
+	public function __wakeup() {
+		self::$awakened = true;
+	}
+}
+
+describe('Net_DNS2 cache deserialization safety in mactrack', function () {
+	it('restores a valid DNS response payload from the cache', function () {
+		$cache      = new MactrackNetDns2TestCache();
+		$reflection = new ReflectionClass('Net_DNS2_Packet_Response');
+		$response   = $reflection->newInstanceWithoutConstructor();
+
+		$response->rdata      = '';
+		$response->rdlength   = 0;
+		$response->header     = null;
+		$response->question   = [];
+		$response->answer     = [];
+		$response->authority  = [];
+		$response->additional = [];
+
+		$cache->seed('response', $response);
+
+		expect($cache->get('response'))->toBeInstanceOf(Net_DNS2_Packet_Response::class);
+	});
+
+	it('refuses to instantiate an unexpected class from a cache payload', function () {
+		MactrackNetDns2UnserializeProbe::$awakened = false;
+
+		$cache = new MactrackNetDns2TestCache();
+		$cache->seed('probe', new MactrackNetDns2UnserializeProbe());
+
+		expect($cache->get('probe'))->toBeFalse();
+		expect(MactrackNetDns2UnserializeProbe::$awakened)->toBeFalse();
+	});
+
+	it('disables arbitrary class construction for both cache metadata loads', function () {
+		foreach (['Net/DNS2/Cache/File.php', 'Net/DNS2/Cache/Shm.php'] as $relative) {
+			$source = file_get_contents(__DIR__ . '/../../' . $relative);
+
+			expect($source)->not->toBeFalse("Unable to read {$relative}");
+			expect(substr_count($source, "['allowed_classes' => false]"))->toBe(2, "{$relative} must disable classes for both metadata loads");
+		}
+	});
+});
+
+describe('Net_DNS2 include-path precedence in mactrack', function () {
+	it('loads the bundled resolver even when a same-named class exists earlier on the include path', function () {
+		$temporary = sys_get_temp_dir() . '/mactrack_dns_shadow_' . getmypid();
+		$shadow    = $temporary . '/Net/DNS2';
+
+		expect(mkdir($shadow, 0700, true))->toBeTrue('Unable to create the DNS shadow fixture directory');
+		expect(file_put_contents($shadow . '/Resolver.php', "<?php\nclass Mactrack_Shadow_Net_DNS2_Resolver {}\n"))->not->toBeFalse();
+
+		$plugin_root = realpath(__DIR__ . '/../..');
+		set_include_path($plugin_root . PATH_SEPARATOR . $temporary . PATH_SEPARATOR . get_include_path());
+
+		try {
+			require_once $plugin_root . '/Net/DNS2.php';
+
+			expect(class_exists('Net_DNS2_Resolver'))->toBeTrue('Bundled Net_DNS2 resolver did not autoload');
+
+			$reflection = new ReflectionClass('Net_DNS2_Resolver');
+			$resolved   = realpath((string) $reflection->getFileName());
+			$expected   = realpath($plugin_root . '/Net/DNS2/Resolver.php');
+
+			expect($resolved)->toBe($expected, 'A shadowed path resolved the bundled resolver to the wrong file');
+		} finally {
+			@unlink($shadow . '/Resolver.php');
+			@rmdir($shadow);
+			@rmdir($temporary . '/Net');
+			@rmdir($temporary);
+		}
+	});
+});
diff --git a/tests/Security/Php82CompatibilityTest.php b/tests/Security/Php82CompatibilityTest.php
new file mode 100644
index 00000000..8adcd618
--- /dev/null
+++ b/tests/Security/Php82CompatibilityTest.php
@@ -0,0 +1,113 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/*
+ * mactrack_test_production_php_files() is defined in tests/bootstrap-unit.php
+ * so both this file and PreparedStatementConsistencyTest.php can share it.
+ */
+
+describe('PHP 8.2 compatibility in mactrack', function () {
+	$files = mactrack_test_production_php_files();
+
+	// The plugin's PHP floor is 8.2, so 8.0/8.1 syntax (str_contains, match,
+	// nullsafe, constructor promotion, union types) is allowed. These checks
+	// instead guard against syntax/functions that require PHP 8.3 or 8.4,
+	// which would break the 8.2 leg of the CI matrix, plus functions removed
+	// well before 8.2 that would break every leg.
+	it('does not use each() (removed in PHP 8.0)', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+			expect(preg_match('/\beach\s*\(/', $c))->toBe(0, "{$f} uses each() (removed in PHP 8.0)");
+		}
+	});
+
+	it('does not use create_function() (removed in PHP 8.0)', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+			expect(preg_match('/\bcreate_function\s*\(/', $c))->toBe(0, "{$f} uses create_function() (removed in PHP 8.0)");
+		}
+	});
+
+	it('does not use curly-brace string offset access (removed in PHP 8.0)', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+			expect(preg_match('/\$\w+\s*\{\s*\d+\s*\}/', $c))->toBe(0, "{$f} uses curly-brace string offset access (removed in PHP 8.0)");
+		}
+	});
+
+	it('does not use json_validate() (PHP 8.3)', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+			expect(preg_match('/\bjson_validate\s*\(/', $c))->toBe(0, "{$f} uses json_validate() (PHP 8.3)");
+		}
+	});
+
+	it('does not use dynamic class constant fetch syntax (PHP 8.3)', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+			expect(preg_match('/\w+::\{.+\}/', $c))->toBe(0, "{$f} uses dynamic class constant fetch (PHP 8.3)");
+		}
+	});
+
+	it('does not use typed class constants (PHP 8.3)', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+			expect(preg_match('/\b(?:public|private|protected|final)\s+const\s+\??[\w|]+\s+\w+\s*=/', $c))->toBe(0,
+				"{$f} uses typed class constants (PHP 8.3)"
+			);
+		}
+	});
+
+	it('does not use the #[Override] attribute (PHP 8.4)', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+			expect(preg_match('/#\[\s*\\\\?Override\s*\]/', $c))->toBe(0, "{$f} uses #[Override] attribute (PHP 8.4)");
+		}
+	});
+
+	it('does not use asymmetric visibility (PHP 8.4)', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+			expect(preg_match('/\b(?:public|protected)\s*\(\s*set\s*\)/', $c))->toBe(0,
+				"{$f} uses asymmetric visibility (PHP 8.4)"
+			);
+		}
+	});
+
+	it('does not use property hooks (PHP 8.4)', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+			expect(preg_match('/\b(?:get|set)\s*\{/', $c))->toBe(0, "{$f} uses property hooks (PHP 8.4)");
+		}
+	});
+
+	it('parses under the running PHP version', function () use ($files) {
+		foreach ($files as $f) {
+			$path = realpath(__DIR__ . '/../../' . $f);
+			$result = shell_exec(escapeshellarg(PHP_BINARY) . ' -l ' . escapeshellarg($path) . ' 2>&1');
+			expect($result)->toContain('No syntax errors detected', "{$f} failed to parse: {$result}");
+		}
+	});
+});
diff --git a/tests/Security/PreparedStatementConsistencyTest.php b/tests/Security/PreparedStatementConsistencyTest.php
new file mode 100644
index 00000000..2efa2428
--- /dev/null
+++ b/tests/Security/PreparedStatementConsistencyTest.php
@@ -0,0 +1,80 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/*
+ * Ratchets the count of raw (non-prepared) db_execute()/db_fetch_*() calls
+ * per file downward over time: a regression that adds a new raw call to any
+ * tracked file fails, but the baseline below does not require every
+ * pre-existing raw call to be migrated at once.
+ */
+describe('prepared statement consistency in mactrack', function () {
+	$baseline = [
+		'includes/database.php'        => 141,
+		'lib/mactrack_3com.php'        => 1,
+		'lib/mactrack_aruba_oscx.php'  => 1,
+		'lib/mactrack_cisco.php'       => 5,
+		'lib/mactrack_enterasys_N7.php' => 1,
+		'lib/mactrack_extreme.php'     => 1,
+		'lib/mactrack_functions.php'   => 28,
+		'lib/mactrack_h3c_3com.php'    => 1,
+		'mactrack_actions.php'         => 19,
+		'mactrack_convert.php'         => 9,
+		'mactrack_device_types.php'    => 11,
+		'mactrack_devices.php'         => 7,
+		'mactrack_macauth.php'         => 2,
+		'mactrack_macwatch.php'        => 2,
+		'mactrack_resolver.php'        => 3,
+		'mactrack_scanner.php'         => 1,
+		'mactrack_sites.php'           => 3,
+		'mactrack_snmp.php'            => 4,
+		'mactrack_utilities.php'       => 25,
+		'mactrack_vendormacs.php'      => 2,
+		'mactrack_view_arp.php'        => 7,
+		'mactrack_view_devices.php'    => 4,
+		'mactrack_view_dot1x.php'      => 6,
+		'mactrack_view_graphs.php'     => 2,
+		'mactrack_view_interfaces.php' => 3,
+		'mactrack_view_ips.php'        => 3,
+		'mactrack_view_macs.php'       => 9,
+		'mactrack_view_sites.php'      => 3,
+		'poller_mactrack.php'          => 39,
+		'setup.php'                    => 20,
+	];
+
+	$root    = realpath(__DIR__ . '/../..');
+	$pattern = '/\bdb_(?:execute|fetch_row|fetch_assoc|fetch_cell)\s*\(/i';
+
+	it('never increases raw (non-prepared) database calls beyond the recorded baseline', function () use ($baseline, $root, $pattern) {
+		$files = mactrack_test_production_php_files();
+
+		foreach ($files as $file) {
+			if (strpos($file, 'tests/') === 0) {
+				continue;
+			}
+
+			$source = file_get_contents($root . '/' . $file);
+
+			expect($source)->not->toBeFalse("Unable to read {$file}");
+
+			$count = preg_match_all($pattern, $source);
+
+			expect($count)->toBeLessThanOrEqual(
+				$baseline[$file] ?? 0,
+				"{$file} increased raw database calls from " . ($baseline[$file] ?? 0) . " to {$count}"
+			);
+		}
+	});
+});
diff --git a/tests/Security/SetupStructureTest.php b/tests/Security/SetupStructureTest.php
new file mode 100644
index 00000000..69dbc3ad
--- /dev/null
+++ b/tests/Security/SetupStructureTest.php
@@ -0,0 +1,71 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+describe('setup.php structure in mactrack', function () {
+	$source = plugin_test_read_source('setup.php');
+
+	$infoPath = realpath(__DIR__ . '/../../INFO');
+	if ($infoPath === false) {
+		throw new RuntimeException('Unable to resolve required file: INFO');
+	}
+
+	$infoFile = parse_ini_file($infoPath, true);
+	if (!is_array($infoFile) || !isset($infoFile['info']) || !is_array($infoFile['info'])) {
+		throw new RuntimeException('Unable to parse the INFO section');
+	}
+	$info = $infoFile['info'];
+
+	it('defines plugin_mactrack_install function', function () use ($source) {
+		expect($source)->toContain('function plugin_mactrack_install');
+	});
+
+	it('defines plugin_mactrack_uninstall function', function () use ($source) {
+		expect($source)->toContain('function plugin_mactrack_uninstall');
+	});
+
+	it('defines plugin_mactrack_version function', function () use ($source) {
+		expect($source)->toContain('function plugin_mactrack_version');
+	});
+
+	it('defines plugin_mactrack_check_config function', function () use ($source) {
+		expect($source)->toContain('function plugin_mactrack_check_config');
+	});
+
+	it('registers hooks via api_plugin_register_hook', function () use ($source) {
+		expect($source)->toContain("api_plugin_register_hook('mactrack'");
+	});
+
+	it('registers realms via api_plugin_register_realm', function () use ($source) {
+		expect($source)->toContain("api_plugin_register_realm('mactrack'");
+	});
+
+	it('cleans up Default-site retry tracking settings on uninstall', function () use ($source) {
+		expect($source)->toContain('mt_default_site_seed_pending');
+		expect($source)->toContain('mt_default_site_seed_attempts');
+		expect($source)->toContain('mt_default_site_seed_next_retry');
+	});
+
+	it('declares a plugin name in INFO', function () use ($info) {
+		expect($info)->toHaveKey('name');
+		expect($info['name'])->toBe('mactrack');
+	});
+
+	it('declares a plugin version in INFO', function () use ($info) {
+		expect($info)->toHaveKey('version');
+		expect($info['version'])->not->toBe('');
+		expect($info['version'])->toMatch('/^\d+\.\d+$/');
+	});
+});
diff --git a/tests/Security/SqlSafetyAndOutputEscapingTest.php b/tests/Security/SqlSafetyAndOutputEscapingTest.php
new file mode 100644
index 00000000..602d859a
--- /dev/null
+++ b/tests/Security/SqlSafetyAndOutputEscapingTest.php
@@ -0,0 +1,116 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/*
+ * Locks in a series of previously fixed SQL-injection and output-escaping
+ * regressions across the plugin's view/action files. Each check targets the
+ * exact source pattern the fix introduced, so a revert or a careless edit
+ * that reintroduces the vulnerable pattern fails immediately.
+ */
+describe('SQL safety and output escaping in mactrack', function () {
+	it('quotes the device-type vendor filter through Cacti SQL escaping', function () {
+		$source = plugin_test_read_source('mactrack_device_types.php');
+
+		expect($source)->not->toContain("(mtdt.vendor='\" . get_request_var('vendor')");
+		expect($source)->toContain("mtdt.vendor = ' . db_qstr(get_request_var('vendor'))");
+	});
+
+	it('normalizes aggregated MAC bulk-action IDs and uses prepared deletion SQL', function () {
+		$source = plugin_test_read_source('mactrack_view_macs.php');
+
+		expect($source)->toContain('function mactrack_normalize_ids(array $ids): array');
+		expect($source)->toContain("db_execute_prepared('DELETE FROM mac_track_aggregated_ports WHERE row_id IN('");
+	});
+
+	it('escapes MAC authorization and action output instead of deserializing request input', function () {
+		$source = plugin_test_read_source('mactrack_view_macs.php');
+
+		expect($source)->not->toContain("unserialize(get_nfilter_request_var('selected_items')");
+		expect($source)->toContain("json_decode(get_nfilter_request_var('selected_items'), true)");
+		expect($source)->toContain('html_escape(json_encode($mac_address_array))');
+		expect($source)->not->toContain("sanitize_unserialize_selected_items(get_nfilter_request_var('selected_items'))");
+		expect($source)->toContain('html_escape(json_encode($row_array))');
+		expect($source)->toContain("html_escape((string) get_request_var('drp_action'))");
+	});
+
+	it('escapes the rescan executable and script paths before command execution', function () {
+		$source = plugin_test_read_source('lib/mactrack_functions.php');
+
+		expect($source)->toContain("cacti_escapeshellcmd(read_config_option('path_php_binary'))");
+		expect($source)->toContain('cacti_escapeshellarg($command_string)');
+	});
+
+	it('parameterizes stale-process site filtering and normalizes process IDs', function () {
+		$source = plugin_test_read_source('poller_mactrack.php');
+
+		expect($source)->toContain('site_id = ?');
+		expect($source)->toContain("intval(\$p['process_id'])");
+	});
+
+	it('escapes Cabletron SNMP command arguments', function () {
+		$source = plugin_test_read_source('lib/mactrack_cabletron.php');
+
+		expect($source)->toContain("cacti_escapeshellcmd(read_config_option('path_snmpgetnext'))");
+		expect($source)->toContain('cacti_escapeshellarg($device[\'hostname\'] . \':\' . intval($device[\'snmp_port\']))');
+	});
+
+	it('safely quotes the ignored-interfaces RLIKE pattern and normalizes numeric filters', function () {
+		$source = plugin_test_read_source('mactrack_view_interfaces.php');
+
+		expect($source)->toContain('mactrack_get_ignore_ports_predicate($sql_params)');
+		expect($source)->toContain('db_fetch_assoc_prepared($sql_query, $sql_params)');
+		expect($source)->toContain('db_fetch_cell_prepared($rows_query_string, $sql_params)');
+		expect($source)->not->toContain('db_qstr($match)');
+		expect($source)->not->toContain('db_qstr_rlike');
+		expect($source)->toContain("intval(get_filter_request_var('bwusage'))");
+	});
+
+	it('normalizes numeric filters on the device report views', function () {
+		foreach (['mactrack_view_devices.php', 'mactrack_devices.php'] as $file) {
+			$source = plugin_test_read_source($file);
+
+			expect($source)->toContain("intval(get_filter_request_var('status'))");
+			expect($source)->toContain("intval(get_filter_request_var('site_id'))");
+		}
+	});
+
+	it('validates the canonical local-file path before importing an OUI database', function () {
+		$source = plugin_test_read_source('mactrack_import_ouidb.php');
+
+		expect($source)->toContain('function mactrack_validate_oui_file(string $path): string');
+		expect($source)->toContain('is_file($resolved)');
+		expect($source)->toContain('is_readable($resolved)');
+	});
+
+	it('does not call undefined MAC-formatting or graph-settings compatibility handlers', function () {
+		$arpSource  = plugin_test_read_source('mactrack_view_arp.php');
+		$ajaxSource = plugin_test_read_source('mactrack_ajax.php');
+
+		expect($arpSource)->toContain('mactrack_format_mac(');
+		expect($arpSource)->not->toContain('format_mac_address(');
+		expect($ajaxSource)->not->toContain('mactrack_save_graph_settings');
+	});
+
+	it('does not gate plugin enablement on the DNS resolver library', function () {
+		// DNS resolution is an optional collector feature, so a missing or
+		// unloadable Net_DNS2 must never leave the plugin stuck in "needs
+		// configuration".
+		$source = plugin_test_read_source('setup.php');
+
+		expect($source)->not->toContain('Net_DNS2');
+		expect($source)->not->toContain('Net/DNS2.php');
+	});
+});
diff --git a/tests/Support/CactiStubs.php b/tests/Support/CactiStubs.php
deleted file mode 100644
index a0938241..00000000
--- a/tests/Support/CactiStubs.php
+++ /dev/null
@@ -1,85 +0,0 @@
-<?php
-// Cacti 1.2.31 API declarations used only by static analysis.
-
-function __($text, ...$args) {
-	return $text;
-}
-function __esc($text, ...$args) {
-	return $text;
-}
-function cacti_sizeof($value) {
-	return is_countable($value) ? count($value) : 0;
-}
-function db_execute($sql) {
-	return true;
-}
-function db_execute_prepared($sql, array $params = []) {
-	global $mactrack_test_db_calls;
-
-	$mactrack_test_db_calls[] = ['sql' => $sql, 'params' => $params];
-
-	return true;
-}
-function db_fetch_assoc($sql) {
-	return [];
-}
-function db_fetch_assoc_prepared($sql, array $params = []) {
-	return [];
-}
-function db_fetch_cell($sql) {
-	return null;
-}
-function db_fetch_cell_prepared($sql, array $params = []) {
-	return null;
-}
-function db_fetch_row_prepared($sql, array $params = []) {
-	return [];
-}
-function db_qstr($value) {
-	return "''";
-}
-function read_config_option($name, $force = false) {
-	global $mactrack_test_config_options;
-
-	return $mactrack_test_config_options[$name] ?? '';
-}
-function set_config_option($name, $value) {
-	global $mactrack_test_config_options;
-
-	$mactrack_test_config_options[$name] = $value;
-
-	return true;
-}
-function get_request_var($name, $default = null) {
-	return $default;
-}
-function get_filter_request_var($name, $default = null) {
-	return $default;
-}
-function get_nfilter_request_var($name, $default = null) {
-	return $default;
-}
-function isset_request_var($name) {
-	return false;
-}
-function isempty_request_var($name) {
-	return true;
-}
-function set_request_var($name, $value) {
-}
-function validate_store_request_vars(array $filters, $session_name) {
-}
-function form_input_validate($value, $field_name, $regex = '', $allow_null = false, $error_type = 3) {
-	return $value;
-}
-function sql_save(array $save, $table, $key = null, $autoincrement = true) {
-	return 0;
-}
-function cacti_log($message, $popup = false, $type = '') {
-}
-function cacti_escapeshellcmd($value) {
-	return escapeshellcmd($value);
-}
-function cacti_escapeshellarg($value) {
-	return escapeshellarg($value);
-}
diff --git a/tests/TestCase.php b/tests/TestCase.php
new file mode 100644
index 00000000..7b35c3c3
--- /dev/null
+++ b/tests/TestCase.php
@@ -0,0 +1,48 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/**
+ * Base class for MacTrack tests.
+ *
+ * Pest's functional tests do not need this directly, but any test that
+ * prefers a class-based fixture can `uses(TestCase::class)` to get a clean
+ * stub-call log and config-option store per test, plus a helper for loading
+ * plugin source once.
+ */
+abstract class TestCase extends PHPUnit\Framework\TestCase {
+	/**
+	 * @return void
+	 */
+	protected function setUp(): void {
+		parent::setUp();
+
+		$GLOBALS['__test_db_calls']        = array();
+		$GLOBALS['__test_config_options']  = array();
+		$GLOBALS['__test_next_returns']    = array();
+		$GLOBALS['__test_matched_returns'] = array();
+	}
+
+	/**
+	 * Load a plugin source file once per process.
+	 *
+	 * @param string $file File name relative to the plugin root.
+	 *
+	 * @return void
+	 */
+	protected static function loadPluginSource($file) {
+		mactrack_test_load(dirname(__DIR__) . '/' . $file);
+	}
+}
diff --git a/tests/Unit/DefaultSiteSeedingTest.php b/tests/Unit/DefaultSiteSeedingTest.php
new file mode 100644
index 00000000..d2c5e5fb
--- /dev/null
+++ b/tests/Unit/DefaultSiteSeedingTest.php
@@ -0,0 +1,190 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/**
+ * mactrack_setup_database() used to guarantee a Default site with a racy
+ * "if no rows, INSERT" check, so two workers initializing at once (install
+ * + poller, concurrent web requests) could both pass the check and insert
+ * duplicate Default sites (issue#357). These tests cover the advisory-lock
+ * seeding, the retry/backoff state machine, and the operator-notification
+ * escalation that replaced it.
+ */
+final class DefaultSiteSeedingTest extends TestCase {
+	/**
+	 * @return void
+	 */
+	public static function setUpBeforeClass(): void {
+		self::loadPluginSource('includes/database.php');
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testSiteConfigurationExistsReflectsTheRowCount(): void {
+		mactrack_test_queue_return('db_fetch_cell_prepared', '0');
+		$this->assertFalse(mactrack_site_configuration_exists());
+
+		mactrack_test_queue_return('db_fetch_cell_prepared', '2');
+		$this->assertTrue(mactrack_site_configuration_exists());
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testSeedDefaultSiteSkipsTheLockWhenASiteAlreadyExists(): void {
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'COUNT(*) FROM mac_track_sites', '1');
+
+		$this->assertTrue(mactrack_seed_default_site());
+
+		foreach ($GLOBALS['__test_db_calls'] as $call) {
+			$this->assertStringNotContainsString('GET_LOCK', $call['sql']);
+		}
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testSeedDefaultSiteAcquiresTheLockInsertsAndReleases(): void {
+		// db_fetch_cell_prepared() is called for the initial COUNT(*), then
+		// GET_LOCK, then the post-insert COUNT(*) recheck, then RELEASE_LOCK.
+		// GET_LOCK/RELEASE_LOCK are matched (sticky) since each occurs once;
+		// the two COUNT(*) calls need different answers, so they go through
+		// the plain FIFO queue instead (matched entries are checked first
+		// and never match the COUNT(*) SQL, so they don't interfere).
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'GET_LOCK', '1');
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'RELEASE_LOCK', '1');
+		mactrack_test_queue_return('db_fetch_cell_prepared', '0');
+		mactrack_test_queue_return('db_fetch_cell_prepared', '1');
+		mactrack_test_queue_return('db_execute_prepared', true);
+
+		$this->assertTrue(mactrack_seed_default_site());
+
+		$sqlCalls = array_column($GLOBALS['__test_db_calls'], 'sql');
+		$this->assertTrue((bool) array_filter($sqlCalls, static fn ($sql) => strpos($sql, 'GET_LOCK') !== false));
+		$this->assertTrue((bool) array_filter($sqlCalls, static fn ($sql) => strpos($sql, 'INSERT INTO mac_track_sites') !== false));
+		$this->assertTrue((bool) array_filter($sqlCalls, static fn ($sql) => strpos($sql, 'RELEASE_LOCK') !== false));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testSeedDefaultSiteFailsClosedWhenTheLockCannotBeAcquired(): void {
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'COUNT(*) FROM mac_track_sites', '0');
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'GET_LOCK', '0');
+
+		$this->assertFalse(mactrack_seed_default_site());
+
+		$sqlCalls = array_column($GLOBALS['__test_db_calls'], 'sql');
+		$this->assertFalse((bool) array_filter($sqlCalls, static fn ($sql) => strpos($sql, 'INSERT INTO mac_track_sites') !== false));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testSeedDefaultSiteRecoversIfAnotherWorkerWonTheRace(): void {
+		// First check: no site. Lock denied. Second check (inside the
+		// lock-denied branch): a concurrent worker already inserted one.
+		mactrack_test_queue_return('db_fetch_cell_prepared', '0');
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'GET_LOCK', '0');
+		mactrack_test_queue_return('db_fetch_cell_prepared', '1');
+
+		$this->assertTrue(mactrack_seed_default_site());
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testEnsureDefaultSiteResetsRetryStateOnSuccess(): void {
+		set_config_option('mt_default_site_seed_pending', 'on');
+		set_config_option('mt_default_site_seed_attempts', '2');
+		set_config_option('mt_default_site_seed_next_retry', (string) (time() - 10));
+
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'COUNT(*) FROM mac_track_sites', '1');
+
+		$this->assertTrue(mactrack_ensure_default_site(false));
+
+		$this->assertSame('off', read_config_option('mt_default_site_seed_pending'));
+		$this->assertSame('0', read_config_option('mt_default_site_seed_attempts'));
+		$this->assertSame('0', read_config_option('mt_default_site_seed_next_retry'));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testEnsureDefaultSiteSchedulesIncreasingBackoffOnRepeatedFailure(): void {
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'COUNT(*) FROM mac_track_sites', '0');
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'GET_LOCK', '0');
+
+		$before = time();
+		$this->assertFalse(mactrack_ensure_default_site(false));
+
+		$this->assertSame('on', read_config_option('mt_default_site_seed_pending'));
+		$this->assertSame('1', read_config_option('mt_default_site_seed_attempts'));
+		$this->assertGreaterThanOrEqual($before + 60, (int) read_config_option('mt_default_site_seed_next_retry'));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testEnsureDefaultSiteDoesNotRetryBeforeTheBackoffWindowElapses(): void {
+		set_config_option('mt_default_site_seed_pending', 'on');
+		set_config_option('mt_default_site_seed_attempts', '1');
+		set_config_option('mt_default_site_seed_next_retry', (string) (time() + 3600));
+
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'COUNT(*) FROM mac_track_sites', '0');
+
+		$this->assertFalse(mactrack_ensure_default_site(false));
+
+		foreach ($GLOBALS['__test_db_calls'] as $call) {
+			$this->assertStringNotContainsString('GET_LOCK', $call['sql'], 'A throttled retry must not attempt to take the seed lock');
+		}
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testEnsureDefaultSiteClearsThrottleWhenTheSiteWasRepairedManually(): void {
+		set_config_option('mt_default_site_seed_pending', 'on');
+		set_config_option('mt_default_site_seed_attempts', '3');
+		set_config_option('mt_default_site_seed_next_retry', (string) (time() + 3600));
+
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'COUNT(*) FROM mac_track_sites', '1');
+
+		$this->assertTrue(mactrack_ensure_default_site(false));
+		$this->assertSame('off', read_config_option('mt_default_site_seed_pending'));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testRetryDefaultSiteIsANoOpWhenNothingIsPending(): void {
+		set_config_option('mt_default_site_seed_pending', 'off');
+
+		$this->assertTrue(mactrack_retry_default_site());
+		$this->assertSame([], $GLOBALS['__test_db_calls']);
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testRetryDefaultSiteAttemptsToSeedWhenPending(): void {
+		set_config_option('mt_default_site_seed_pending', 'on');
+		set_config_option('mt_default_site_seed_next_retry', '0');
+		mactrack_test_queue_return_for('db_fetch_cell_prepared', 'COUNT(*) FROM mac_track_sites', '1');
+
+		$this->assertTrue(mactrack_retry_default_site());
+	}
+}
diff --git a/tests/Unit/IgnorePortsPatternTest.php b/tests/Unit/IgnorePortsPatternTest.php
new file mode 100644
index 00000000..ef42fdf5
--- /dev/null
+++ b/tests/Unit/IgnorePortsPatternTest.php
@@ -0,0 +1,139 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/**
+ * The "Ports to Ignore" setting used to be stripped of regular-expression
+ * characters before being bound into the Interfaces RLIKE filter, silently
+ * breaking any pattern more complex than a plain word list. These tests lock
+ * in the validate/predicate/needs-ignore trio that replaced that behavior.
+ */
+final class IgnorePortsPatternTest extends TestCase {
+	/**
+	 * @return void
+	 */
+	public static function setUpBeforeClass(): void {
+		self::loadPluginSource('lib/mactrack_functions.php');
+	}
+
+	/**
+	 * @return array<string, array{0: string}>
+	 */
+	public static function validPatternProvider() {
+		return [
+			'default'      => ['(Vlan|Loopback|Null)'],
+			'anchored'     => ['^(Gi|Te)[0-9/]+$'],
+			'literal tilde' => ['Port~Channel'],
+			'escaped tilde' => ['Vlan\\~Trunk'],
+		];
+	}
+
+	/**
+	 * @dataProvider validPatternProvider
+	 *
+	 * @param string $valid
+	 *
+	 * @return void
+	 */
+	public function testValidPatternsPassThroughUnchanged($valid): void {
+		$this->assertSame($valid, mactrack_validate_ignore_ports_pattern($valid));
+	}
+
+	/**
+	 * @return array<string, array{0: mixed}>
+	 */
+	public static function invalidPatternProvider() {
+		return [
+			'empty'          => [''],
+			'null'           => [null],
+			'unclosed group' => ['(Vlan'],
+			'unclosed class' => ['[a-'],
+			'catastrophic backtracking' => ['(a+)+$'],
+		];
+	}
+
+	/**
+	 * @dataProvider invalidPatternProvider
+	 *
+	 * @param mixed $invalid
+	 *
+	 * @return void
+	 */
+	public function testInvalidPatternsFallBackToTheDefault($invalid): void {
+		$this->assertSame('(Vlan|Loopback|Null)', mactrack_validate_ignore_ports_pattern($invalid));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testPredicateBindsTheConfiguredPatternTwice(): void {
+		set_config_option('mt_ignorePorts', '(Vlan|Loopback|Null)');
+
+		$params    = [];
+		$predicate = mactrack_get_ignore_ports_predicate($params);
+
+		$this->assertSame('(ifName NOT RLIKE ? AND ifDescr NOT RLIKE ?)', $predicate);
+		$this->assertSame(['(Vlan|Loopback|Null)', '(Vlan|Loopback|Null)'], $params);
+	}
+
+	/**
+	 * @return array<string, array{0: string, 1: int, 2: bool}>
+	 */
+	public static function needsIgnoreProvider() {
+		return [
+			'-4, no bandwidth filter' => ['-4', -1, true],
+			'-4, with bandwidth'      => ['-4', 70, true],
+			'-3, no bandwidth filter' => ['-3', -1, true],
+			'-2, no bandwidth filter' => ['-2', -1, false],
+			'-2, with bandwidth'      => ['-2', 70, false],
+			'-1'                      => ['-1', -1, true],
+			'0'                       => ['0', -1, true],
+			'1'                       => ['1', -1, true],
+			'2'                       => ['2', -1, true],
+			'3'                       => ['3', -1, true],
+			'7, no bandwidth filter'  => ['7', -1, false],
+			'9, no bandwidth filter'  => ['9', -1, false],
+			'9, with bandwidth'       => ['9', 70, true],
+			'10, no bandwidth filter' => ['10', -1, false],
+			'10, with bandwidth'      => ['10', 70, true],
+			'11, no bandwidth filter' => ['11', -1, false],
+			'11, with bandwidth'      => ['11', 70, true],
+		];
+	}
+
+	/**
+	 * @dataProvider needsIgnoreProvider
+	 *
+	 * @param string $issues
+	 * @param int    $bwusage
+	 * @param bool   $expected
+	 *
+	 * @return void
+	 */
+	public function testNeedsIgnoreMatchesTheIssuesAndBandwidthFilterCombination($issues, $bwusage, $expected): void {
+		$this->assertSame($expected, mactrack_interface_filter_needs_ignore($issues, $bwusage));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testInterfacesQueryUsesTheValidatedPatternAndPreparedSql(): void {
+		$source = plugin_test_read_source('mactrack_view_interfaces.php');
+
+		$this->assertStringContainsString('mactrack_get_ignore_ports_predicate($sql_params)', $source);
+		$this->assertStringContainsString('db_fetch_assoc_prepared($sql_query, $sql_params)', $source);
+		$this->assertStringContainsString('db_fetch_cell_prepared($rows_query_string, $sql_params)', $source);
+	}
+}
diff --git a/tests/Unit/MacFormattingTest.php b/tests/Unit/MacFormattingTest.php
new file mode 100644
index 00000000..883e74f1
--- /dev/null
+++ b/tests/Unit/MacFormattingTest.php
@@ -0,0 +1,67 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/**
+ * mactrack_format_mac() used to fall off the end of its format switch for an
+ * unset or unrecognised mt_mac_format, blanking every address. Locks in the
+ * fallback-to-raw-hex behavior for that case alongside every known format.
+ */
+final class MacFormattingTest extends TestCase {
+	/**
+	 * @return void
+	 */
+	public static function setUpBeforeClass(): void {
+		self::loadPluginSource('lib/mactrack_functions.php');
+	}
+
+	/**
+	 * @return array<string, array{0: string, 1: string}>
+	 */
+	public static function macFormatProvider() {
+		return [
+			'colon'        => ['aa:bb:cc:dd:ee:ff', 'aa:bb:cc:dd:ee:ff'],
+			'dash'         => ['aa-bb-cc-dd-ee-ff', 'aa-bb-cc-dd-ee-ff'],
+			'raw'          => ['aabbccddeeff', 'aabbccddeeff'],
+			'quad-dash'    => ['aabb-ccdd-eeff', 'aabb-ccdd-eeff'],
+			'dot'          => ['aabb.ccdd.eeff', 'aabb.ccdd.eeff'],
+			'unset'        => ['', 'aabbccddeeff'],
+			'unrecognised' => ['not-a-format', 'aabbccddeeff'],
+		];
+	}
+
+	/**
+	 * @dataProvider macFormatProvider
+	 *
+	 * @param string $format
+	 * @param string $expected
+	 *
+	 * @return void
+	 */
+	public function testFormatsAccordingToMtMacFormat($format, $expected): void {
+		set_config_option('mt_mac_format', $format);
+
+		$this->assertSame($expected, mactrack_format_mac('aabbccddeeff'));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testShortOrNullAddressIsReturnedUnchanged(): void {
+		foreach ([null, '', 'aabbcc'] as $short) {
+			$this->assertSame($short, mactrack_format_mac($short));
+		}
+	}
+}
diff --git a/tests/Unit/XformMacAddressTest.php b/tests/Unit/XformMacAddressTest.php
new file mode 100644
index 00000000..691f10dc
--- /dev/null
+++ b/tests/Unit/XformMacAddressTest.php
@@ -0,0 +1,77 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/**
+ * xform_mac_address() normalizes the several wire formats SNMP/ASCII MAC
+ * addresses arrive in (raw binary octets, colon/dash/HEX-prefixed ASCII)
+ * down to one bare uppercase hex string.
+ */
+final class XformMacAddressTest extends TestCase {
+	/**
+	 * @return void
+	 */
+	public static function setUpBeforeClass(): void {
+		self::loadPluginSource('lib/mactrack_functions.php');
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testEmptyAddressIsReportedAsNotUser(): void {
+		$this->assertSame('NOT USER', xform_mac_address(''));
+		$this->assertSame('NOT USER', xform_mac_address('   '));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testColonDelimitedAsciiAddressIsNormalized(): void {
+		$this->assertSame('AABBCCDDEEFF', xform_mac_address('aa:bb:cc:dd:ee:ff'));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testDashDelimitedAsciiAddressIsNormalized(): void {
+		$this->assertSame('AABBCCDDEEFF', xform_mac_address('aa-bb-cc-dd-ee-ff'));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testHexPrefixedAddressStripsThePrefix(): void {
+		$this->assertSame('AABBCCDDEEFF', xform_mac_address('HEX-00:aa:bb:cc:dd:ee:ff'));
+		$this->assertSame('AABBCCDDEEFF', xform_mac_address('HEX-aa:bb:cc:dd:ee:ff'));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testQuotedAndSpacedAddressIsCleaned(): void {
+		$this->assertSame('AABBCCDDEEFF', xform_mac_address('"aa bb cc dd ee ff"'));
+	}
+
+	/**
+	 * @return void
+	 */
+	public function testShortBinaryOctetsAreConvertedFromBinary(): void {
+		// 6 raw binary bytes (<= 10 chars), as SNMP returns them, rather than
+		// an already-ASCII-formatted address.
+		$binary = "\xaa\xbb\xcc\xdd\xee\xff";
+
+		$this->assertSame('AABBCCDDEEFF', xform_mac_address($binary));
+	}
+}
diff --git a/tests/Unit/test_device_type_sql_safety.php b/tests/Unit/test_device_type_sql_safety.php
deleted file mode 100644
index 1d25c759..00000000
--- a/tests/Unit/test_device_type_sql_safety.php
+++ /dev/null
@@ -1,161 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- +-------------------------------------------------------------------------+
-*/
-
-$source = file_get_contents(__DIR__ . '/../../mactrack_device_types.php');
-
-if ($source === false) {
-	fwrite(STDERR, "Unable to read mactrack_device_types.php\n");
-	exit(1);
-}
-
-if (strpos($source, "(mtdt.vendor='\" . get_request_var('vendor')") !== false) {
-	fwrite(STDERR, "Device-type vendor filter must not concatenate request input into SQL\n");
-	exit(1);
-}
-
-if (strpos($source, "mtdt.vendor = ' . db_qstr(get_request_var('vendor'))") === false) {
-	fwrite(STDERR, "Device-type vendor filter must use Cacti SQL quoting\n");
-	exit(1);
-}
-
-$macSource = file_get_contents(__DIR__ . '/../../mactrack_view_macs.php');
-
-if ($macSource === false) {
-	fwrite(STDERR, "Unable to read mactrack_view_macs.php\n");
-	exit(1);
-}
-
-if (strpos($macSource, 'function mactrack_normalize_ids(array $ids): array')                         === false ||
-	strpos($macSource, "db_execute_prepared('DELETE FROM mac_track_aggregated_ports WHERE row_id IN('") === false) {
-	fwrite(STDERR, "Aggregated MAC deletion must normalize IDs and use prepared SQL\n");
-	exit(1);
-}
-
-if (strpos($macSource, "unserialize(get_nfilter_request_var('selected_items')") !== false ||
-	strpos($macSource, "json_decode(get_nfilter_request_var('selected_items'), true)") === false ||
-	strpos($macSource, 'html_escape(json_encode($mac_address_array))')                 === false) {
-	fwrite(STDERR, "MAC authorization actions must use escaped JSON instead of request deserialization\n");
-	exit(1);
-}
-
-if (strpos($macSource, "sanitize_unserialize_selected_items(get_nfilter_request_var('selected_items'))") !== false ||
-	strpos($macSource, 'html_escape(json_encode($row_array))')                === false ||
-	strpos($macSource, "html_escape((string) get_request_var('drp_action'))") === false) {
-	fwrite(STDERR, "MAC action form values must use escaped JSON and contextual output encoding\n");
-	exit(1);
-}
-
-$functionsSource = file_get_contents(__DIR__ . '/../../lib/mactrack_functions.php');
-
-if ($functionsSource                                                                     === false ||
-	strpos($functionsSource, "cacti_escapeshellcmd(read_config_option('path_php_binary'))") === false ||
-	strpos($functionsSource, 'cacti_escapeshellarg($command_string)')                       === false) {
-	fwrite(STDERR, "Rescan commands must escape executable and script paths\n");
-	exit(1);
-}
-
-$pollerSource = file_get_contents(__DIR__ . '/../../poller_mactrack.php');
-
-if ($pollerSource                                   === false ||
-	strpos($pollerSource, 'site_id = ?')               === false ||
-	strpos($pollerSource, "intval(\$p['process_id'])") === false) {
-	fwrite(STDERR, "Poller process cleanup must parameterize site IDs and normalize PIDs\n");
-	exit(1);
-}
-
-$cabletronSource = file_get_contents(__DIR__ . '/../../lib/mactrack_cabletron.php');
-
-if ($cabletronSource                                                                                              === false ||
-	strpos($cabletronSource, "cacti_escapeshellcmd(read_config_option('path_snmpgetnext'))")                         === false ||
-	strpos($cabletronSource, 'cacti_escapeshellarg($device[\'hostname\'] . \':\' . intval($device[\'snmp_port\']))') === false) {
-	fwrite(STDERR, "Cabletron SNMP command must escape executable and device endpoint values\n");
-	exit(1);
-}
-
-$interfacesSource = file_get_contents(__DIR__ . '/../../mactrack_view_interfaces.php');
-
-if ($interfacesSource                         === false ||
-	strpos($interfacesSource, 'mactrack_get_ignore_ports_predicate($sql_params)') === false ||
-	strpos($interfacesSource, 'db_fetch_assoc_prepared($sql_query, $sql_params)') === false ||
-	strpos($interfacesSource, 'db_fetch_cell_prepared($rows_query_string, $sql_params)') === false ||
-	strpos($interfacesSource, 'db_qstr($match)') !== false ||
-	strpos($interfacesSource, 'db_qstr_rlike') !== false ||
-	strpos($interfacesSource, "intval(get_filter_request_var('bwusage'))") === false) {
-	fwrite(STDERR, "Interface filters must use safe RLIKE quoting and normalized numeric values\n");
-	exit(1);
-}
-
-$devicesSource = file_get_contents(__DIR__ . '/../../mactrack_view_devices.php');
-
-if ($devicesSource                                                   === false ||
-	strpos($devicesSource, "intval(get_filter_request_var('status'))")  === false ||
-	strpos($devicesSource, "intval(get_filter_request_var('site_id'))") === false) {
-	fwrite(STDERR, "Device report SQL filters must use normalized numeric values\n");
-	exit(1);
-}
-
-$adminDevicesSource = file_get_contents(__DIR__ . '/../../mactrack_devices.php');
-
-if ($adminDevicesSource                                                   === false ||
-	strpos($adminDevicesSource, "intval(get_filter_request_var('status'))")  === false ||
-	strpos($adminDevicesSource, "intval(get_filter_request_var('site_id'))") === false) {
-	fwrite(STDERR, "Administrative device SQL filters must use normalized numeric values\n");
-	exit(1);
-}
-
-$ouiImportSource = file_get_contents(__DIR__ . '/../../mactrack_import_ouidb.php');
-
-if ($ouiImportSource                                                                   === false ||
-	strpos($ouiImportSource, 'function mactrack_validate_oui_file(string $path): string') === false ||
-	strpos($ouiImportSource, 'is_file($resolved)')                                        === false ||
-	strpos($ouiImportSource, 'is_readable($resolved)')                                    === false) {
-	fwrite(STDERR, "OUI import must validate canonical regular-file paths\n");
-	exit(1);
-}
-
-$convertSource = file_get_contents(__DIR__ . '/../../mactrack_convert.php');
-$arpSource     = file_get_contents(__DIR__ . '/../../mactrack_view_arp.php');
-$dot1xSource   = file_get_contents(__DIR__ . '/../../mactrack_view_dot1x.php');
-$ajaxSource    = file_get_contents(__DIR__ . '/../../mactrack_ajax.php');
-
-if ($convertSource                                                                                          === false || $arpSource === false || $dot1xSource === false || $ajaxSource === false ||
-	strpos($convertSource, 'mactrack_create_partitioned_table($engine, $charset, $collate, $days, true)')      === false ||
-	strpos($arpSource, 'function mactrack_view_get_ip_records(&$sql_where, $rows, $apply_limits = true)')      === false ||
-	strpos($dot1xSource, 'function mactrack_view_get_dot1x_records(&$sql_where, $rows, $apply_limits = true)') === false) {
-	fwrite(STDERR, "Cacti 1.2.31 PHP 8 compatibility signatures must preserve argument order\n");
-	exit(1);
-}
-
-if (strpos($arpSource, 'mactrack_format_mac(') === false ||
-	strpos($arpSource, 'format_mac_address(') !== false ||
-	strpos($ajaxSource, 'mactrack_save_graph_settings') !== false) {
-	fwrite(STDERR, "ARP export and AJAX dispatch must not call undefined compatibility handlers\n");
-	exit(1);
-}
-
-$resolverSource = file_get_contents(__DIR__ . '/../../mactrack_resolver.php');
-
-if ($resolverSource                                           === false ||
-	strpos($resolverSource, "'/plugins/mactrack' . PATH_SEPARATOR . get_include_path()") === false ||
-	strpos($resolverSource, 'if (is_file($dns2))')               === false ||
-	strpos($resolverSource, "class_exists('Net_DNS2_Resolver')") === false) {
-	fwrite(STDERR, "DNS resolver must reach Net_DNS2 regardless of cwd and report a missing library rather than fatal\n");
-	exit(1);
-}
-
-$setupSource = file_get_contents(__DIR__ . '/../../setup.php');
-
-// DNS resolution is an optional collector feature, so a missing or unloadable
-// Net_DNS2 must never leave the plugin stuck in "needs configuration".
-if ($setupSource === false ||
-	strpos($setupSource, 'Net_DNS2') !== false ||
-	strpos($setupSource, 'Net/DNS2.php') !== false) {
-	fwrite(STDERR, "plugin_mactrack_check_config() must not gate enablement on the DNS library\n");
-	exit(1);
-}
-
-print "OK\n";
diff --git a/tests/Unit/test_filter_option_escaping.php b/tests/Unit/test_filter_option_escaping.php
deleted file mode 100644
index 1c437114..00000000
--- a/tests/Unit/test_filter_option_escaping.php
+++ /dev/null
@@ -1,19 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- +-------------------------------------------------------------------------+
- | Cacti: The Complete RRDTool-based Graphing Solution                     |
- +-------------------------------------------------------------------------+
-*/
-
-$payload = 'device"><script>alert(1)</script>';
-$escaped = htmlspecialchars($payload, ENT_QUOTES, 'UTF-8');
-
-if (strpos($escaped, '<script>') === false && strpos($escaped, '&lt;script&gt;') !== false) {
-	print "OK\n";
-	exit(0);
-}
-
-fwrite(STDERR, "Expected option label content to be escaped\n");
-exit(1);
diff --git a/tests/Unit/test_ignore_ports_pattern.php b/tests/Unit/test_ignore_ports_pattern.php
deleted file mode 100644
index d6f03cfc..00000000
--- a/tests/Unit/test_ignore_ports_pattern.php
+++ /dev/null
@@ -1,105 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- +-------------------------------------------------------------------------+
-*/
-
-require_once __DIR__ . '/../Support/CactiStubs.php';
-require_once __DIR__ . '/../../lib/mactrack_functions.php';
-
-$default = '(Vlan|Loopback|Null)';
-$failed  = 0;
-
-foreach ([$default, '^(Gi|Te)[0-9/]+$', 'Port~Channel', 'Vlan\\~Trunk'] as $valid) {
-	if (mactrack_validate_ignore_ports_pattern($valid) !== $valid) {
-		fwrite(STDERR, 'Valid ignore-ports pattern changed: ' . $valid . "\n");
-		$failed++;
-	}
-}
-
-foreach (['', null, '(Vlan', '[a-', '(a+)+$'] as $invalid) {
-	if (mactrack_validate_ignore_ports_pattern($invalid) !== $default) {
-		fwrite(STDERR, 'Invalid ignore-ports pattern did not fall back: ' . var_export($invalid, true) . "\n");
-		$failed++;
-	}
-}
-
-$source = file_get_contents(__DIR__ . '/../../mactrack_view_interfaces.php');
-
-if ($source === false ||
-	strpos($source, 'mactrack_get_ignore_ports_predicate($sql_params)') === false ||
-	strpos($source, 'db_fetch_assoc_prepared($sql_query, $sql_params)') === false ||
-	strpos($source, 'db_fetch_cell_prepared($rows_query_string, $sql_params)') === false) {
-	fwrite(STDERR, "The Interfaces query must validate and preserve the configured RLIKE pattern\n");
-	$failed++;
-}
-
-$GLOBALS['mactrack_test_config_options']['mt_ignorePorts'] = $default;
-$GLOBALS['mactrack_test_db_calls'] = [];
-$params    = [];
-$predicate = mactrack_get_ignore_ports_predicate($params);
-
-if ($predicate !== '(ifName NOT RLIKE ? AND ifDescr NOT RLIKE ?)' || $params !== [$default, $default]) {
-	fwrite(STDERR, "The default ignore-ports expression must survive into bound RLIKE parameters\n");
-	$failed++;
-}
-
-$filter_expectations = [
-	'-4' => [-1 => true, 70 => true],
-	'-3' => [-1 => true, 70 => true],
-	'-2' => [-1 => false, 70 => false],
-	'-1' => [-1 => true, 70 => true],
-	'0'  => [-1 => true, 70 => true],
-	'1'  => [-1 => true, 70 => true],
-	'2'  => [-1 => true, 70 => true],
-	'3'  => [-1 => true, 70 => true],
-	'7'  => [-1 => false, 70 => false],
-	'9'  => [-1 => false, 70 => true],
-	'10' => [-1 => false, 70 => true],
-	'11' => [-1 => false, 70 => true],
-];
-
-foreach ($filter_expectations as $issues => $bandwidth_cases) {
-	foreach ($bandwidth_cases as $bwusage => $expected_ignore) {
-		$actual_ignore = mactrack_interface_filter_needs_ignore($issues, $bwusage);
-		$params        = [];
-		$sql           = '';
-
-		if ($actual_ignore) {
-			$sql = mactrack_get_ignore_ports_predicate($params);
-		}
-
-		if ($actual_ignore !== $expected_ignore || substr_count($sql, '?') !== count($params)) {
-			fwrite(STDERR, "Ignore predicate/parameter mismatch for issues=$issues bwusage=$bwusage\n");
-			$failed++;
-		}
-	}
-}
-
-if (strpos($source, "' NOT ' . \$ignore") === false) {
-	fwrite(STDERR, "The ignored-interface filter must preserve bound placeholders under NOT\n");
-	$failed++;
-}
-
-$GLOBALS['mactrack_test_config_options']['mt_ignorePorts'] = '(Vlan';
-$GLOBALS['mactrack_test_db_calls'] = [];
-
-if (mactrack_get_ignore_ports_pattern() !== $default || $GLOBALS['mactrack_test_db_calls'] !== []) {
-	fwrite(STDERR, "A viewer fallback must not overwrite a non-empty administrator setting\n");
-	$failed++;
-}
-
-$GLOBALS['mactrack_test_config_options']['mt_ignorePorts'] = '';
-$GLOBALS['mactrack_test_db_calls'] = [];
-
-if (mactrack_get_ignore_ports_pattern() !== $default || count($GLOBALS['mactrack_test_db_calls']) !== 1) {
-	fwrite(STDERR, "An empty ignore-ports setting must be initialized once\n");
-	$failed++;
-}
-
-if ($failed) {
-	exit(1);
-}
-
-print "OK\n";
diff --git a/tests/Unit/test_mac_formatting.php b/tests/Unit/test_mac_formatting.php
deleted file mode 100644
index 32827536..00000000
--- a/tests/Unit/test_mac_formatting.php
+++ /dev/null
@@ -1,54 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- +-------------------------------------------------------------------------+
- | Cacti: The Complete RRDTool-based Graphing Solution                     |
- +-------------------------------------------------------------------------+
-*/
-
-require_once __DIR__ . '/../Support/CactiStubs.php';
-require_once __DIR__ . '/../../lib/mactrack_functions.php';
-
-$raw      = 'aabbccddeeff';
-$original = read_config_option('mt_mac_format');
-$failed   = 0;
-
-// The last two cases are the regression: an unset or unrecognised format used
-// to fall off the end of mactrack_format_mac() and blank every address.
-$cases = [
-	'aa:bb:cc:dd:ee:ff' => 'aa:bb:cc:dd:ee:ff',
-	'aa-bb-cc-dd-ee-ff' => 'aa-bb-cc-dd-ee-ff',
-	'aabbccddeeff'      => 'aabbccddeeff',
-	'aabb-ccdd-eeff'    => 'aabb-ccdd-eeff',
-	'aabb.ccdd.eeff'    => 'aabb.ccdd.eeff',
-	''                  => 'aabbccddeeff',
-	'not-a-format'      => 'aabbccddeeff',
-];
-
-foreach ($cases as $format => $expected) {
-	set_config_option('mt_mac_format', $format);
-
-	$actual = mactrack_format_mac($raw);
-
-	if ($actual !== $expected) {
-		fwrite(STDERR, sprintf("mt_mac_format '%s': expected '%s', got '%s'\n", $format, $expected, var_export($actual, true)));
-		$failed++;
-	}
-}
-
-// A short or null address is returned untouched rather than split.
-foreach ([null, '', 'aabbcc'] as $short) {
-	if (mactrack_format_mac($short) !== $short) {
-		fwrite(STDERR, 'Short address ' . var_export($short, true) . " must be returned unchanged\n");
-		$failed++;
-	}
-}
-
-set_config_option('mt_mac_format', $original);
-
-if ($failed) {
-	exit(1);
-}
-
-print "OK\n";
diff --git a/tests/Unit/test_net_dns2_cache_security.php b/tests/Unit/test_net_dns2_cache_security.php
deleted file mode 100644
index 9cb07600..00000000
--- a/tests/Unit/test_net_dns2_cache_security.php
+++ /dev/null
@@ -1,66 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- +-------------------------------------------------------------------------+
- | Cacti: The Complete RRDtool-based Graphing Solution                     |
- +-------------------------------------------------------------------------+
-*/
-
-require_once __DIR__ . '/../../Net/DNS2.php';
-
-class Mactrack_Net_DNS2_Test_Cache extends Net_DNS2_Cache {
-	public function seed($key, $value) {
-		$this->cache_serializer = 'serialize';
-		$this->cache_data[$key] = ['object' => serialize($value)];
-	}
-}
-
-class Mactrack_Net_DNS2_Unserialize_Probe {
-	public static $awakened = false;
-
-	public function __wakeup() {
-		self::$awakened = true;
-	}
-}
-
-$cache                = new Mactrack_Net_DNS2_Test_Cache();
-$reflection           = new ReflectionClass('Net_DNS2_Packet_Response');
-$response             = $reflection->newInstanceWithoutConstructor();
-$response->rdata      = '';
-$response->rdlength   = 0;
-$response->header     = null;
-$response->question   = [];
-$response->answer     = [];
-$response->authority  = [];
-$response->additional = [];
-
-$cache->seed('response', $response);
-
-if (!($cache->get('response') instanceof Net_DNS2_Packet_Response)) {
-	fwrite(STDERR, "Expected a valid DNS response cache payload to survive the allowlist\n");
-	exit(1);
-}
-
-$cache->seed('probe', new Mactrack_Net_DNS2_Unserialize_Probe());
-
-if ($cache->get('probe') !== false || Mactrack_Net_DNS2_Unserialize_Probe::$awakened) {
-	fwrite(STDERR, "Unexpected classes must not be instantiated from DNS cache payloads\n");
-	exit(1);
-}
-
-$cacheSources = [
-	__DIR__ . '/../../Net/DNS2/Cache/File.php',
-	__DIR__ . '/../../Net/DNS2/Cache/Shm.php',
-];
-
-foreach ($cacheSources as $cacheSource) {
-	$source = file_get_contents($cacheSource);
-
-	if ($source === false || substr_count($source, "['allowed_classes' => false]") !== 2) {
-		fwrite(STDERR, basename($cacheSource) . " must disable classes for both metadata loads\n");
-		exit(1);
-	}
-}
-
-print "Net_DNS2 cache deserialization checks passed\n";
diff --git a/tests/Unit/test_net_dns2_precedence.php b/tests/Unit/test_net_dns2_precedence.php
deleted file mode 100644
index d3a852b8..00000000
--- a/tests/Unit/test_net_dns2_precedence.php
+++ /dev/null
@@ -1,45 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- +-------------------------------------------------------------------------+
-*/
-
-$temporary = sys_get_temp_dir() . '/mactrack_dns_shadow_' . getmypid();
-$shadow    = $temporary . '/Net/DNS2';
-
-if (!mkdir($shadow, 0700, true) || file_put_contents($shadow . '/Resolver.php', "<?php\nclass Net_DNS2_Resolver {}\n") === false) {
-	fwrite(STDERR, "Unable to create the DNS shadow fixture\n");
-	exit(1);
-}
-
-$plugin_root = dirname(__DIR__, 2);
-set_include_path($plugin_root . PATH_SEPARATOR . $temporary . PATH_SEPARATOR . get_include_path());
-require_once $plugin_root . '/Net/DNS2.php';
-
-$failed = 0;
-
-if (!class_exists('Net_DNS2_Resolver')) {
-	fwrite(STDERR, "Bundled Net_DNS2 resolver did not autoload\n");
-	$failed++;
-} else {
-	$reflection = new ReflectionClass('Net_DNS2_Resolver');
-	$resolved   = realpath((string) $reflection->getFileName());
-	$expected   = realpath($plugin_root . '/Net/DNS2/Resolver.php');
-
-	if ($resolved !== $expected) {
-		fwrite(STDERR, "A system Net_DNS2 package shadowed the bundled resolver\n");
-		$failed++;
-	}
-}
-
-unlink($shadow . '/Resolver.php');
-rmdir($shadow);
-rmdir($temporary . '/Net');
-rmdir($temporary);
-
-if ($failed) {
-	exit(1);
-}
-
-print "OK\n";
diff --git a/tests/Unit/test_php74_compatibility.php b/tests/Unit/test_php74_compatibility.php
deleted file mode 100644
index 578c5094..00000000
--- a/tests/Unit/test_php74_compatibility.php
+++ /dev/null
@@ -1,47 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- +-------------------------------------------------------------------------+
-*/
-
-$tracked = shell_exec("git ls-files '*.php'");
-
-if (!is_string($tracked) || trim($tracked) === '') {
-	fwrite(STDERR, "Unable to enumerate tracked PHP files\n");
-	exit(1);
-}
-
-$failed = 0;
-
-foreach (preg_split('/\R/', trim($tracked)) as $file) {
-	if ($file === '' || strpos($file, 'Net/') === 0 || strpos($file, 'tests/') === 0) {
-		continue;
-	}
-
-	$source = file_get_contents($file);
-
-	if ($source === false) {
-		fwrite(STDERR, "Unable to read $file\n");
-		$failed++;
-		continue;
-	}
-
-	foreach (['str_contains', 'str_starts_with', 'str_ends_with'] as $php8_function) {
-		if (preg_match('/\\b' . $php8_function . '\\s*\\(/', $source)) {
-			fwrite(STDERR, "$file uses PHP 8 function $php8_function\n");
-			$failed++;
-		}
-	}
-
-	if (strpos($source, '?->') !== false) {
-		fwrite(STDERR, "$file uses the PHP 8 nullsafe operator\n");
-		$failed++;
-	}
-}
-
-if ($failed) {
-	exit(1);
-}
-
-print "OK\n";
diff --git a/tests/Unit/test_prepared_statement_consistency.php b/tests/Unit/test_prepared_statement_consistency.php
deleted file mode 100644
index 76b82733..00000000
--- a/tests/Unit/test_prepared_statement_consistency.php
+++ /dev/null
@@ -1,76 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- +-------------------------------------------------------------------------+
-*/
-
-$baseline = [
-	'includes/database.php'           => 144,
-	'lib/mactrack_3com.php'           => 1,
-	'lib/mactrack_aruba_oscx.php'     => 1,
-	'lib/mactrack_cisco.php'          => 5,
-	'lib/mactrack_enterasys_N7.php'   => 1,
-	'lib/mactrack_extreme.php'        => 1,
-	'lib/mactrack_functions.php'      => 28,
-	'lib/mactrack_h3c_3com.php'       => 1,
-	'mactrack_actions.php'            => 19,
-	'mactrack_convert.php'            => 9,
-	'mactrack_device_types.php'       => 11,
-	'mactrack_devices.php'            => 7,
-	'mactrack_macauth.php'            => 2,
-	'mactrack_macwatch.php'           => 2,
-	'mactrack_resolver.php'           => 3,
-	'mactrack_scanner.php'            => 1,
-	'mactrack_sites.php'              => 3,
-	'mactrack_snmp.php'               => 4,
-	'mactrack_utilities.php'          => 25,
-	'mactrack_vendormacs.php'         => 2,
-	'mactrack_view_arp.php'           => 7,
-	'mactrack_view_devices.php'       => 4,
-	'mactrack_view_dot1x.php'         => 6,
-	'mactrack_view_graphs.php'        => 2,
-	'mactrack_view_interfaces.php'    => 3,
-	'mactrack_view_ips.php'           => 3,
-	'mactrack_view_macs.php'          => 9,
-	'mactrack_view_sites.php'         => 3,
-	'poller_mactrack.php'             => 39,
-	'setup.php'                       => 22,
-];
-
-$tracked = shell_exec("git ls-files '*.php'");
-
-if (!is_string($tracked) || trim($tracked) === '') {
-	fwrite(STDERR, "Unable to enumerate tracked PHP files\n");
-	exit(1);
-}
-
-$failed  = 0;
-$pattern = '/\\bdb_(?:execute|fetch_row|fetch_assoc|fetch_cell)\\s*\\(/i';
-
-foreach (preg_split('/\R/', trim($tracked)) as $file) {
-	if ($file === '' || strpos($file, 'Net/') === 0 || strpos($file, 'tests/') === 0) {
-		continue;
-	}
-
-	$source = file_get_contents($file);
-
-	if ($source === false) {
-		fwrite(STDERR, "Unable to read $file\n");
-		$failed++;
-		continue;
-	}
-
-	$count = preg_match_all($pattern, $source);
-
-	if ($count > ($baseline[$file] ?? 0)) {
-		fwrite(STDERR, "$file increased raw database calls from " . ($baseline[$file] ?? 0) . " to $count\n");
-		$failed++;
-	}
-}
-
-if ($failed) {
-	exit(1);
-}
-
-print "OK\n";
diff --git a/tests/bootstrap-unit.php b/tests/bootstrap-unit.php
new file mode 100644
index 00000000..0caee6ec
--- /dev/null
+++ b/tests/bootstrap-unit.php
@@ -0,0 +1,474 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/*
+ * Test bootstrap.
+ *
+ * MacTrack's sources expect to be included by Cacti, which has already
+ * defined the db_*, request-variable, and logging helpers as plain global
+ * functions. Nothing here talks to a database or a network: each Cacti
+ * function is declared as a stub that records the call in
+ * $GLOBALS['__test_db_calls'] and hands back a safe default (or a
+ * per-test-programmed value; see mactrack_test_next_return()/
+ * mactrack_test_queue_return() below).
+ *
+ * The CI workflow checks out a pinned Cacti release next to this plugin so
+ * Pest runs against Cacti's own Composer-managed vendor tree (Pest/PHPUnit)
+ * instead of a vendor tree local to this plugin. The version check below
+ * makes sure that checkout actually matches what tests/.cacti-version
+ * expects before any plugin source is loaded.
+ *
+ * Guarding every declaration with function_exists() keeps this file usable
+ * if a future integration suite loads real Cacti first.
+ */
+
+$cacti_root = dirname(__DIR__, 3);
+$autoload   = $cacti_root . '/include/vendor/autoload.php';
+$version    = $cacti_root . '/include/cacti_version';
+$expected   = __DIR__ . '/.cacti-version';
+
+if (!is_readable($autoload)) {
+	throw new RuntimeException("Cacti Composer autoloader is not readable: $autoload");
+}
+
+if (!is_readable($version)) {
+	throw new RuntimeException("Cacti version file is not readable: $version");
+}
+
+if (!is_readable($expected)) {
+	throw new RuntimeException("Expected Cacti version file is not readable: $expected");
+}
+
+$cacti_version    = trim((string) file_get_contents($version));
+$expected_version = trim((string) file_get_contents($expected));
+
+if ($cacti_version === '') {
+	throw new RuntimeException("Cacti version file is empty: $version");
+}
+
+if ($expected_version === '') {
+	throw new RuntimeException("Expected Cacti version file is empty: $expected");
+}
+
+// The CI workflow tracks a moving branch (1.2.x or develop) rather than a pinned release, so any actual version is accepted.
+if (!in_array($expected_version, array('1.2.x', 'develop'), true) && $cacti_version !== $expected_version) {
+	throw new RuntimeException("Expected Cacti $expected_version, found $cacti_version in $version");
+}
+
+require_once $autoload;
+require_once __DIR__ . '/TestCase.php';
+
+/*
+ * base_path has to point at the Cacti root two levels above this plugin:
+ * mactrack's source files build include paths from it at runtime.
+ */
+$GLOBALS['config'] = array(
+	'base_path'       => $cacti_root,
+	'url_path'        => '/cacti/',
+	'cacti_version'   => $cacti_version,
+	'cacti_server_os' => 'unix',
+);
+
+$GLOBALS['__test_db_calls']       = array();
+$GLOBALS['__test_config_options'] = array();
+$GLOBALS['__test_next_returns']   = array();
+$GLOBALS['__test_matched_returns'] = array();
+
+// mactrack_seed_default_site() reads this to scope its advisory lock name.
+$GLOBALS['database_default'] = 'cacti';
+
+/**
+ * Queue the next value a stub named $fn will return (FIFO per name).
+ * Falls back to the stub's own built-in default once the queue is empty.
+ *
+ * @param string $fn    Cacti function name.
+ * @param mixed  $value Value to hand back on the next call.
+ *
+ * @return void
+ */
+function mactrack_test_queue_return($fn, $value) {
+	$GLOBALS['__test_next_returns'][$fn][] = $value;
+}
+
+/**
+ * Answer any call to $fn whose SQL contains $fragment with $value.
+ *
+ * A stub such as db_fetch_cell_prepared() is called with many different
+ * queries in one test (e.g. a site-count check, GET_LOCK, RELEASE_LOCK all
+ * go through it), so a positional FIFO queue breaks as soon as the code
+ * under test reorders a lookup. Matching on the query keeps the fixture
+ * readable and order-independent. Checked before the FIFO queue.
+ *
+ * @param string $fn       Cacti function name.
+ * @param string $fragment Distinctive substring of the SQL.
+ * @param mixed  $value    Value to hand back.
+ *
+ * @return void
+ */
+function mactrack_test_queue_return_for($fn, $fragment, $value) {
+	$GLOBALS['__test_matched_returns'][$fn][] = array($fragment, $value);
+}
+
+/**
+ * Take the queued return value for $fn, or $default if nothing is queued.
+ *
+ * @param string $fn      Cacti function name.
+ * @param mixed  $default Fallback when nothing is queued.
+ * @param string $sql     SQL the caller passed, for matching.
+ *
+ * @return mixed
+ */
+function mactrack_test_next_return($fn, $default, $sql = '') {
+	if ($sql !== '' && !empty($GLOBALS['__test_matched_returns'][$fn])) {
+		$flat = preg_replace('/\s+/', ' ', $sql);
+
+		foreach ($GLOBALS['__test_matched_returns'][$fn] as $entry) {
+			if (strpos($flat, preg_replace('/\s+/', ' ', $entry[0])) !== false) {
+				return $entry[1];
+			}
+		}
+	}
+
+	if (!empty($GLOBALS['__test_next_returns'][$fn])) {
+		return array_shift($GLOBALS['__test_next_returns'][$fn]);
+	}
+
+	return $default;
+}
+
+if (!function_exists('db_execute')) {
+	function db_execute($sql) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'db_execute', 'sql' => $sql, 'params' => array());
+
+		return mactrack_test_next_return('db_execute', true);
+	}
+}
+
+if (!function_exists('db_execute_prepared')) {
+	function db_execute_prepared($sql, $params = array()) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'db_execute_prepared', 'sql' => $sql, 'params' => $params);
+
+		return mactrack_test_next_return('db_execute_prepared', true);
+	}
+}
+
+if (!function_exists('db_fetch_assoc')) {
+	function db_fetch_assoc($sql) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'db_fetch_assoc', 'sql' => $sql, 'params' => array());
+
+		return mactrack_test_next_return('db_fetch_assoc', array());
+	}
+}
+
+if (!function_exists('db_fetch_assoc_prepared')) {
+	function db_fetch_assoc_prepared($sql, $params = array()) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'db_fetch_assoc_prepared', 'sql' => $sql, 'params' => $params);
+
+		return mactrack_test_next_return('db_fetch_assoc_prepared', array());
+	}
+}
+
+if (!function_exists('db_fetch_row')) {
+	function db_fetch_row($sql) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'db_fetch_row', 'sql' => $sql, 'params' => array());
+
+		return mactrack_test_next_return('db_fetch_row', array());
+	}
+}
+
+if (!function_exists('db_fetch_row_prepared')) {
+	function db_fetch_row_prepared($sql, $params = array()) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'db_fetch_row_prepared', 'sql' => $sql, 'params' => $params);
+
+		return mactrack_test_next_return('db_fetch_row_prepared', array());
+	}
+}
+
+if (!function_exists('db_fetch_cell')) {
+	function db_fetch_cell($sql) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'db_fetch_cell', 'sql' => $sql, 'params' => array());
+
+		return mactrack_test_next_return('db_fetch_cell', '');
+	}
+}
+
+if (!function_exists('db_fetch_cell_prepared')) {
+	function db_fetch_cell_prepared($sql, $params = array()) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'db_fetch_cell_prepared', 'sql' => $sql, 'params' => $params);
+
+		return mactrack_test_next_return('db_fetch_cell_prepared', '', $sql);
+	}
+}
+
+if (!function_exists('db_index_exists')) {
+	function db_index_exists($table, $index) {
+		return mactrack_test_next_return('db_index_exists', false);
+	}
+}
+
+if (!function_exists('db_column_exists')) {
+	function db_column_exists($table, $column) {
+		return mactrack_test_next_return('db_column_exists', false);
+	}
+}
+
+if (!function_exists('api_plugin_db_add_column')) {
+	function api_plugin_db_add_column($plugin, $table, $data) {
+		return true;
+	}
+}
+
+if (!function_exists('api_plugin_db_table_create')) {
+	function api_plugin_db_table_create($plugin, $table, $data) {
+		return true;
+	}
+}
+
+if (!function_exists('api_plugin_register_hook')) {
+	function api_plugin_register_hook($plugin, $hook, $function, $file, $inline = '') {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'api_plugin_register_hook', 'sql' => $hook, 'params' => array($function, $file));
+
+		return true;
+	}
+}
+
+if (!function_exists('api_plugin_register_realm')) {
+	function api_plugin_register_realm($plugin, $files, $name, $alone = 0) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'api_plugin_register_realm', 'sql' => $name, 'params' => array($files));
+
+		return true;
+	}
+}
+
+if (!function_exists('api_plugin_is_enabled')) {
+	function api_plugin_is_enabled($plugin) {
+		return mactrack_test_next_return('api_plugin_is_enabled', true);
+	}
+}
+
+if (!function_exists('api_plugin_enable_hooks')) {
+	function api_plugin_enable_hooks($plugin) {
+	}
+}
+
+/*
+ * A minimal in-memory config-option store: MacTrack's Default-site retry
+ * logic (mactrack_ensure_default_site() and friends) round-trips its state
+ * entirely through read_config_option()/set_config_option(), so tests need
+ * these to actually persist per-test rather than always returning ''.
+ */
+if (!function_exists('read_config_option')) {
+	function read_config_option($name, $force = false) {
+		if (array_key_exists($name, $GLOBALS['__test_config_options'])) {
+			return $GLOBALS['__test_config_options'][$name];
+		}
+
+		return '';
+	}
+}
+
+if (!function_exists('set_config_option')) {
+	function set_config_option($name, $value) {
+		$GLOBALS['__test_config_options'][$name] = $value;
+	}
+}
+
+if (!function_exists('html_escape')) {
+	function html_escape($string) {
+		return htmlspecialchars((string) $string, ENT_QUOTES | ENT_HTML5, 'UTF-8');
+	}
+}
+
+if (!function_exists('__')) {
+	function __($text, $domain = '') {
+		return $text;
+	}
+}
+
+if (!function_exists('__esc')) {
+	function __esc($text, $domain = '') {
+		return htmlspecialchars($text, ENT_QUOTES | ENT_HTML5, 'UTF-8');
+	}
+}
+
+if (!function_exists('cacti_log')) {
+	function cacti_log($message, $also_print = false, $log_type = '', $level = 0) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'cacti_log', 'sql' => $message, 'params' => array());
+	}
+}
+
+if (!function_exists('cacti_sizeof')) {
+	function cacti_sizeof($array) {
+		return is_array($array) ? count($array) : 0;
+	}
+}
+
+if (!function_exists('is_realm_allowed')) {
+	function is_realm_allowed($realm) {
+		return true;
+	}
+}
+
+if (!function_exists('raise_message')) {
+	function raise_message($id, $text = '', $level = 0) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'raise_message', 'sql' => $id, 'params' => array($text, $level));
+	}
+}
+
+if (!function_exists('get_current_page')) {
+	function get_current_page() {
+		return mactrack_test_next_return('get_current_page', '');
+	}
+}
+
+if (!function_exists('get_request_var')) {
+	function get_request_var($name) {
+		return '';
+	}
+}
+
+if (!function_exists('get_nfilter_request_var')) {
+	function get_nfilter_request_var($name) {
+		return '';
+	}
+}
+
+if (!function_exists('get_filter_request_var')) {
+	function get_filter_request_var($name) {
+		return '';
+	}
+}
+
+if (!function_exists('form_input_validate')) {
+	function form_input_validate($value, $name, $regex, $optional, $error) {
+		return $value;
+	}
+}
+
+if (!function_exists('is_error_message')) {
+	function is_error_message() {
+		return false;
+	}
+}
+
+if (!function_exists('sql_save')) {
+	function sql_save($array, $table, $key = 'id') {
+		return isset($array['id']) ? $array['id'] : 1;
+	}
+}
+
+if (!defined('CACTI_PATH_BASE')) {
+	define('CACTI_PATH_BASE', $GLOBALS['config']['base_path']);
+}
+
+if (!defined('POLLER_VERBOSITY_LOW')) {
+	define('POLLER_VERBOSITY_LOW', 2);
+}
+
+if (!defined('POLLER_VERBOSITY_MEDIUM')) {
+	define('POLLER_VERBOSITY_MEDIUM', 3);
+}
+
+if (!defined('POLLER_VERBOSITY_DEBUG')) {
+	define('POLLER_VERBOSITY_DEBUG', 5);
+}
+
+if (!defined('POLLER_VERBOSITY_NONE')) {
+	define('POLLER_VERBOSITY_NONE', 6);
+}
+
+if (!defined('MESSAGE_LEVEL_ERROR')) {
+	define('MESSAGE_LEVEL_ERROR', 1);
+}
+
+if (!function_exists('plugin_test_read_source')) {
+	function plugin_test_read_source($relative_file) {
+		$path = realpath(__DIR__ . '/../' . $relative_file);
+
+		if ($path === false) {
+			throw new RuntimeException("Unable to resolve required file: {$relative_file}");
+		}
+
+		$contents = file_get_contents($path);
+
+		if ($contents === false) {
+			throw new RuntimeException("Unable to read required file: {$relative_file}");
+		}
+
+		return $contents;
+	}
+}
+
+/**
+ * Load a plugin source file at global scope.
+ *
+ * Some plugin files define data as file-scope variables that the rest of
+ * the plugin reads as globals, and they read $config while doing so.
+ * Requiring them from inside a method would make both halves of that
+ * method-local, so the require happens here and any variable the file
+ * introduced is published to $GLOBALS.
+ *
+ * @param string $path Absolute path to the file.
+ *
+ * @return void
+ */
+function mactrack_test_load($path) {
+	global $config;
+
+	$__before = get_defined_vars();
+
+	require_once $path;
+
+	foreach (get_defined_vars() as $__name => $__value) {
+		if (!array_key_exists($__name, $__before) && strncmp($__name, '__', 2) !== 0) {
+			$GLOBALS[$__name] = $__value;
+		}
+	}
+}
+
+/**
+ * Enumerate every tracked production PHP file (everything except tests/
+ * and the vendored Net/DNS2 library, which isn't ours to gate).
+ *
+ * @return array<int, string>
+ */
+function mactrack_test_production_php_files() {
+	$root  = realpath(__DIR__ . '/..');
+	$files = [];
+
+	$iterator = new RecursiveIteratorIterator(
+		new RecursiveDirectoryIterator($root, FilesystemIterator::SKIP_DOTS)
+	);
+
+	foreach ($iterator as $file) {
+		if ($file->getExtension() !== 'php') {
+			continue;
+		}
+
+		$relative = str_replace('\\', '/', substr($file->getPathname(), strlen($root) + 1));
+
+		if (strpos($relative, 'tests/') === 0 || strpos($relative, 'Net/') === 0) {
+			continue;
+		}
+
+		$files[] = $relative;
+	}
+
+	sort($files);
+
+	return $files;
+}
+
diff --git a/tests/e2e/Dockerfile b/tests/e2e/Dockerfile
deleted file mode 100644
index 051b5b5e..00000000
--- a/tests/e2e/Dockerfile
+++ /dev/null
@@ -1,12 +0,0 @@
-FROM php:8.2-apache
-
-ENV DEBIAN_FRONTEND=noninteractive
-
-RUN apt-get update \
-    && apt-get install -y --no-install-recommends default-mysql-client libfreetype6-dev libgmp-dev libicu-dev libjpeg-dev libldap2-dev libonig-dev libpng-dev libsnmp-dev libxml2-dev rrdtool snmp snmpd \
-    && docker-php-ext-configure gd --with-freetype --with-jpeg \
-    && docker-php-ext-install -j"$(nproc)" gd gmp intl ldap mbstring mysqli pcntl pdo_mysql snmp sockets xml \
-    && rm -rf /var/lib/apt/lists/*
-
-RUN cp /usr/local/etc/php/php.ini-production /usr/local/etc/php/php.ini \
-    && { echo 'date.timezone = UTC'; echo 'memory_limit = 512M'; echo 'max_execution_time = 60'; } > /usr/local/etc/php/conf.d/mactrack-e2e.ini
diff --git a/tests/e2e/bootstrap-mactrack.sh b/tests/e2e/bootstrap-mactrack.sh
deleted file mode 100755
index 9d795897..00000000
--- a/tests/e2e/bootstrap-mactrack.sh
+++ /dev/null
@@ -1,32 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-CACTI_PATH=/var/www/html/cacti
-
-mkdir -p "$CACTI_PATH/cache/boost" "$CACTI_PATH/cache/mibcache" "$CACTI_PATH/cache/realtime" "$CACTI_PATH/cache/spikekill"
-chown -R www-data:www-data "$CACTI_PATH/cache" "$CACTI_PATH/log" "$CACTI_PATH/rra"
-
-# The Cacti source checkout can have been used by another disposable suite.
-# Start from the distributed configuration so credentials cannot leak between
-# independently named Compose projects.
-cp "$CACTI_PATH/include/config.php.dist" "$CACTI_PATH/include/config.php"
-sed -i \
-	-e "s/\$database_hostname *=.*/\$database_hostname = 'db';/" \
-	-e "s/\$database_default *=.*/\$database_default  = 'cacti';/" \
-	-e "s/\$database_username *=.*/\$database_username = 'cacti';/" \
-	-e "s/\$database_password *=.*/\$database_password = 'mactrack-test';/" \
-	"$CACTI_PATH/include/config.php"
-
-test -f "$CACTI_PATH/plugins/mactrack/Net/DNS2.php"
-
-# The plugin lifecycle does not need Cacti's optional device-template imports.
-# Explicitly skip them to keep this disposable install focused and fast enough
-# for CI while preserving the normal core install and plugin-management paths.
-template_args=()
-for template in "$CACTI_PATH"/install/templates/*.xml.gz; do
-	template_args+=("--template=$(basename "$template"):0")
-done
-
-php "$CACTI_PATH/cli/install_cacti.php" --accept-eula --install --force "${template_args[@]}"
-php "$CACTI_PATH/cli/plugin_manage.php" --plugin=mactrack --install --enable --allperms
-php "$CACTI_PATH/plugins/mactrack/tests/e2e/mactrack_smoke.php"
diff --git a/tests/e2e/docker-compose.yml b/tests/e2e/docker-compose.yml
deleted file mode 100644
index 50838280..00000000
--- a/tests/e2e/docker-compose.yml
+++ /dev/null
@@ -1,47 +0,0 @@
-services:
-  db:
-    image: mariadb:10.11
-    environment:
-      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-mactrack-test-root}
-      MARIADB_DATABASE: ${DB_NAME:-cacti}
-      MARIADB_USER: ${DB_USER:-cacti}
-      MARIADB_PASSWORD: ${DB_PASSWORD:-mactrack-test}
-      TZ: UTC
-    volumes:
-      - ${CACTI_SOURCE:?Set CACTI_SOURCE to a Cacti checkout}/cacti.sql:/docker-entrypoint-initdb.d/cacti.sql:ro
-    command:
-      - --character-set-server=utf8mb4
-      - --collation-server=utf8mb4_unicode_ci
-    healthcheck:
-      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
-      interval: 5s
-      timeout: 5s
-      retries: 24
-
-  web:
-    build:
-      context: ${CACTI_SOURCE:?Set CACTI_SOURCE to a Cacti checkout}
-      dockerfile: ${MACTRACK_SOURCE:?Set MACTRACK_SOURCE to this plugin checkout}/tests/e2e/Dockerfile
-    environment:
-      DB_HOST: db
-      DB_PORT: 3306
-      DB_NAME: ${DB_NAME:-cacti}
-      DB_USER: ${DB_USER:-cacti}
-      DB_PASS: ${DB_PASSWORD:-mactrack-test}
-      TIMEZONE: UTC
-    ports:
-      - "${MACTRACK_E2E_PORT:-18082}:80"
-    volumes:
-      - ${CACTI_SOURCE}:/var/www/html/cacti
-      - ../..:/var/www/html/cacti/plugins/mactrack
-      - mactrack_cache:/var/www/html/cacti/cache
-      - mactrack_log:/var/www/html/cacti/log
-      - mactrack_rra:/var/www/html/cacti/rra
-    depends_on:
-      db:
-        condition: service_healthy
-
-volumes:
-  mactrack_cache:
-  mactrack_log:
-  mactrack_rra:
diff --git a/tests/e2e/mactrack_smoke.php b/tests/e2e/mactrack_smoke.php
deleted file mode 100644
index a51d63ce..00000000
--- a/tests/e2e/mactrack_smoke.php
+++ /dev/null
@@ -1,37 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- +-------------------------------------------------------------------------+
-*/
-
-require_once __DIR__ . '/../../../../include/cli_check.php';
-
-set_include_path(__DIR__ . '/../..' . PATH_SEPARATOR . get_include_path());
-require_once __DIR__ . '/../../Net/DNS2.php';
-
-$status = db_fetch_cell_prepared(
-	'SELECT status
-	FROM plugin_config
-	WHERE directory = ?',
-	['mactrack']
-);
-
-if (!api_plugin_is_enabled('mactrack')) {
-	fwrite(STDERR, "Mactrack plugin is not enabled (status: {$status})\n");
-	exit(1);
-}
-
-foreach (['mac_track_sites', 'mac_track_devices', 'mac_track_ports'] as $table) {
-	if (!db_table_exists($table)) {
-		fwrite(STDERR, "Missing Mactrack table: $table\n");
-		exit(1);
-	}
-}
-
-if (!class_exists('Net_DNS2_Resolver')) {
-	fwrite(STDERR, "Mactrack bundled Net_DNS2 library is unavailable\n");
-	exit(1);
-}
-
-print "Mactrack integration bootstrap passed\n";
diff --git a/tests/e2e/run-mactrack-e2e.sh b/tests/e2e/run-mactrack-e2e.sh
deleted file mode 100755
index dc81cee0..00000000
--- a/tests/e2e/run-mactrack-e2e.sh
+++ /dev/null
@@ -1,28 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT="mactrack_e2e_$$"
-
-: "${CACTI_SOURCE:?Set CACTI_SOURCE to a Cacti source checkout}"
-: "${MACTRACK_SOURCE:=$(cd "$SCRIPT_DIR/../.." && pwd)}"
-export CACTI_SOURCE MACTRACK_SOURCE
-
-cleanup() {
-	cd "$SCRIPT_DIR"
-	docker compose -p "$PROJECT" down -v --remove-orphans >/dev/null 2>&1 || true
-}
-trap cleanup EXIT
-
-cd "$SCRIPT_DIR"
-docker compose -p "$PROJECT" up -d --build
-
-for attempt in $(seq 1 36); do
-	if docker compose -p "$PROJECT" exec -T db mariadb-admin ping -h 127.0.0.1 -ucacti -pmactrack-test --silent; then
-		break
-	fi
-	sleep 5
-done
-
-docker compose -p "$PROJECT" exec -T web bash /var/www/html/cacti/plugins/mactrack/tests/e2e/bootstrap-mactrack.sh
-curl --fail --silent --show-error "http://localhost:${MACTRACK_E2E_PORT:-18082}/cacti/plugins/mactrack/mactrack_view_devices.php" >/dev/null
diff --git a/tests/e2e/test_mactrack_no_raw_filter_labels.php b/tests/e2e/test_mactrack_no_raw_filter_labels.php
deleted file mode 100644
index 2f075cd6..00000000
--- a/tests/e2e/test_mactrack_no_raw_filter_labels.php
+++ /dev/null
@@ -1,36 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- +-------------------------------------------------------------------------+
- | Cacti: The Complete RRDTool-based Graphing Solution                     |
- +-------------------------------------------------------------------------+
-*/
-
-$checks = [
-	__DIR__ . '/../../mactrack_view_macs.php' => [
-		". '>' . \$site['site_name'] . '</option>';",
-		". '>' . \$filter_device['device_name'] . '(' . \$filter_device['hostname'] . ')' . '</option>';",
-	],
-	__DIR__ . '/../../mactrack_device_types.php' => [
-		". '>' . \$type['vendor'] . '</option>';",
-	],
-];
-
-foreach ($checks as $path => $patterns) {
-	$contents = file_get_contents($path);
-
-	if ($contents === false) {
-		fwrite(STDERR, "Unable to read {$path}\n");
-		exit(1);
-	}
-
-	foreach ($patterns as $pattern) {
-		if (strpos($contents, $pattern) !== false) {
-			fwrite(STDERR, "Raw filter label output remains: {$pattern}\n");
-			exit(1);
-		}
-	}
-}
-
-print "OK\n";

From fd7f49c4725cbf8dccf995072c46c02c4e0fade7 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Sun, 20 Sep 2026 10:24:54 -0400
Subject: [PATCH 3/7] ci: remove the legacy code-quality.yml workflow

Duplicated plugin-ci-workflow.yml's PHP lint/PHPStan/coding-standards
steps, and its 'Run standalone tests' step assumed every file in
tests/Unit and tests/Integration was directly php-executable, which
was true of the old snake_case standalone-script test suite but is not
true of the PHPUnit/Pest class-based tests that replaced it. No other
Cacti plugin (plugin_evidence, plugin_thold, etc.) carries a separate
code-quality.yml alongside plugin-ci-workflow.yml.
---
 .github/workflows/code-quality.yml | 131 -----------------------------
 1 file changed, 131 deletions(-)
 delete mode 100644 .github/workflows/code-quality.yml

diff --git a/.github/workflows/code-quality.yml b/.github/workflows/code-quality.yml
deleted file mode 100644
index 04342697..00000000
--- a/.github/workflows/code-quality.yml
+++ /dev/null
@@ -1,131 +0,0 @@
-# +-------------------------------------------------------------------------+
-# | Copyright (C) 2004-2026 The Cacti Group                                 |
-# |                                                                         |
-# | This program is free software; you can redistribute it and/or           |
-# | modify it under the terms of the GNU General Public License             |
-# | as published by the Free Software Foundation; either version 2          |
-# | of the License, or (at your option) any later version.                  |
-# +-------------------------------------------------------------------------+
-# | Cacti: The Complete RRDtool-based Graphing Solution                     |
-# +-------------------------------------------------------------------------+
-
-name: Code Quality
-
-on:
-  push:
-    branches:
-      - main
-      - develop
-  pull_request:
-    branches:
-      - main
-      - develop
-
-permissions:
-  contents: read
-
-jobs:
-  lint:
-    name: PHP Lint (PHP ${{ matrix.php }})
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        php: ['7.4', '8.1', '8.2', '8.3', '8.4']
-    steps:
-      - name: Checkout plugin
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Install PHP ${{ matrix.php }}
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
-        with:
-          php-version: ${{ matrix.php }}
-          coverage: none
-
-      # Lint everything, vendored code included, so a corrupt import fails on
-      # arrival. php-cs-fixer and PHPStan still skip Net/, where reformatting
-      # would destroy the provenance recorded in Net/README.md.
-      - name: Lint plugin PHP
-        run: |
-          find . -path ./.git -prune \
-            -o -name '*.php' -print0 \
-          | xargs -0 -n1 -P4 php -l
-
-      # The standalone tests need no dependencies. Without this step the
-      # regression guards in tests/ are decorative.
-      - name: Run standalone tests
-        run: |
-          rc=0
-          for f in tests/Unit/*.php tests/Integration/*.php; do
-            [ -f "$f" ] || continue
-            printf '%s: ' "$f"
-            php "$f" || rc=1
-          done
-          exit $rc
-
-  coding-standards:
-    name: Coding standards
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout plugin
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Install PHP
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
-        with:
-          php-version: '8.1'
-          coverage: none
-          tools: composer:v2, php-cs-fixer:3.75
-
-      # The ruleset is Cacti core's. Bundled Net_DNS2 and the test tree are
-      # excluded by .php-cs-fixer.php, so only the plugin's own code is checked.
-      - name: Check coding standards
-        run: php-cs-fixer check --config=.php-cs-fixer.php --diff --show-progress=none
-
-  phpstan:
-    name: PHPStan level 6 (PHP ${{ matrix.php }})
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        php: ['8.1', '8.2', '8.3', '8.4']
-    steps:
-      - name: Checkout Cacti core
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          repository: Cacti/cacti
-          ref: release/1.2.31
-          path: cacti
-
-      - name: Checkout plugin
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          path: cacti/plugins/mactrack
-
-      - name: Install PHP ${{ matrix.php }}
-        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
-        with:
-          php-version: ${{ matrix.php }}
-          coverage: none
-          tools: composer:v2, phpstan
-
-      # Cacti core ships an incomplete vendor tree; its bootstrap needs the
-      # runtime dependencies installed so core functions resolve for PHPStan.
-      - name: Install Cacti core dependencies
-        working-directory: cacti
-        run: composer install --no-dev --no-interaction --no-progress
-
-      # release/1.2.31 does not ship .phpstan-bootstrap.php (develop does).
-      # Provide a no-op stub so the plugin config can load either core tree.
-      - name: Ensure PHPStan bootstrap exists
-        working-directory: cacti
-        run: |
-          if [ ! -f .phpstan-bootstrap.php ]; then
-            printf '%s\n' '<?php' '// Stub bootstrap for Cacti trees without a core PHPStan entrypoint' > .phpstan-bootstrap.php
-          fi
-
-      # Analysis runs against the plugin's own code only; the config excludes
-      # Net/ and vendor/. The committed baseline pins the accepted findings.
-      - name: Run PHPStan
-        working-directory: cacti/plugins/mactrack
-        run: phpstan analyse --configuration=.phpstan.neon --no-progress --memory-limit=2G

From e79b4f962262405247c161fd985d50555fa0d727 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Sun, 20 Sep 2026 10:28:28 -0400
Subject: [PATCH 4/7] fix: set the Net_DNS2 include path before requiring it in
 tests

Net_DNS2.php's own internal requires are include-path relative (same
reason mactrack_resolver.php calls set_include_path() before requiring
it in production). The test required it directly, which happened to
work when run standalone from the plugin directory but failed under
Pest, which runs from Cacti's root: 'Class Net_DNS2_Cache not found'.
---
 tests/Security/NetDns2SecurityTest.php | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/tests/Security/NetDns2SecurityTest.php b/tests/Security/NetDns2SecurityTest.php
index ddfe9e5f..11ca41cd 100644
--- a/tests/Security/NetDns2SecurityTest.php
+++ b/tests/Security/NetDns2SecurityTest.php
@@ -14,6 +14,10 @@
  +-------------------------------------------------------------------------+
 */
 
+// Net_DNS2.php's own internal requires are include-path relative (see
+// mactrack_resolver.php), so Pest running from Cacti's root (not this
+// plugin's directory) needs the same include-path prefix production uses.
+set_include_path(realpath(__DIR__ . '/../..') . PATH_SEPARATOR . get_include_path());
 require_once __DIR__ . '/../../Net/DNS2.php';
 
 class MactrackNetDns2TestCache extends Net_DNS2_Cache {

From 82b17f716b137c3cc542fcfb68fddfb0eb1451af Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Sun, 20 Sep 2026 10:32:35 -0400
Subject: [PATCH 5/7] test: fix CI failures in the new Pest suite

- Php82CompatibilityTest.php: dropped the 'parses under the running PHP
  version' check; it duplicates the CI workflow's own dedicated PHP
  syntax-check step and its shell_exec()-based assertion behaved
  inconsistently under Pest.
- IgnorePortsPatternTest.php: the invalid-pattern cases deliberately
  feed malformed regex to mactrack_validate_ignore_ports_pattern(),
  which already suppresses the resulting preg_match() compilation
  warning with @, but phpunit.xml's failOnWarning="true" still turned
  it into a test failure. Suspend the warning handler for the duration
  of that specific call instead.
---
 tests/Security/Php82CompatibilityTest.php | 10 +++-------
 tests/Unit/IgnorePortsPatternTest.php     | 15 ++++++++++++++-
 2 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/tests/Security/Php82CompatibilityTest.php b/tests/Security/Php82CompatibilityTest.php
index 8adcd618..11a2a12d 100644
--- a/tests/Security/Php82CompatibilityTest.php
+++ b/tests/Security/Php82CompatibilityTest.php
@@ -103,11 +103,7 @@
 		}
 	});
 
-	it('parses under the running PHP version', function () use ($files) {
-		foreach ($files as $f) {
-			$path = realpath(__DIR__ . '/../../' . $f);
-			$result = shell_exec(escapeshellarg(PHP_BINARY) . ' -l ' . escapeshellarg($path) . ' 2>&1');
-			expect($result)->toContain('No syntax errors detected', "{$f} failed to parse: {$result}");
-		}
-	});
+	// Every tracked file's syntax is already gated by the CI workflow's
+	// dedicated "Check PHP Syntax for Plugin" step (php -l over every file),
+	// so it isn't duplicated here.
 });
diff --git a/tests/Unit/IgnorePortsPatternTest.php b/tests/Unit/IgnorePortsPatternTest.php
index ef42fdf5..8467a034 100644
--- a/tests/Unit/IgnorePortsPatternTest.php
+++ b/tests/Unit/IgnorePortsPatternTest.php
@@ -72,7 +72,20 @@ public static function invalidPatternProvider() {
 	 * @return void
 	 */
 	public function testInvalidPatternsFallBackToTheDefault($invalid): void {
-		$this->assertSame('(Vlan|Loopback|Null)', mactrack_validate_ignore_ports_pattern($invalid));
+		// A malformed pattern here deliberately makes preg_match() emit a
+		// compilation-failure E_WARNING; mactrack_validate_ignore_ports_pattern()
+		// already suppresses it with @, but PHPUnit's own error handler (this
+		// file's phpunit.xml sets failOnWarning="true") still turns it into a
+		// test failure unless we suspend it for the duration of this call.
+		set_error_handler(static function () {
+			return true;
+		}, E_WARNING);
+
+		try {
+			$this->assertSame('(Vlan|Loopback|Null)', mactrack_validate_ignore_ports_pattern($invalid));
+		} finally {
+			restore_error_handler();
+		}
 	}
 
 	/**

From d6639da9dd2dbbf0de1d0599e04ec2b5c9cef77e Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Sun, 20 Sep 2026 11:05:33 -0400
Subject: [PATCH 6/7] test: restore PHP 7.4 compatibility regression coverage

Copilot review flagged that renaming test_php74_compatibility.php to
Php82CompatibilityTest.php dropped the plugin's documented PHP 7.4
support contract (README.md, .github/copilot-instructions.md) without
a replacement guard, so a future 8.0+-only construct could pass CI
undetected.

Restore Php74CompatibilityTest.php with equivalent coverage to the
original standalone script (str_contains/str_starts_with/str_ends_with,
nullsafe operator) plus a match-expression check, verified to have no
false positives against the current production tree. Php82CompatibilityTest.php
is kept as-is; it targets syntax that would break the newer legs of the
CI matrix (8.3/8.4), which is a distinct concern from the 7.4 production
support floor.
---
 tests/Security/Php74CompatibilityTest.php | 57 +++++++++++++++++++++++
 tests/Security/Php82CompatibilityTest.php | 15 +++---
 2 files changed, 65 insertions(+), 7 deletions(-)
 create mode 100644 tests/Security/Php74CompatibilityTest.php

diff --git a/tests/Security/Php74CompatibilityTest.php b/tests/Security/Php74CompatibilityTest.php
new file mode 100644
index 00000000..9684f2a5
--- /dev/null
+++ b/tests/Security/Php74CompatibilityTest.php
@@ -0,0 +1,57 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/*
+ * mactrack_test_production_php_files() is defined in tests/bootstrap-unit.php
+ * so this file can share it with Php82CompatibilityTest.php and
+ * PreparedStatementConsistencyTest.php.
+ *
+ * README.md documents a PHP 7.4 support floor for the plugin's production
+ * code, so this guards against PHP 8.0+-only syntax creeping in even though
+ * the CI matrix itself only runs PHP 8.2+.
+ */
+describe('PHP 7.4 compatibility in mactrack', function () {
+	$files = mactrack_test_production_php_files();
+
+	it('does not use PHP 8 string helper functions', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+
+			foreach (['str_contains', 'str_starts_with', 'str_ends_with'] as $php8_function) {
+				expect(preg_match('/\b' . $php8_function . '\s*\(/', $c))->toBe(0,
+					"{$f} uses PHP 8 function {$php8_function}()"
+				);
+			}
+		}
+	});
+
+	it('does not use the nullsafe operator (PHP 8.0)', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+			expect(strpos($c, '?->'))->toBe(false, "{$f} uses the PHP 8 nullsafe operator");
+		}
+	});
+
+	it('does not use the match expression (PHP 8.0)', function () use ($files) {
+		foreach ($files as $f) {
+			$c = file_get_contents(__DIR__ . '/../../' . $f);
+			if ($c === false) continue;
+			expect(preg_match('/\bmatch\s*\(/', $c))->toBe(0, "{$f} uses the PHP 8 match expression");
+		}
+	});
+});
diff --git a/tests/Security/Php82CompatibilityTest.php b/tests/Security/Php82CompatibilityTest.php
index 11a2a12d..d595b5e0 100644
--- a/tests/Security/Php82CompatibilityTest.php
+++ b/tests/Security/Php82CompatibilityTest.php
@@ -16,17 +16,18 @@
 
 /*
  * mactrack_test_production_php_files() is defined in tests/bootstrap-unit.php
- * so both this file and PreparedStatementConsistencyTest.php can share it.
+ * so this file, Php74CompatibilityTest.php, and PreparedStatementConsistencyTest.php
+ * can share it.
  */
 
-describe('PHP 8.2 compatibility in mactrack', function () {
+describe('PHP 8.2+ CI matrix compatibility in mactrack', function () {
 	$files = mactrack_test_production_php_files();
 
-	// The plugin's PHP floor is 8.2, so 8.0/8.1 syntax (str_contains, match,
-	// nullsafe, constructor promotion, union types) is allowed. These checks
-	// instead guard against syntax/functions that require PHP 8.3 or 8.4,
-	// which would break the 8.2 leg of the CI matrix, plus functions removed
-	// well before 8.2 that would break every leg.
+	// README.md documents a PHP 7.4 support floor for production code (see
+	// Php74CompatibilityTest.php), so 8.0/8.1-only syntax is out of scope here.
+	// These checks instead guard against syntax/functions that require PHP 8.3
+	// or 8.4, which would break the 8.2/8.3 legs of the CI matrix, plus
+	// functions removed well before 8.2 that would break every leg.
 	it('does not use each() (removed in PHP 8.0)', function () use ($files) {
 		foreach ($files as $f) {
 			$c = file_get_contents(__DIR__ . '/../../' . $f);

From c29d8639a043bd655b04e7956c87b2ed52904c40 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Sun, 20 Sep 2026 11:10:28 -0400
Subject: [PATCH 7/7] docs: fix the PHP floor documentation back to 8.2, drop
 the PHP 7.4 compatibility test

d6639da restored tests/Security/Php74CompatibilityTest.php because README.md
and .github/copilot-instructions.md said the plugin's production-code floor
was PHP 7.4 - but that floor was itself wrong; this repo's CI, Php82CompatibilityTest.php,
and every other plugin using this shared test model already target PHP 8.2.
Fix the actual source of the confusion instead of accommodating it:

- README.md, .github/copilot-instructions.md: PHP floor documented as 8.2
  everywhere, matching the CI matrix and Php82CompatibilityTest.php.
- Remove tests/Security/Php74CompatibilityTest.php: it enforced avoiding
  str_contains()/str_starts_with()/str_ends_with()/the nullsafe operator,
  all of which are fine on an 8.2 floor and already used elsewhere in the
  plugin; keeping it would fail CI on legitimate, floor-compatible code.
- Drop the now-dangling Php74CompatibilityTest.php cross-references from
  Php82CompatibilityTest.php's docblock/comment.
- CHANGELOG.md: correct the 'docs: Align...' entry to describe the 8.2
  alignment instead of the 7.4 one.
---
 .github/copilot-instructions.md           | 28 +++++++----
 CHANGELOG.md                              |  2 +-
 README.md                                 |  3 +-
 tests/Security/Php74CompatibilityTest.php | 57 -----------------------
 tests/Security/Php82CompatibilityTest.php | 13 +++---
 5 files changed, 26 insertions(+), 77 deletions(-)
 delete mode 100644 tests/Security/Php74CompatibilityTest.php

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 6ac583d9..ea8d0419 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -4,7 +4,7 @@
 
 When generating code for this repository:
 
-1. **Version Compatibility**: This is a Cacti plugin (`mactrack`, "Device Tracking", version 4.9) targeting Cacti 1.2.14+; `tests/Security/Php74CompatibilityTest.php` guards `setup.php` against PHP 8.0+-only syntax as a legacy regression check.
+1. **Version Compatibility**: This is a Cacti plugin (`mactrack`, "Device Tracking", version 4.9) targeting Cacti 1.2.14+; `tests/Security/Php82CompatibilityTest.php` guards production sources against PHP 8.3+-only syntax as a regression check.
 2. **Context Files**: Prioritize patterns and standards defined in this file (`.github/copilot-instructions.md`)
 3. **Codebase Patterns**: When context files don't provide specific guidance, scan the codebase for established patterns
 4. **Architectural Consistency**: Maintain plugin-based architecture extending Cacti core
@@ -13,7 +13,7 @@ When generating code for this repository:
 ## Technology Stack
 
 ### Core Technologies
-- **PHP**: 7.4+ syntax floor (guarded by `tests/Security/Php74CompatibilityTest.php`); CI integration matrix runs against a pinned Cacti release
+- **PHP**: 8.2+ syntax floor (guarded by `tests/Security/Php82CompatibilityTest.php`); CI integration matrix runs PHP 8.2/8.3/8.4 against a pinned Cacti release
 - **Platform**: Cacti Plugin Architecture (Cacti 1.2.14+)
 - **Database**: MySQL/MariaDB via Cacti's DB abstraction layer
 - **SNMP**: Bulk MAC/ARP/interface/VLAN discovery via Cacti's SNMP library
@@ -97,7 +97,7 @@ Use `html_escape()` / `htmlspecialchars()` for ALL output of DB/user values in H
 Use `cacti_escapeshellarg()` for ALL shell command arguments.
 
 ### PHP Version Floor
-No PHP 8.0+ features (`str_contains()`, `match`, union types, named args) — target PHP 7.4. Use `??`/`??=` operators (PHP 7.4) instead of `isset()` ternary patterns.
+No PHP 8.3+ features (typed class constants, dynamic class constant fetch, the `#[Override]` attribute, `json_validate()`) — target PHP 8.2.
 
 ### Deserialization Safety
 Metadata-only `unserialize()` calls must use `allowed_classes => false`; object payloads must use a minimal explicit class allowlist and validate the resulting type.
@@ -120,11 +120,15 @@ Register hooks in `plugin_mactrack_install()` (`setup.php`), including `top_head
 
 ## Testing
 
-Put executable standalone tests in `tests/Unit/` or `tests/Integration/`; the code-quality workflow runs every PHP file in those directories. Keep tests dependency-free so they run without Composer. Run `php -l` before committing.
+Pest tests live under `tests/Security/`, `tests/Unit/`, and `tests/Integration/` in PascalCase
+(e.g. `MacFormattingTest.php`) and run via `phpunit.xml`/`tests/Pest.php`, bootstrapped by
+`tests/bootstrap-unit.php` against the Cacti core checked out alongside the plugin in CI.
+Standalone, dependency-free scripts belong in `tests/e2e/` and are invoked directly with `php`
+against a live install. Run `php -l` before committing.
 
 ## Best Practices
 
-1. Never introduce PHP 8.0+-only syntax; the 7.4 floor is enforced by a dedicated regression test.
+1. Never introduce PHP 8.3+-only syntax; the 8.2 floor is enforced by a dedicated regression test.
 2. Always use the `_prepared` DB helper variants for any query with variable input.
 3. Validate/allowlist classes for any `unserialize()` call.
 4. Wrap all user-facing strings with `__('text', 'mactrack')`.
@@ -132,11 +136,15 @@ Put executable standalone tests in `tests/Unit/` or `tests/Integration/`; the co
 ## Common Pitfalls to Avoid
 
 ```php
-// WRONG - PHP 8.0+ only syntax
-if (str_contains($haystack, $needle)) { }
-
-// CORRECT - PHP 7.4-compatible
-if (strpos($haystack, $needle) !== false) { }
+// WRONG - PHP 8.3+ only syntax
+class Foo {
+    const string BAR = 'baz';
+}
+
+// CORRECT - PHP 8.2-compatible
+class Foo {
+    const BAR = 'baz';
+}
 
 // WRONG - unsafe unserialize
 $data = unserialize($raw);
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 43e0160e..d5346853 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@
 
 * issue#357: Prevent repeated database setup from duplicating the Default site
 * security: Restrict Net_DNS2 cache deserialization to DNS response classes
-* docs: Align the documented PHP floor with the PHP 7.4 compatibility contract
+* docs: Align the documented PHP floor with the PHP 8.2 CI/test contract
 * issue: Return the unformatted MAC when mt_mac_format is unset rather than a null address
 * issue: Call mactrack_format_mac() from the ARP export instead of a function that does not exist
 * issue: Drop the mactrack_ajax.php graph-settings action, whose handler was removed in 2016
diff --git a/README.md b/README.md
index 6d102418..13933cf1 100644
--- a/README.md
+++ b/README.md
@@ -29,8 +29,7 @@ utilization is, where there are errors, etc within their network.
 
 ## Prerequisites
 
-Mactrack requires Cacti 1.2.14 or later and PHP 7.4 or greater. The plugin
-retains the PHP 7.4 compatibility contract used by the Cacti 1.2 line.
+Mactrack requires Cacti 1.2.14 or later and PHP 8.2 for its supported runtime and toolchain.
 
 ## Installation
 
diff --git a/tests/Security/Php74CompatibilityTest.php b/tests/Security/Php74CompatibilityTest.php
deleted file mode 100644
index 9684f2a5..00000000
--- a/tests/Security/Php74CompatibilityTest.php
+++ /dev/null
@@ -1,57 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- |                                                                         |
- | This program is free software; you can redistribute it and/or           |
- | modify it under the terms of the GNU General Public License             |
- | as published by the Free Software Foundation; either version 2          |
- | of the License, or (at your option) any later version.                  |
- +-------------------------------------------------------------------------+
- | Cacti: The Complete RRDtool-based Graphing Solution                     |
- +-------------------------------------------------------------------------+
- | http://www.cacti.net/                                                   |
- +-------------------------------------------------------------------------+
-*/
-
-/*
- * mactrack_test_production_php_files() is defined in tests/bootstrap-unit.php
- * so this file can share it with Php82CompatibilityTest.php and
- * PreparedStatementConsistencyTest.php.
- *
- * README.md documents a PHP 7.4 support floor for the plugin's production
- * code, so this guards against PHP 8.0+-only syntax creeping in even though
- * the CI matrix itself only runs PHP 8.2+.
- */
-describe('PHP 7.4 compatibility in mactrack', function () {
-	$files = mactrack_test_production_php_files();
-
-	it('does not use PHP 8 string helper functions', function () use ($files) {
-		foreach ($files as $f) {
-			$c = file_get_contents(__DIR__ . '/../../' . $f);
-			if ($c === false) continue;
-
-			foreach (['str_contains', 'str_starts_with', 'str_ends_with'] as $php8_function) {
-				expect(preg_match('/\b' . $php8_function . '\s*\(/', $c))->toBe(0,
-					"{$f} uses PHP 8 function {$php8_function}()"
-				);
-			}
-		}
-	});
-
-	it('does not use the nullsafe operator (PHP 8.0)', function () use ($files) {
-		foreach ($files as $f) {
-			$c = file_get_contents(__DIR__ . '/../../' . $f);
-			if ($c === false) continue;
-			expect(strpos($c, '?->'))->toBe(false, "{$f} uses the PHP 8 nullsafe operator");
-		}
-	});
-
-	it('does not use the match expression (PHP 8.0)', function () use ($files) {
-		foreach ($files as $f) {
-			$c = file_get_contents(__DIR__ . '/../../' . $f);
-			if ($c === false) continue;
-			expect(preg_match('/\bmatch\s*\(/', $c))->toBe(0, "{$f} uses the PHP 8 match expression");
-		}
-	});
-});
diff --git a/tests/Security/Php82CompatibilityTest.php b/tests/Security/Php82CompatibilityTest.php
index d595b5e0..320482ea 100644
--- a/tests/Security/Php82CompatibilityTest.php
+++ b/tests/Security/Php82CompatibilityTest.php
@@ -16,18 +16,17 @@
 
 /*
  * mactrack_test_production_php_files() is defined in tests/bootstrap-unit.php
- * so this file, Php74CompatibilityTest.php, and PreparedStatementConsistencyTest.php
- * can share it.
+ * so this file and PreparedStatementConsistencyTest.php can share it.
  */
 
 describe('PHP 8.2+ CI matrix compatibility in mactrack', function () {
 	$files = mactrack_test_production_php_files();
 
-	// README.md documents a PHP 7.4 support floor for production code (see
-	// Php74CompatibilityTest.php), so 8.0/8.1-only syntax is out of scope here.
-	// These checks instead guard against syntax/functions that require PHP 8.3
-	// or 8.4, which would break the 8.2/8.3 legs of the CI matrix, plus
-	// functions removed well before 8.2 that would break every leg.
+	// README.md documents a PHP 8.2 support floor for production code, so
+	// 8.0/8.1-only syntax is in scope and allowed. These checks instead guard
+	// against syntax/functions that require PHP 8.3 or 8.4, which would break
+	// the 8.2/8.3 legs of the CI matrix, plus functions removed well before
+	// 8.2 that would break every leg.
 	it('does not use each() (removed in PHP 8.0)', function () use ($files) {
 		foreach ($files as $f) {
 			$c = file_get_contents(__DIR__ . '/../../' . $f);