Testing an AIWAF-protected application

Choose the right test boundary

Keep a successful request beside each rejection assertion. A suite where every request fails can hide a broken registration, missing route, or overly broad policy. The examples below enable only rate limiting so an unrelated header or model check cannot cause an accidental pass.

Isolate state before writing assertions

• Use a fresh application or test client lifecycle and dedicated data, log, and model locations. CSV files and Redis state do not roll back with a database transaction.
• Give parallel workers separate cache namespaces, databases, or directories. Keep one namespace shared only for tests explicitly checking cross-worker behavior.
• Use fixed route budgets and an isolated manifest path. A discovered route policy can override the global limit, so test the effective route policy.
• Keep the client identity stable while testing a bucket. Use a new identity when testing independent clients.
• Use a known JSON model fixture for anomaly decisions. Do not train on live traffic as part of a deterministic application test.
• For window expiry tests, control the clock at the component boundary or use a dedicated timed integration test. Avoid long sleeps in ordinary tests.

Django's test runner creates test databases, but caches are not automatically isolated or cleared between tests. Use a dedicated test cache before clearing it. See Django's testing overview.

Write and run Flask protection tests

Create an empty working directory, install aiwaf[flask], and save this complete file as test_flask_protection.py. It builds a new application and temporary CSV directory for every test, explicitly selects memory counters, and pins both route budgets.

python -m pip install "aiwaf[flask]"

test_flask_protection.py

"""Run with: python -m unittest discover -s examples/testing -p test_flask_protection.py -v"""

from pathlib import Path
import tempfile
import unittest

from flask import Flask
from aiwaf.flask import AIWAF, aiwaf_exempt, aiwaf_exempt_from


class ProtectionTests(unittest.TestCase):
    def setUp(self):
        # A new application and state directory for every test.
        directory = tempfile.TemporaryDirectory(prefix=".ci-protection-validation-", dir=Path.cwd())
        self.addCleanup(directory.cleanup)
        app = Flask(__name__)
        app.config.update(
            TESTING=True,
            AIWAF_USE_CSV=True,
            AIWAF_DATA_DIR=directory.name,
            AIWAF_RATE_CACHE_BACKEND="memory",
            AIWAF_PATH_MANIFEST=str(Path(directory.name) / "paths.json"),
            AIWAF_RATE_WINDOW=60,
            AIWAF_RATE_MAX=3,
            AIWAF_RATE_FLOOD=100,
            AIWAF_PATH_RULES=[
                {"PREFIX": path, "RATE_LIMIT": {"WINDOW": 60, "MAX": 3, "FLOOD": 100}}
                for path in ("/api/message", "/api/preview")
            ],
        )

        @app.get("/api/message")
        def message():
            return {"message": "Protected"}

        @app.get("/health")
        @aiwaf_exempt
        def health():
            return {"ok": True}

        @app.get("/api/preview")
        @aiwaf_exempt_from("rate_limit")
        def preview():
            return {"message": "Preview"}

        AIWAF(app, middlewares=["rate_limit"])
        self.client = app.test_client()

    def test_protected_route_throttles(self):
        for _ in range(3):
            response = self.client.get("/api/message")
            self.assertEqual(response.status_code, 200)
            self.assertEqual(response.json, {"message": "Protected"})
        response = self.client.get("/api/message")
        self.assertEqual(response.status_code, 429)
        self.assertEqual(response.json, {"error": "too_many_requests"})

    def test_health_stays_available_after_throttling(self):
        for _ in range(4):
            self.client.get("/api/message")
        response = self.client.get("/health")
        self.assertEqual(response.status_code, 200)
        self.assertEqual(response.json, {"ok": True})

    def test_selective_exemption_bypasses_rate_limit(self):
        self.assertEqual(
            [self.client.get("/api/preview").status_code for _ in range(5)],
            [200] * 5,
        )


if __name__ == "__main__":
    unittest.main()

python -m unittest discover -s . -p test_flask_protection.py -v

Expect three passing tests. The first verifies three successful responses followed by HTTP 429 and the exact too_many_requests JSON body. The others verify health availability after the protected route is throttled and that a selective rate-limit exemption permits repeated requests.

