Testing Strategy and Test Suite

Relevant source files

The following files were used as context for generating this wiki page:

• tests/conftest.py
• tests/test_concurrency.py
• tests/test_security.py
• tests/test_fixed_window.py
• tests/test_sliding_window.py
• tests/test_edge_cases.py
• tests/test_multi_tenant.py
• benchmarks/performance.py
• CONTRIBUTING.md

FastLimit employs a comprehensive testing strategy designed to ensure the reliability, atomicity, and performance of its rate-limiting algorithms. The test suite is built on pytest and covers unit logic, integration with Redis, concurrent race conditions, and security edge cases. This strategy ensures that the library can handle high-throughput production environments (10K+ req/s) while maintaining strict rate limit guarantees and tenant isolation.

Sources: README.md:12-19, CONTRIBUTING.md:213-219, benchmarks/performance.py:12-22

Test Architecture and Environment

The testing environment relies on a live Redis instance to validate the Lua-based backend logic. Tests are categorized into unit tests (pure Python logic), integration tests (Redis interactions), and specialized suites for concurrency and security.

Test Fixtures

The suite uses pytest fixtures defined in tests/conftest.py to manage lifecycle and isolation:

• redis_client: Provides a Redis connection and performs a flushdb() before and after each test to ensure environmental isolation.
• clean_limiter: Generates a RateLimiter instance with a unique, UUID-based key_prefix for every test case.
• mock_request: Simulates a FastAPI request object for testing decorators and middleware without requiring a running web server.
• benchmark: A custom fixture for measuring operation rates and execution time.

Sources: tests/conftest.py:41-59, tests/conftest.py:82-93, tests/conftest.py:109-122, tests/conftest.py:186-224

Data Flow for a Standard Integration Test

The following diagram illustrates how a typical test case interacts with the fixtures and the Redis backend:

The use of unique prefixes ensures that concurrent test executions do not interfere with each other's Redis keys.
Sources: tests/conftest.py:109-122, tests/test_fixed_window.py:17-31

Testing Categories

Algorithm Validation

Each rate-limiting algorithm has a dedicated test suite to verify its specific behavior and mathematical accuracy.

Algorithm	Focus Area	Key Test Cases
Fixed Window	Boundary enforcement	Basic rate limiting, window reset after expiry, cost-based increments.
Token Bucket	Smoothing and Bursts	Refill accuracy under load, millisecond precision for low rates.
Sliding Window	Weighted accuracy	Weighted calculation from previous window, accurate retry_after.

Sources: tests/test_fixed_window.py:14-60, tests/test_sliding_window.py:15-38, tests/test_concurrency.py:73-108

Concurrency and Atomicity

Concurrency tests validate that Lua scripts execute atomically in Redis, preventing "over-limit" requests during race conditions. The suite frequently uses asyncio.gather() to simulate hundreds of simultaneous requests against a single key.

• Exact Limit Enforcement: Ensures that if a limit is 50, exactly 50 requests are allowed even if 200 are sent concurrently.
• Distributed Clock Consistency: Verifies that the limiter uses Redis server time via TIME methods rather than local system time to prevent issues with clock skew across multiple application servers.

Sources: tests/test_concurrency.py:27-44, tests/test_concurrency.py:136-155

Security and Edge Cases

The security suite focuses on input sanitization and protection against common rate-limiting bypasses.

• Key Collision Prevention: Validates that identifiers like user:123 and user_123 do not collide by using URL encoding for key components.
• Proxy Header Security: Ensures that X-Forwarded-For and X-Real-IP headers are only used for rate-limiting when trust_proxy_headers is explicitly enabled.
• Sensitive Data Redaction: Verifies that Redis passwords are redacted from connection logs.

Sources: tests/test_security.py:22-38, tests/test_security.py:114-135, tests/test_security.py:148-164

Performance Benchmarking

The benchmarks/performance.py script provides a suite of high-load tests to verify that the library meets its production targets.

Performance Targets

Metric	Target
p50 Latency	< 2.0 ms
p99 Latency	< 10.0 ms
Throughput (Sequential)	> 3,000 req/s
Throughput (Concurrent)	> 10,000 req/s
Accuracy	100%

Sources: benchmarks/performance.py:25-33

Benchmarking Logic Flow

The benchmark utility performs a sequence of tests to stress different parts of the system:

Multi-Tenant Isolation

Tests in tests/test_multi_tenant.py ensure that rate limits are strictly isolated between different tenants and tiers.

• Tenant Separation: Verifies that exhausting the limit for Tenant A does not affect Tenant B.
• Tier Upgrading: Simulates a scenario where a tenant moves from a "free" tier to a "premium" tier, ensuring the new limits apply correctly without carry-over from the previous tier's exhaustion.
• Wildcard Operations: Tests resetting limits for a specific tenant across all tiers or globally.

Sources: tests/test_multi_tenant.py:18-42, tests/test_multi_tenant.py:79-110, tests/test_multi_tenant.py:255-274

Summary

The FastLimit test suite is an integral part of the development lifecycle, requiring a minimum of 80% coverage for all changes. By combining exhaustive functional testing with concurrency stress tests and performance benchmarks, the suite ensures that the rate-limiting logic remains robust against race conditions and high traffic volume while maintaining strict security standards for key generation and proxy handling.

Sources: CONTRIBUTING.md:278-283, tests/test_concurrency.py:12-16