Home / Blog / How-To Guides / How to Automate Network Error Recovery Testing (Step-by-Step)

How to Automate Network Error Recovery Testing (Step-by-Step)

Automating network error recovery testing involves systematically simulating various network conditions—latency, packet loss, bandwidth throttling, and complete disconnections—and verifying that an ap

May 23, 2026 · 15 min read · How-To Guides

Automating network error recovery testing involves systematically simulating various network conditions—latency, packet loss, bandwidth throttling, and complete disconnections—and verifying that an application behaves gracefully, recovers as expected, and maintains data integrity. This guide provides a step-by-step approach to implementing such automation, focusing on practical techniques, tool choices, and common challenges. Effectively automating this critical aspect of quality assurance ensures resilience against real-world network instabilities, leading to a more robust and reliable user experience.

The core objective is to move beyond manual, ad-hoc testing of network failures to a repeatable, scalable, and comprehensive automated suite. While manual testing can identify obvious failures, the sheer number of network permutations and the need for consistent, precise fault injection make automation indispensable. This article will walk you through defining your test scope, selecting appropriate tools, crafting stable tests, integrating them into your CI/CD pipeline, and interpreting results to build applications that gracefully handle the unpredictable nature of network connectivity.

Defining the Scope and Impact of Network Failures

Before diving into automation, it's crucial to understand *what* you're testing and *why*. Network failures are not monolithic; they manifest in various forms, each with unique impacts on an application's behavior. Identifying the critical user journeys and their associated network dependencies is the first step.

Identifying Critical User Journeys and Network Dependencies

Consider user actions that involve external API calls, database synchronization, or content loading. For an e-commerce application, examples include:

For each journey, map out the specific network requests involved. Understanding these dependencies helps prioritize which scenarios require the most rigorous error recovery testing.

Categorizing Network Error Scenarios

Network errors can be broadly categorized. Your automation strategy should encompass these variations:

  1. Transient Failures:
  1. Persistent Failures:
  1. Degraded Conditions:

Impact Analysis: What Constitutes "Graceful Recovery"?

For each error scenario, define what constitutes acceptable "graceful recovery." This isn't just about preventing crashes; it's about maintaining a positive user experience.

When Does Automation Pay Off for Network Error Recovery?

While manual testing can cover basic "no network" scenarios, the complexity of network conditions quickly makes manual efforts unsustainable. Automation becomes essential when:

Crafting a Network Error Recovery Test Matrix

A structured test matrix helps ensure comprehensive coverage. It maps user actions against various network failure types and expected outcomes.

User Action/FeatureNetwork ConditionExpected Application BehaviorTest Automation Strategy
User LoginNo NetworkDisplay "No network" message. Prevent login.Disable network, attempt login, assert error message.
User LoginHigh Latency (3s)Show loading spinner. Login successfully after delay.Inject latency, attempt login, assert loading state & eventual success.
User Login500 Internal Server ErrorDisplay "Server error, please try again."Mock API to return 500, attempt login, assert error message.
Product Search50% Packet LossEventually load results, potentially slow. Retries handled gracefully.Inject packet loss, perform search, assert results eventually appear.
Checkout (Payment)Intermittent DisconnectionPayment processing retries, clear status if failure.Simulate brief disconnections during payment API call, assert retry/failure message.
Offline Data SyncComplete DisconnectionQueue data for sync, indicate offline mode.Disable network, modify data, re-enable, assert sync.
Image LoadingBandwidth Throttling (2G)Images load slowly, placeholders shown.Throttle bandwidth, scroll through image-heavy feed, assert loading states.

This matrix provides a blueprint for individual test cases. Each row represents a specific scenario to be automated.

Choosing the Right Tools and Frameworks for Network Error Simulation

Effective network error recovery testing relies heavily on the ability to programmatically manipulate network conditions. Several approaches and tools exist, each with its strengths and weaknesses.

Network Simulation Tools (Infrastructure Level)

These tools operate at a lower level, often manipulating network interfaces or routing tables.

Proxy-Based Tools (Application Level)