This fixture exercises AIWAF behavior independently. In your own project, also test your actual app factory and live routes so a mistake in production registration cannot be hidden by a separate fixture.

Write and run Django protection tests

In a separate empty directory, install aiwaf[django] and save both files below. The fixture uses Django's test client, ORM-backed AIWAF stores, an in-memory SQLite test database, and a dedicated local-memory cache. The URL configuration is the test module itself.

python -m pip install "aiwaf[django]"

django_test_settings.py

"""Settings for this standalone example, separate from your application's settings."""

from pathlib import Path

SECRET_KEY = "local-documentation-test-key"
INSTALLED_APPS = ["aiwaf.django"]
DATABASES = {"default": {"ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:"}}
DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
# Only for this standalone fixture: create AIWAF tables without generated migrations.
MIGRATION_MODULES = {"aiwaf": None}
ROOT_URLCONF = "test_django_protection"
ALLOWED_HOSTS = ["testserver"]
MIDDLEWARE = ["aiwaf.django.middleware.RateLimitMiddleware"]
CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
        "LOCATION": "documentation-protection-tests",
    }
}
AIWAF_USE_CSV = False
AIWAF_PATH_MANIFEST = str(Path(__file__).with_name("unused-test-manifest.json"))
AIWAF_RATE_WINDOW = 60
AIWAF_RATE_MAX = 3
AIWAF_RATE_FLOOD = 100
AIWAF_EXEMPT_PATHS = ["/health"]
AIWAF_SETTINGS = {
    "PATH_RULES": [
        {"PREFIX": "/api/message", "RATE_LIMIT": {"WINDOW": 60, "MAX": 3, "FLOOD": 100}},
        {"PREFIX": "/api/preview", "DISABLE": ["rate_limit"]},
    ]
}

test_django_protection.py

"""Run from this directory using django_test_settings; see /docs/testing."""

from django.core.cache import cache
from django.http import JsonResponse
from django.test import TestCase
from django.urls import path


def message(request):
    return JsonResponse({"message": "Protected"})


def health(request):
    return JsonResponse({"ok": True})


def preview(request):
    return JsonResponse({"message": "Preview"})


urlpatterns = [
    path("api/message", message),
    path("health", health),
    path("api/preview", preview),
]


class ProtectionTests(TestCase):
    def setUp(self):
        # django_test_settings points only at a dedicated local-memory test cache.
        cache.clear()
        self.addCleanup(cache.clear)

    def test_protected_route_throttles(self):
        for _ in range(3):
            response = self.client.get("/api/message")
            self.assertEqual(response.status_code, 200)
            self.assertEqual(response.json(), {"message": "Protected"})
        response = self.client.get("/api/message")
        self.assertEqual(response.status_code, 429)
        self.assertEqual(response.json(), {"error": "too_many_requests"})

    def test_health_stays_available_after_throttling(self):
        for _ in range(4):
            self.client.get("/api/message")
        response = self.client.get("/health")
        self.assertEqual(response.status_code, 200)
        self.assertEqual(response.json(), {"ok": True})

    def test_selective_exemption_bypasses_rate_limit(self):
        self.assertEqual(
            [self.client.get("/api/preview").status_code for _ in range(5)],
            [200] * 5,
        )

python -m django test test_django_protection --settings=django_test_settings -v 2

Expect three passing tests and creation/destruction of the test database. TestCase isolates ORM changes; setUp() and cleanup clear only the dedicated local-memory cache. The standalone fixture disables AIWAF migrations to create its tables directly. In an existing project, keep your real migrations, include AIWAF in INSTALLED_APPS, and run your application's tests with its dedicated test settings.

Adapt these assertions to the routes from the Django setup guide. Keep another suite using your real ROOT_URLCONF and complete MIDDLEWARE list: this focused fixture intentionally exercises only the rate limiter.

Apply the same assertions to other frameworks

The status sequence and test structure above belong to these Python fixtures. For other runtimes, use that runtime's configuration names, response contract, and policy precedence.

