π©Ί Automated Failure Diagnostics, Wire Recording & Instant Incident Triage
In enterprise continuous integration environments where regression suites run thousands of API tests daily across parallel workers, debugging failed tests from terse stack traces (such as java.lang.AssertionError: 1 expectation failed. Expected status code <200> but was <500>) is notoriously inefficient. Engineers waste hours manually reconstructing queries, tracing missing correlation IDs, or running raw calls in Postman to reproduce defects. Conversely, indiscriminately dumping every request and response body into standard output floods CI console logs with gigabytes of unreadable noise. Custom TestNG Listeners paired with REST Assured Filters establish an automated Failure Diagnostics Pipeline. By capturing network wire traffic into an in-memory ThreadLocal diagnostic buffer, tests run silently on green passes; upon any failure or exception, the listener automatically extracts the exact HTTP transaction, generates a reproducible reproducibility curl command, formats request/response payloads, and dumps a dedicated diagnostic report artifact to disk for instant, single-click root-cause triage.
TEST EXECUTION & FAILURE DIAGNOSTIC INTERCEPTION ARCHITECTURE:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β TEST EXECUTION RUNNER (TestNG Worker Thread-1) β
β @Test public void testStudentEnrollment() { studentClient.enroll(payload); } β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ (Dispatches HTTP Call via Base Specification)
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β REST ASSURED DIAGNOSTIC FILTER (DiagnosticBufferFilter.java) β
β βββ 1. Capture Inbound Request: HTTP Verb, URL, Query, Headers, JSON Body β
β βββ 2. Auto-Generate Equivalent cURL Syntax: curl -X POST -H 'Content-Type:...' -d '...' β
β βββ 3. Execute Wire Socket Roundtrip β
β βββ 4. Capture Inbound Response: HTTP Status, Latency (ms), Response Headers, Entity Body β
β βββ 5. Store in ThreadLocal Memory: DiagnosticSessionContext.setSession(data) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
ββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββ
βΌ (Test Result Evaluation by TestNG Engine) βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββββββββββββββββββ
β BRANCH A: TEST PASSES (onTestSuccess) β β BRANCH B: TEST FAILS (onTestFailure) β
ββββββββββββββββββββββββββββββββββββββββββββββββ€ ββββββββββββββββββββββββββββββββββββββββββββββββ€
β 1. ITestListener.onTestSuccess() invoked β β 1. ITestListener.onTestFailure() invoked β
β 2. DiagnosticSessionContext.clear() called β β 2. Extract context from ThreadLocal storage β
β 3. Zero console noise / Zero disk overhead β β 3. Generate target/failures/TEST-NAME.log β
β [CLEAN, FAST, SILENT GREEN EXECUTION] β β 4. Dump formatted cURL, Wire Dumps & Stack β
β β β 5. Print high-visibility diagnostic banner β
ββββββββββββββββββββββββββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββββββββββββββββββ
ThreadLocal container to guarantee concurrency safety.
package com.nikita.restassured.diagnostics;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
public class DiagnosticSessionContext {
public static class HttpExchangeRecord {
public String method;
public String uri;
public String requestHeaders;
public String requestBody;
public String generatedCurl;
public int responseStatusCode;
public long responseDurationMs;
public String responseHeaders;
public String responseBody;
}
// ThreadLocal container stores list of HTTP exchanges executed during the current test
private static final ThreadLocal<List<HttpExchangeRecord>> sessionExchanges =
ThreadLocal.withInitial(ArrayList::new);
public static void recordExchange(HttpExchangeRecord record) {
sessionExchanges.get().add(record);
}
public static List<HttpExchangeRecord> getSessionExchanges() {
return Collections.unmodifiableList(sessionExchanges.get());
}
public static void clear() {
sessionExchanges.get().clear();
sessionExchanges.remove();
}
}
package com.nikita.restassured.diagnostics;
import io.restassured.http.Header;
import io.restassured.specification.FilterableRequestSpecification;
public class CurlCommandGenerator {
/**
* Synthesizes an exact, reproducible cURL command string from a FilterableRequestSpecification
*/
public static String generateCurl(FilterableRequestSpecification requestSpec) {
StringBuilder curl = new StringBuilder("curl -i -X ");
curl.append(requestSpec.getMethod()).append(" ");
curl.append("'").append(requestSpec.getURI()).append("'");
// Append transport headers
for (Header header : requestSpec.getHeaders()) {
// Mask or include headers as required for debugging
curl.append(" \\\n -H '").append(header.getName()).append(": ")
.append(escapeSingleQuotes(header.getValue())).append("'");
}
// Append body payload if present
if (requestSpec.getBody() != null) {
String bodyString = requestSpec.getBody().toString();
if (!bodyString.trim().isEmpty()) {
curl.append(" \\\n --data-raw '")
.append(escapeSingleQuotes(bodyString))
.append("'");
}
}
return curl.toString();
}
private static String escapeSingleQuotes(String str) {
if (str == null) return "";
return str.replace("'", "'\\''");
}
}
Filter that extracts outbound request metadata, generates the cURL command, captures the raw response, and registers the transaction into DiagnosticSessionContext.
package com.nikita.restassured.diagnostics;
import io.restassured.filter.Filter;
import io.restassured.filter.FilterContext;
import io.restassured.response.Response;
import io.restassured.specification.FilterableRequestSpecification;
import io.restassured.specification.FilterableResponseSpecification;
public class DiagnosticBufferFilter implements Filter {
@Override
public Response filter(FilterableRequestSpecification requestSpec,
FilterableResponseSpecification responseSpec,
FilterContext ctx) {
DiagnosticSessionContext.HttpExchangeRecord record = new DiagnosticSessionContext.HttpExchangeRecord();
// 1. Capture request metadata
record.method = requestSpec.getMethod();
record.uri = requestSpec.getURI();
record.requestHeaders = requestSpec.getHeaders().toString();
record.requestBody = requestSpec.getBody() != null ? requestSpec.getBody().toString() : "<EMPTY>";
record.generatedCurl = CurlCommandGenerator.generateCurl(requestSpec);
long startEpoch = System.currentTimeMillis();
// 2. Dispatch call across the wire socket
Response response = ctx.next(requestSpec, responseSpec);
long durationMs = System.currentTimeMillis() - startEpoch;
// 3. Capture response metadata
record.responseStatusCode = response.getStatusCode();
record.responseDurationMs = durationMs;
record.responseHeaders = response.getHeaders().toString();
record.responseBody = response.getBody() != null ? response.getBody().asPrettyString() : "<EMPTY>";
// 4. Store transaction in ThreadLocal memory buffer
DiagnosticSessionContext.recordExchange(record);
return response;
}
}
ApiFailureDiagnosticsListener. Implements ITestListener to monitor test outcomes, writing comprehensive diagnostics files to target/failure-dumps/ and printing high-visibility console banners whenever an assertion fails.
package com.nikita.restassured.diagnostics;
import org.testng.ITestContext;
import org.testng.ITestListener;
import org.testng.ITestResult;
import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.time.Instant;
import java.util.List;
public class ApiFailureDiagnosticsListener implements ITestListener {
private static final String DUMP_DIRECTORY = "target/failure-dumps";
@Override
public void onStart(ITestContext context) {
new File(DUMP_DIRECTORY).mkdirs();
}
@Override
public void onTestSuccess(ITestResult result) {
// Test passed cleanly: Purge in-memory wire buffer silently
DiagnosticSessionContext.clear();
}
@Override
public void onTestFailure(ITestResult result) {
String testClass = result.getTestClass().getRealClass().getSimpleName();
String testMethod = result.getMethod().getMethodName();
long threadId = Thread.currentThread().getId();
List<DiagnosticSessionContext.HttpExchangeRecord> exchanges = DiagnosticSessionContext.getSessionExchanges();
// 1. Build structured diagnostic dump file
String fileName = String.format("%s/%s_%s_FAILURE.log", DUMP_DIRECTORY, testClass, testMethod);
File dumpFile = new File(fileName);
try (FileWriter writer = new FileWriter(dumpFile)) {
writer.write("================================================================================\n");
writer.write("API TEST FAILURE DIAGNOSTIC REPORT\n");
writer.write("================================================================================\n");
writer.write("Timestamp : " + Instant.now() + "\n");
writer.write("Test Class : " + testClass + "\n");
writer.write("Test Method : " + testMethod + "\n");
writer.write("Worker Thread: Thread-" + threadId + "\n");
writer.write("Failure Cause: " + result.getThrowable().getMessage() + "\n");
writer.write("================================================================================\n\n");
int exchangeIndex = 1;
for (DiagnosticSessionContext.HttpExchangeRecord ex : exchanges) {
writer.write(String.format("----------------- [HTTP EXCHANGE #%d] -----------------\n", exchangeIndex++));
writer.write("METHOD & URI : " + ex.method + " " + ex.uri + "\n");
writer.write("STATUS CODE : HTTP " + ex.responseStatusCode + " (Duration: " + ex.responseDurationMs + " ms)\n\n");
writer.write("REPRODUCIBILITY cURL:\n");
writer.write(ex.generatedCurl + "\n\n");
writer.write("REQUEST HEADERS:\n" + ex.requestHeaders + "\n");
writer.write("REQUEST BODY:\n" + ex.requestBody + "\n\n");
writer.write("RESPONSE HEADERS:\n" + ex.responseHeaders + "\n");
writer.write("RESPONSE BODY:\n" + ex.responseBody + "\n\n");
}
writer.write("STACK TRACE:\n");
for (StackTraceElement element : result.getThrowable().getStackTrace()) {
writer.write(" at " + element.toString() + "\n");
}
} catch (IOException e) {
e.printStackTrace();
}
// 2. Print high-visibility banner to standard error for immediate CI console feedback
System.err.println("\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ");
System.err.printf("β β TEST FAILURE DETECTED: %s.%s()%n", testClass, testMethod);
System.err.printf("β π Diagnostic Dump Written: %s%n", dumpFile.getAbsolutePath());
if (!exchanges.isEmpty()) {
DiagnosticSessionContext.HttpExchangeRecord last = exchanges.get(exchanges.size() - 1);
System.err.printf("β π Last Wire Exchange: %s %s β HTTP %d (%d ms)%n",
last.method, last.uri, last.responseStatusCode, last.responseDurationMs);
System.err.println("β π Quick Reproduce cURL:\nβ " + last.generatedCurl.replace("\n", "\nβ "));
}
System.err.println("βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n");
// Clear ThreadLocal memory after writing the dump
DiagnosticSessionContext.clear();
}
@Override
public void onTestSkipped(ITestResult result) {
DiagnosticSessionContext.clear();
}
}
DiagnosticBufferFilter into a centralized RequestSpecBuilder factory, ensuring every service client inherits automated wire capture with zero manual boilerplate in test cases.
package com.nikita.restassured.diagnostics;
import io.restassured.builder.RequestSpecBuilder;
import io.restassured.http.ContentType;
import io.restassured.specification.RequestSpecification;
import java.util.UUID;
public class DiagnosticSpecFactory {
private static final String BASE_URI = "https://staging-api.nikita-infotech.com/v1";
public static RequestSpecification getDiagnosticSpec() {
return new RequestSpecBuilder()
.setBaseUri(BASE_URI)
.setContentType(ContentType.JSON)
.setAccept(ContentType.JSON)
.addHeader("X-Correlation-Id", "TRACE-DIAG-" + UUID.randomUUID().toString().substring(0, 8))
// Attach diagnostic buffer filter to all requests
.addFilter(new DiagnosticBufferFilter())
.build();
}
}
package com.nikita.restassured.diagnostics;
import io.restassured.specification.RequestSpecification;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.Listeners;
import org.testng.annotations.Test;
import java.util.HashMap;
import java.util.Map;
import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;
@Listeners(ApiFailureDiagnosticsListener.class)
public class StudentEnrollmentDiagnosticsTest {
private RequestSpecification spec;
@BeforeClass
public void setup() {
spec = DiagnosticSpecFactory.getDiagnosticSpec();
}
@Test(description = "Verify successful registration (Runs silently with zero log clutter)")
public void testSuccessfulEnrollment() {
Map<String, Object> payload = new HashMap<>();
payload.put("studentId", "STU-88219");
payload.put("fullName", "Nikita Sharma");
payload.put("enrolledCredits", 16);
given()
.spec(spec)
.body(payload)
.when()
.post("/students")
.then()
.statusCode(201)
.body("status", equalTo("SUCCESS"));
System.out.println("[β] Passing test completed cleanly. Zero diagnostic dumps generated.");
}
@Test(description = "Intentionally failing test asserting 200 instead of 422 to demonstrate failure dump")
public void testFailedCreditBoundaryValidation() {
Map<String, Object> payload = new HashMap<>();
payload.put("studentId", "STU-88220");
payload.put("fullName", "Aarav Deshmukh");
payload.put("enrolledCredits", 0); // Server returns 422 Unprocessable Entity
given()
.spec(spec)
.body(payload)
.when()
.post("/students")
.then()
// Intentionally asserting 200 to trigger failure diagnostics:
.statusCode(200);
}
}
ApiFailureDiagnosticsListener across an entire test suite in testng.xml and archiving failure dumps in Jenkins and GitHub Actions.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="EnterpriseDiagnosticsParallelSuite" parallel="methods" thread-count="4" verbose="1">
<!-- Global Listener Registration: Binds diagnostics listener to every test in suite -->
<listeners>
<listener class-name="com.nikita.restassured.diagnostics.ApiFailureDiagnosticsListener"/>
</listeners>
<test name="StudentEnrollmentServiceTests" preserve-order="false">
<packages>
<package name="com.nikita.restassured.diagnostics"/>
</packages>
</test>
</suite>
# .github/workflows/api-regression.yml
name: API Automation Regression
on: [push, pull_request]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up JDK 17
uses: actions/setup-java@v4
with:
java-version: '17'
distribution: 'temurin'
- name: Execute Parallel REST Assured Tests
run: mvn clean test -DsuiteXmlFile=src/test/resources/testng-diagnostics-suite.xml
# Archive failure diagnostic dumps only when tests fail
- name: Archive Failure Diagnostics Artifacts
if: failure()
uses: actions/upload-artifact@v4
with:
name: api-failure-diagnostics
path: target/failure-dumps/*.log
retention-days: 14
ThreadLocal buffers.
package com.nikita.restassured.diagnostics;
import org.testng.Assert;
import org.testng.annotations.Test;
public class DiagnosticsTriageTest {
// ==========================================================================
// PITFALL 1: STALE WIRE LOGS LEAKING ACROSS SEQUENTIAL TESTS
// Symptom: Test B fails, but its diagnostic report contains the request from Test A!
//
// CAUSE: Test A passed, but DiagnosticSessionContext.clear() was not called,
// leaving stale transactions in the reused thread's list.
//
// FIX: Always invoke clear() in onTestSuccess(), onTestFailure(), and onTestSkipped()!
// ==========================================================================
@Test(description = "Verify that DiagnosticSessionContext isolates transactions cleanly per test")
public void testSessionContextIsolation() {
// Step 1: Record mock exchange
DiagnosticSessionContext.HttpExchangeRecord record = new DiagnosticSessionContext.HttpExchangeRecord();
record.method = "GET";
record.uri = "https://staging-api.nikita-infotech.com/v1/health";
DiagnosticSessionContext.recordExchange(record);
Assert.assertEquals(DiagnosticSessionContext.getSessionExchanges().size(), 1);
// Step 2: Clear context (simulating listener cleanup)
DiagnosticSessionContext.clear();
// Step 3: Verify context is empty
Assert.assertEquals(DiagnosticSessionContext.getSessionExchanges().size(), 0,
"Session context must be empty following clear() invocation!");
System.out.println("[β] Verified: DiagnosticSessionContext properly purged memory.");
}
}
FAILURE DIAGNOSTICS & CUSTOM LISTENERS SPECIFICATION MATRIX:
βββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββ¬βββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββ
β DIAGNOSTIC COMPONENT β MECHANISM / IMPLEMENTATION β LIFECYCLE HOOK β PRIMARY OPERATIONAL PURPOSE β
βββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββΌβββββββββββββββββββΌββββββββββββββββββββββββββββββββββ€
β ITestListener β ApiFailureDiagnosticsListenerβ Test Status Flow β Captures onTestFailure events β
β Diagnostic Filter β DiagnosticBufferFilter β REST Assured Fltrβ Buffers request & response wire β
β ThreadLocal Context β DiagnosticSessionContext β Per-Thread Memoryβ Thread-safe transaction buffer β
β cURL Generator β CurlCommandGenerator β Helper Utility β Builds reproducible terminal cmdβ
β Diagnostic Dump File β target/failure-dumps/*.log β On Test Failure β Human-readable triage report β
β Console Alert Banner β System.err formatted banner β On Test Failure β High-visibility terminal alert β
β Buffer Cleanup β DiagnosticSessionContext.clr β Success/Skip/Failβ Prevents memory leakage in CI β
β Global Registration β <listeners> in testng.xml β Suite XML Config β Universal suite-wide coverage β
β CI Artifact Archiving β upload-artifact (GitHub/Jnk) β CI Post-Step β Archives failure logs for team β
βββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββ΄βββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββ€
β TOP 5 FAILURE DIAGNOSTICS BEST PRACTICES: β
β 1. Buffer in memory, dump on failure: Keep CI console output clean by dumping wire traffic only on bug. β
β 2. Generate executable cURL commands: Give developers instant single-line commands to reproduce issues. β
β 3. Always purge ThreadLocal context: Call clear() in onTestSuccess, onTestFailure, and onTestSkipped. β
β 4. Register listeners globally in testng.xml: Avoid manual @Listeners annotations across individual tests β
β 5. Archive failure logs as CI artifacts: Ensure diagnostic reports are preserved for post-build review. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