Understanding Mkulu QA Proxy: A Complete Deployment Guide Mkulu QA Proxy is an open-source, lightweight testing proxy engineered to intercept, rewrite, and mock API traffic within automated Quality Assurance pipelines. By serving as an intermediary between your test scripts and staging backends, it allows QA teams to simulate erratic server behaviors, modify payloads on the fly, and isolate front-end automation from unstable dependencies.
This guide provides a comprehensive walkthrough for deploying, configuring, and validating Mkulu QA Proxy across containerized and local testing environments. Core Features and Architecture
Unlike heavy enterprise service meshes, Mkulu QA Proxy focuses entirely on the developer and QA workflow. It operates using three primary layers:
The Interception Engine: Captures inbound HTTP/HTTPS requests from clients like Selenium, Playwright, or Cypress.
The Rule Evaluator: Matches request patterns against custom routing tables or mocking configurations.
The Mocking/Forwarding Data Plane: Returns pre-configured mock responses or applies latency before forwarding the request to real upstream services. Deployment Prerequisites
Ensure your host machine or deployment server has the following dependencies ready:
Docker & Docker Compose: Required for standard containerized deployment.
OpenSSL: Necessary for generating custom root CA certificates to handle SSL/TLS decryption.
Network Access: Free external ports (Default: 8080 for traffic routing, 8081 for the web administration UI). Step-by-Step Deployment Guide Step 1: Generate custom SSL/TLS certificates
To intercept HTTPS traffic successfully, the proxy needs a trusted Certificate Authority (CA) certificate.
Run the following commands to generate the private key and root certificate:
openssl genrsa -out mkulu-ca.key 2048 openssl req -x509 -new -nodes -key mkulu-ca.key -sha256 -days 365 -out mkulu-ca.crt Use code with caution. Step 2: Create the Docker Compose configuration
Create a file named docker-compose.yml in your project root directory. This file spins up both the proxy daemon and its configuration dashboard.
version: ‘3.8’ services: mkulu-proxy: image: ghcr.io/mkulu/qa-proxy:latest container_name: mkulu_qa_proxy ports: - “8080:8080” - “8081:8081” environment: - PROXY_PORT=8080 - ADMIN_PORT=8081 - LOG_LEVEL=info volumes: - ./mkulu-ca.crt:/etc/mkulu/certs/ca.crt:ro - ./mkulu-ca.key:/etc/mkulu/certs/ca.key:ro - ./rules:/etc/mkulu/rules:rw restart: unless-stopped Use code with caution. Step 3: Define mock rules
Create a local directory named rules and place an initial default-rules.json file inside it to catch and respond to a sample endpoint:
[ { “name”: “Simulate User Service Timeout”, “match”: { “url_contains”: “/api/v1/users”, “method”: “GET” }, “actions”: { “inject_delay_ms”: 5000, “status_code”: 504, “response_body”: { “error”: “Gateway Timeout Simulated by Mkulu” } } } ] Use code with caution. Step 4: Boot up the proxy container
Launch the proxy service by executing the following terminal command: docker compose up -d Use code with caution.
Verify the status of the container using docker compose ps to ensure ports 8080 and 8081 are actively listening. Integrating with QA Automation Frameworks
To funnel automated browser tests through Mkulu QA Proxy, configure your framework’s browser capabilities to route network traffic to the proxy’s IP address and port (8080). Playwright Integration Example javascript
const { chromium } = require(‘playwright’); (async () => { const browser = await chromium.launch({ proxy: { server: ‘http://localhost:8080’, bypass: ‘localhost’ }, args: [‘–ignore-certificate-errors’] // Ignores custom CA validation warnings }); const page = await browser.newPage(); await page.goto(’https://example.com’); // Script will now trigger the 504 error rule defined in Step 3 await browser.close(); })(); Use code with caution. Playwright Python Integration Example
from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch( proxy={“server”: “http://localhost:8080”}, args=[“–ignore-certificate-errors”] ) page = browser.new_page() page.goto(”https://example.com”) browser.close() Use code with caution. Validating and Monitoring Deployment
Once deployed, you can interactively monitor and update rules by accessing the web dashboard at http://localhost:8081.
Live Traffic Stream: Inspect live requests, request headers, query parameters, and execution latency.
Rule Management: Dynamically toggle specific rewrites or structural mocks without restarting the underlying container engine.
Log Verification: Inspect stdout by running docker compose logs -f mkulu-proxy to debug rule-matching exceptions.
If you would like to tailor this setup further, let me know:
What test automation framework you plan to use (e.g., Selenium, Playwright, Cypress).
Whether your application utilizes gRPC, WebSockets, or strict HTTP REST APIs.
If you need a script to automatically trust the root certificate inside a CI/CD pipeline runner like GitHub Actions or GitLab CI. Containerized Uyuni Proxy Setup
Leave a Reply