diff --git a/tests/test_helpers.php b/tests/test_helpers.php
new file mode 100644
index 0000000..3f35b50
--- /dev/null
+++ b/tests/test_helpers.php
@@ -0,0 +1,49 @@
+<?php
+define('DS', DIRECTORY_SEPARATOR);
+define('ROOT', dirname(__FILE__) . '/..');
+require_once ROOT . '/src/helpers.php';
+
+$passed = 0;
+$failed = 0;
+
+function check(bool $condition, string $label): void {
+    global $passed, $failed;
+    if ($condition) { echo "PASS: $label\n"; $passed++; }
+    else            { echo "FAIL: $label\n"; $failed++; }
+}
+
+// --- isPrivateIP ---
+check(isPrivateIP('127.0.0.1'),        'loopback 127.0.0.1');
+check(isPrivateIP('127.255.255.255'),   'loopback 127.255.255.255');
+check(isPrivateIP('10.0.0.1'),          '10.x private');
+check(isPrivateIP('10.255.255.255'),    '10.255.x private');
+check(isPrivateIP('172.16.0.1'),        '172.16.x private');
+check(isPrivateIP('172.31.255.255'),    '172.31.x private');
+check(!isPrivateIP('172.15.255.255'),   '172.15.x is public');
+check(!isPrivateIP('172.32.0.0'),       '172.32.x is public');
+check(isPrivateIP('192.168.0.1'),       '192.168.x private');
+check(isPrivateIP('169.254.169.254'),   'AWS metadata IP');
+check(!isPrivateIP('8.8.8.8'),          'Google DNS is public');
+check(!isPrivateIP('93.184.216.34'),    'example.com IP is public');
+check(isPrivateIP('not-an-ip'),         'unparseable IP blocked');
+
+// --- getUserIP ---
+unset($_SERVER['HTTP_CLIENT_IP']);
+unset($_SERVER['HTTP_X_FORWARDED_FOR']);
+$_SERVER['REMOTE_ADDR'] = '5.6.7.8';
+check(getUserIP() === '5.6.7.8', 'getUserIP falls back to REMOTE_ADDR');
+
+$_SERVER['HTTP_X_FORWARDED_FOR'] = '1.2.3.4, 10.0.0.1, 172.16.0.5';
+check(getUserIP() === '1.2.3.4', 'getUserIP takes first X-Forwarded-For IP');
+
+$_SERVER['HTTP_X_FORWARDED_FOR'] = '  9.9.9.9  ';
+check(getUserIP() === '9.9.9.9', 'getUserIP trims whitespace');
+
+$_SERVER['HTTP_CLIENT_IP'] = '6.6.6.6';
+$_SERVER['HTTP_X_FORWARDED_FOR'] = '1.1.1.1';
+check(getUserIP() === '1.1.1.1', 'HTTP_CLIENT_IP ignored, X-Forwarded-For used');
+unset($_SERVER['HTTP_CLIENT_IP']);
+unset($_SERVER['HTTP_X_FORWARDED_FOR']);
+
+echo "\n$passed passed, $failed failed\n";
+exit($failed > 0 ? 1 : 0);