[Environment] Mitigate Sandbox WAF (Incapsula/Imperva) 403 Blocking across all modules

[watersRand]

Subcategory

new-feature - Entirely new functionality

Description

Problem

The Safaricom Daraja Sandbox environment is protected by an aggressive Web Application Firewall (WAF) that frequently returns HTTP 403 Forbidden errors for automated integration tests. This currently causes flaky builds and blocks CI/CD pipelines, even when the underlying library code is correct.

Current State

We have implemented a localized mitigation in the auth module using:

• User-Agent spoofing.
• Request throttling (0.5s delay).
• pytest.xfail wrappers for 403 errors.

However, as we expand to C2B, B2C, and STK Push modules, these tests will face the same susceptibility.

Proposed Global Solution

To avoid repeating boilerplate resilience code, we should implement:

1. Global Pytest Decorator: Create an @mpesa_integration_test decorator in conftest.py that automatically handles async setup and WAF 403 xfail logic.
2. Exponential Backoff: Implement a retry mechanism within MpesaAsyncHttpClient that specifically targets 403 errors with increasing delays (e.g., 1s, 2s, 4s).
3. Session Persistence: Ensure the httpx.AsyncClient is session-scoped to reuse TCP connections, which is less likely to trigger bot-detection patterns.

Impact

Implementing these will ensure that our integration tests remain green and reliable, providing a better developer experience for anyone contributing to the library.

---

Labels: enhancement, testing, environment-issue

Motivation

No response

Alternatives

No response

Additional Context

No response