• FastAPI: use its test client against the actual ASGI application. Keep the client in a context manager when startup/shutdown initializes resources. Give each test its own policy/state configuration; see the FastAPI setup guide.
• Node.js: create a fresh app and AIWAF middleware instance per test. Use the framework's injection facility or an HTTP client against an ephemeral local port. Verify a normal response, configured throttle/block response, and exemption. See Node.js operations.
• Java: test the engine decision independently, then exercise the registered Spring filter or Servlet filter through your framework test harness. Keep shared Redis integration tests separate from memory-backed tests. See Java operations.

Expand to the full protection stack

• Headers and parsing: pair valid browser/API requests with requests violating your configured requirements. Assert the rejection reason or body as well as status.
• Exemptions: verify that the intended check is bypassed and that another enabled check still runs. The rate-only examples prove the bypass, but do not prove other checks remain active.
• Flood and reputation: distinguish a soft throttle from a hard block. Verify persistent state and later requests separately using disposable storage.
• Models: cover a known normal sample, a known anomaly, and missing/invalid model handling for your configured runtime. Keep training tests separate from inference tests.
• Route discovery: generate the manifest from the test application's live route table, verify the protected route is present, and repeat the behavior assertions with the manifest loaded.
• Observation: check the expected log record and response status, including denied requests, without relying on a production log file.

For Redis or multiple workers, send a combined request sequence across workers using the same client identity and bucket. Assert the aggregate budget, expiry behavior, and configured backend-failure behavior. A single-process in-memory test cannot establish those guarantees.

Run the examples in continuous integration

From the AIWAF website checkout, the checked-in examples run with these commands. Install the relevant framework extras first.

python -m unittest discover -s examples/testing -p test_flask_protection.py -v
cd examples/testing
python -m django test test_django_protection --settings=django_test_settings -v 2

Run application and focused protection tests on each change. Run shared-backend and deployed-topology checks in a separate integration job with disposable services. Save failure output and effective policy configuration so failures can be reproduced locally.

Diagnose a failing protection test

Use the Redis-enabled multi-runtime sandbox for pinned GitHub source builds and cross-runtime checks. Follow the first-run tutorial, run SQL, TLS, outage and dependency checks, and review OWASP coverage and limits before interpreting results.

Continue with troubleshooting, configuration reference, and state ownership across workers.

Verify the current Python and Node source

The source targets are Python 1.1.4 with Rust/Python 0.2.3 and Node 1.1.2 with WASM 0.2.2. Run the framework-specific suites with the same dependencies and configuration as the deployed application.

# From the AIWAF monorepo root, with test dependencies installed.
python -m pytest tests/core tests/flask tests/fast tests/test_cli.py tests/test_cli_init_detection.py
python manage.py test tests.django

# Reproduce the committed Node dependency tree.
npm ci --prefix js
npm audit --prefix js

# Build the CommonJS native fixture used by Jest.
wasm-pack build rust/crates/aiwaf_wasm --release --target nodejs --out-dir pkg-node-test
export AIWAF_NATIVE_TEST_MODULE="$PWD/rust/crates/aiwaf_wasm/pkg-node-test/aiwaf_wasm.js"
npm run test:coverage --prefix js
npm run test:wasm --prefix js
npm run test:native --prefix js

In PowerShell, replace export with:

$env:AIWAF_NATIVE_TEST_MODULE = (Resolve-Path 'rust/crates/aiwaf_wasm/pkg-node-test/aiwaf_wasm.js').Path

The Node release workflow builds this fixture for Jest and checks the actual installed WASM engine separately. Framework test dependencies include patched Fastify 5 and NestJS 11; Jest 30 uses a cookie-module transform for Node 22 compatibility. Audit development dependencies as well as production dependencies.

For Python CSV upgrades, verify temporary and permanent blocks, expiry metadata, keywords and counts, IP/pattern exemptions, country lists, path exemptions, and UTF-8 data. Restart after removing a migrated block to verify that the old source is not replayed. Test malformed input and interrupted migration using an isolated directory. See migration semantics.

For native Node mode, verify initialization failure, bounded parsed bodies, unknown-route checks, actual model inference counters, finish/close finalization, persistence on reconstruction, and worker isolation. Native Node files and legacy CLI stores have different schemas. See the current validation results.