These tools sit between your application and the network, intercepting and modifying traffic.

Mobile Emulators/Simulators

API Mocking and Stubbing Frameworks

While not strictly network *simulation*, mocking API responses is crucial for testing error recovery when the backend is unavailable or returns specific error codes (e.g., 500, 401, 404).

Choosing a Strategy

For comprehensive testing, a combination of these approaches is often best:

  1. For Web Applications: Use Playwright's/Selenium's network intercept capabilities combined with browser dev tools throttling for client-side conditions. For backend errors, use API mocking (e.g., MSW, Nock) or a Toxiproxy instance for specific service interactions.
  2. For Mobile Applications (Native): Use Android Emulator/iOS Simulator network controls for general conditions. For specific API failures, API mocking or Toxiproxy positioned between the app and its backend is ideal. Appium can often interact with emulator/simulator settings.
  3. For Desktop/Server Applications: tc (Linux), Toxiproxy, or cloud provider tools are generally more appropriate for simulating network degradation.

Recommendation: For robust, automatable network error recovery testing across different application types, Toxiproxy stands out for its API-driven control and granular "toxic" injection. It complements UI automation frameworks by allowing precise network manipulation programmatically.

Integrating Network Simulation with UI Automation Frameworks

Once you've chosen your network simulation tools, the next step is to integrate them into your UI automation framework (e.g., Playwright, Selenium, Appium). This typically involves:

  1. Setup: Starting the network simulator (e.g., Toxiproxy server, configuring tc rules).
  2. Test Step: Applying specific network conditions (e.g., adding latency, packet loss).
  3. Application Action: Performing the user interaction that should trigger the error recovery.
  4. Verification: Asserting that the application handles the error gracefully.
  5. Teardown: Reverting network conditions to normal.

Example: Playwright with Toxiproxy (Web Application)

This example demonstrates how to use Playwright (a popular web automation framework) with Toxiproxy to simulate network latency.

First, ensure Toxiproxy is running (e.g., toxiproxy-server).


# pip install playwright pytest pytest-playwright requests toxiproxy-python-client

import pytest
from playwright.sync_api import Page, expect
from toxiproxy.toxiproxy import Toxiproxy # toxiproxy-python-client

# Assume your web app makes requests to 'api.example.com'
# We'll proxy this through Toxiproxy

TOXIPROXY_HOST = "localhost"
TOXIPROXY_PORT = 8474
APP_URL = "http://localhost:8080" # Your web application URL

@pytest.fixture(scope="module")
def toxiproxy_client():
    client = Toxiproxy(TOXIPROXY_HOST, TOXIPROXY_PORT)
    # Ensure no proxies are left over from previous runs
    for proxy in client.get_all():
        client.delete(proxy.name)
    yield client
    # Clean up after all tests in the module
    for proxy in client.get_all():
        client.delete(proxy.name)

@pytest.fixture(scope="function", autouse=True)
def setup_proxy_for_test(toxiproxy_client):
    # Create an upstream proxy for your API
    # Your app will now call http://localhost:8888 instead of api.example.com
    proxy = toxiproxy_client.create(
        name="api_proxy",
        listen="localhost:8888", # The address your app will call
        upstream="api.example.com:443" # The actual backend
    )
    yield proxy
    # Remove all toxics after each test
    proxy.remove_all_toxics()

def test_login_with_high_latency(page: Page, setup_proxy_for_test):
    # Get the proxy created by the fixture
    api_proxy = setup_proxy_for_test

    # 1. Navigate to the application
    page.goto(APP_URL)

    # 2. Configure Playwright to use the Toxiproxy for API calls
    # This might require changing your app's API base URL for the test environment
    # Or, if your app uses relative paths, Playwright's proxy setup could be used
    # For this example, let's assume the app is configured to hit `localhost:8888` in test env.

    # 3. Inject latency using Toxiproxy
    # Add a 3-second latency to the API proxy
    api_proxy.add_toxic("latency", "latency", latency=3000)

    # 4. Perform user actions (e.g., login)
    page.fill("#username", "testuser")
    page.fill("#password", "password123")
    page.click("#loginButton")

    # 5. Verify application behavior
    # Expect a loading spinner or message due to latency
    expect(page.locator(".loading-spinner")).to_be_visible()

    # After 3 seconds + processing time, expect successful login
    expect(page.locator(".welcome-message")).to_to_have_text("Welcome, testuser!", timeout=5000)

    # 6. Optional: Verify network requests if needed
    # Playwright's network interception can also be used here to confirm calls went through Toxiproxy
    # e.g., page.on("request", lambda request: print(request.url))

Example: Appium with Android Emulator (Mobile Application)

This example shows how to use Appium to control Android Emulator's network conditions.


# pip install Appium-Python-Client pytest

import pytest
from appium import webdriver
from appium.options.common.base import AppiumOptions
from appium.webdriver.common.appiumby import AppiumBy

# Desired Capabilities for Android Emulator
APPIUM_SERVER_URL = "http://localhost:4723"
PACKAGE_NAME = "com.example.myapp" # Replace with your app's package

@pytest.fixture(scope="function")
def driver():
    options = AppiumOptions()
    options.platform_name = "Android"
    options.automation_name = "UiAutomator2"
    options.device_name = "emulator-5554" # Replace with your emulator name/ID
    options.app_package = PACKAGE_NAME
    options.app_activity = f"{PACKAGE_NAME}.MainActivity"
    options.no_reset = True # Keep app state between runs for quicker tests

    _driver = webdriver.Remote(APPIUM_SERVER_URL, options=options)
    yield _driver
    _driver.quit()

def set_network_speed(driver_instance, speed_profile):
    """
    Sets the network speed of the Android emulator.
    Profiles: 'gsm', 'hscsd', 'gprs', 'edge', 'umts', 'hsdpa', 'hsupa', 'full', 'evdo', 'lte', 'none'
    """
    driver_instance.execute_script("mobile: shell", {
        "command": "network",
        "args": ["speed", speed_profile]
    })

def set_network_delay(driver_instance, delay_profile):
    """
    Sets the network delay of the Android emulator.
    Profiles: 'gsm', 'hscsd', 'gprs', 'edge', 'umts', 'hsdpa', 'hsupa', 'full', 'evdo', 'lte', 'none'
    """
    driver_instance.execute_script("mobile: shell", {
        "command": "network",
        "args": ["delay", delay_profile]
    })

def test_product_browsing_under_2g_conditions(driver):
    # 1. Set network conditions to simulate 2G (GPRS)
    set_network_speed(driver, "gprs")
    set_network_delay(driver, "gprs")

    # 2. Perform user actions (e.g., browse products, scroll)
    # Assume we're on a product listing screen
    product_list_locator = AppiumBy.ID, f"{PACKAGE_NAME}:id/product_list"
    expect(driver.find_element(*product_list_locator)).to_be_visible()

    # Scroll down multiple times to load more products/images
    for _ in range(3):
        driver.swipe(start_x=500, start_y=1500, end_x=500, end_y=500, duration=1000)
        # Verify that loading indicators appear and eventually disappear
        # (This would require more sophisticated waits/assertions based on your app's UI)
        # For simplicity, we just assert visibility after some delay
        driver.implicitly_wait(2) # Give some time for slow loading

    # 3. Verify application behavior: images load slowly, no crashes, placeholders handled
    # This requires specific assertions based on your UI implementation
    # e.g., expect(driver.find_element(AppiumBy.ID, f"{PACKAGE_NAME}:id/image_placeholder")).to_be_present()
    # then expect(driver.find_element(AppiumBy.ID, f"{PACKAGE_NAME}:id/product_image")).to_be_visible() after delay.

    # 4. Reset network conditions to full speed for subsequent tests
    set_network_speed(driver, "full")
    set_network_delay(driver, "full")

Writing Stable and Maintainable Tests

Network error recovery tests can be inherently flaky due to the timing involved. Strategies are needed to ensure stability.

Robust Locator Strategy

Consistent and unique locators are paramount. Avoid brittle XPath or CSS selectors that rely on element order or volatile attributes.


<!-- Good: Web -->
<button data-testid="login-button">Login</button>

<!-- Good: Android -->
<Button
    android:id="@+id/login_button"
    android:contentDescription="Login button"
    android:text="Login" />

Handling Waits and Flakiness

Network-related operations introduce variable delays. Static waits (time.sleep()) are a primary cause of flakiness.

Data Setup and Teardown

Reliable tests require consistent initial conditions.

Leveraging Autonomous QA for Network Error Recovery (SUSATest)

While scripting individual network error scenarios with frameworks like Playwright or Appium provides fine-grained control, the sheer number of possible network conditions and application states can make comprehensive coverage daunting. This is where autonomous QA platforms like SUSATest offer a powerful alternative, especially for initial discovery and broad regression.

SUSATest's approach: Instead of requiring engineers to script every interaction and manually inject network conditions for each step, SUSATest explores an application autonomously. When provided with an APK or a web URL, it navigates, taps, scrolls, types, and interacts with UI elements across various user personas (curious, impatient, adversarial, etc.). During this exploration, SUSATest can be configured to operate under different network profiles.

How it helps with Network Error Recovery Testing:

  1. Exploration Under Duress: You can instruct SUSATest to perform its autonomous exploration while simulating a "poor network" condition (e.g., high latency, intermittent connection). As it explores different screens and flows (login, signup, checkout), it will encounter network-dependent operations.
  2. Automatic Crash/ANR Detection: If the application crashes or freezes (ANR on Android) due to mishandled network errors (e.g., a timeout not handled, leading to a null pointer exception), SUSATest will automatically detect and report it.
  3. UI/UX Anomaly Detection: It can identify dead buttons, unresponsive UI elements, or incorrect error messages that result from network failures. For instance, if an API call fails due to a network timeout and the application's UI doesn't update or present a user-friendly error, SUSATest can flag this as a potential UX issue.
  4. Accessibility Violations: Sometimes, network errors can lead to accessibility regressions if error messages are not properly announced or if focus management breaks. SUSATest's accessibility persona can uncover these issues.
  5. Tracking Flows with Network Resilience: SUSATest can track critical business flows like "Login" or "Checkout." If these flows fail to complete or complete with errors under simulated network conditions, it provides a clear PASS/FAIL verdict, indicating a lack of network resilience for that specific flow.
  6. Cross-Session Learning: SUSATest learns from previous runs. If a particular screen or API call consistently fails under certain network conditions, it will remember these "dead ends" and prioritize re-testing them or exploring alternative paths in subsequent runs, making its network error discovery smarter over time.
  7. Bootstrapping Scripted Tests: Crucially, if SUSATest uncovers a network-related bug during its autonomous exploration, it can auto-generate a corresponding regression script (e.g., Appium for Android, Playwright for Web). This script captures the exact sequence of actions that led to the bug under the simulated network condition. Engineers can then take this generated script, refine it, and integrate it into their traditional CI/CD pipeline for targeted regression testing, often enhancing it with the specific network simulation techniques discussed earlier (Toxiproxy, tc, etc.). This bridges the gap between broad autonomous discovery and precise, repeatable scripted validation.

Scenario: You upload your APK to SUSATest and configure it to run with a "High Latency (3G)" network profile. SUSATest starts exploring. It might attempt to load a product image gallery. If the application freezes for 10 seconds without a loading indicator, then crashes because an image decoding library timed out, SUSATest will:

This capability significantly reduces the manual effort required to identify *where* network error recovery is failing in your application, providing a solid foundation for more targeted, scripted automation.

Running Network Error Recovery Tests in CI/CD

Integrating these tests into your CI/CD pipeline is crucial for continuous feedback on application resilience.

Pipeline Stage Selection

Environment Setup

*

Test Your App Autonomously

Upload your APK or URL. SUSA explores like 10 real users — finds bugs, accessibility violations, and security issues. No scripts.

Try SUSA Free

Related Articles