CUSTOM TESTNG LISTENERS: FAILURE DIAGNOSTICS & WIRE DUMPS

Architect production-grade test observability and failure diagnostics in REST Assured: TestNG ITestListener and IInvokedMethodListener architectures, automated wire transaction interception, failure-only diagnostic dumps, ThreadLocal session buffers, curl command generators, and structured CI triage artifact exports.

🩺 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.

1. TestNG Failure Diagnostics Architecture & Buffer Flow Topography
The multi-stage architectural lifecycle of failure diagnostics, showing how REST Assured wire events are held in memory per thread, inspected by TestNG listeners upon status transitions, and exported to disk only when assertions fail.
In-Memory Diagnostic Buffer & Failure Dump Architecture
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   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜      β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Architectural Standard: Never log HTTP payloads directly to standard output in production test frameworks. Holding session metadata in ThreadLocal memory buffers keeps CI logs clean on success while ensuring complete, high-fidelity wire dumps are instantly available for failing assertions.
Real-Time Example 1: ThreadLocal Diagnostic Session Context Model
Designing the in-memory diagnostic data model. Captures outbound requests, inbound responses, timestamps, latency metrics, and cURL commands inside an isolated ThreadLocal container to guarantee concurrency safety.
Java (DiagnosticSessionContext.java Concurrency Container)
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();
    }
}
Concurrency Safety Standard: ThreadLocal.withInitial(ArrayList::new) allocates a distinct list per worker thread. In multi-step workflows with several API calls, every HTTP transaction is chronologically recorded and cleanly isolated from competing threads.
Real-Time Example 2: Reproducible cURL Command Generator Engine
Building an automated cURL command generator. Inspects request specifications, extracts headers and body payloads, escapes single quotes, and builds fully executable terminal commands for instant defect reproduction.
Java (CurlCommandGenerator.java Automated Terminal Synthesizer)
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("'", "'\\''");
    }
}
Generated cURL Output Format: curl -i -X POST 'https://staging-api.nikita-infotech.com/v1/students' \ -H 'Content-Type: application/json' \ -H 'X-Correlation-Id: TRACE-21-4f8a10c9' \ --data-raw '{"studentId":"STU-88219","enrolledCredits":0}' Engineers can copy this command straight from the failure report and paste it into a terminal to reproduce the defect instantly.
Real-Time Example 3: Diagnostic Buffer REST Assured Filter
Intercepting and buffering wire data. Creates a custom Filter that extracts outbound request metadata, generates the cURL command, captures the raw response, and registers the transaction into DiagnosticSessionContext.
Java (DiagnosticBufferFilter.java Non-Intrusive Wire Collector)
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;
    }
}
Filter Lifecycle Telemetry: Filter captures full exchange in memory with zero console output. Response times and payload sizes are tracked automatically without distorting socket transmission.
Real-Time Example 4: Custom TestNG ITestListener Failure Dump Generator
Building the core 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.
Java (ApiFailureDiagnosticsListener.java Automated CI Reporter)
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();
    }
}
CI Console Diagnostic Banner: ╔════════════════════════════════════════════════════════════════════════════════ β•‘ ❌ TEST FAILURE DETECTED: StudentRegistrationTest.testEnrollmentCreditBoundary() β•‘ πŸ“ Diagnostic Dump Written: target/failure-dumps/StudentRegistrationTest_testEnrollmentCreditBoundary_FAILURE.log β•‘ 🌐 Last Wire Exchange: POST https://staging-api.../students βž” HTTP 422 (88 ms) β•‘ πŸ“‹ Quick Reproduce cURL: β•‘ curl -i -X POST 'https://staging-api.../students' \ β•‘ -H 'Content-Type: application/json' \ β•‘ --data-raw '{"studentId":"STU-88219","enrolledCredits":0}' β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•
Real-Time Example 5: Wiring Diagnostic Buffer into Base Specification Factory
Seamless framework integration. Embeds DiagnosticBufferFilter into a centralized RequestSpecBuilder factory, ensuring every service client inherits automated wire capture with zero manual boilerplate in test cases.
Java (DiagnosticSpecFactory.java Centralized Specification)
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();
    }
}
Integration Benefit: Attaching DiagnosticBufferFilter in the central specification automatically equips every downstream API call with diagnostic recording capabilities.
Real-Time Example 6: End-to-End Test Execution with Deliberate Failure Triage
A complete test execution example. Runs two test scenariosβ€”a passing test that executes silently and an intentionally failing assertion that triggers the full failure diagnostic pipeline.
Java (StudentEnrollmentDiagnosticsTest.java Execution)
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);
    }
}
Execution Telemetry: [βœ”] Passing test completed cleanly. Zero diagnostic dumps generated. ╔════════════════════════════════════════════════════════════════════════════════ β•‘ ❌ TEST FAILURE DETECTED: StudentEnrollmentDiagnosticsTest.testFailedCreditBoundaryValidation() β•‘ πŸ“ Diagnostic Dump Written: target/failure-dumps/StudentEnrollmentDiagnosticsTest_testFailedCreditBoundaryValidation_FAILURE.log β•‘ 🌐 Last Wire Exchange: POST https://staging-api.nikita-infotech.com/v1/students βž” HTTP 422 (92 ms) β•‘ πŸ“‹ Quick Reproduce cURL: β•‘ curl -i -X POST 'https://staging-api.nikita-infotech.com/v1/students' \ β•‘ -H 'Content-Type: application/json' \ β•‘ --data-raw '{"fullName":"Aarav Deshmukh","enrolledCredits":0,"studentId":"STU-88220"}' β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β• Dump file generated instantly on failure with full wire inspection details.
Real-Time Example 7: TestNG XML Global Listener Registration & CI Artifact Archiving
Registering listeners globally and configuring CI build pipelines. Demonstrates binding ApiFailureDiagnosticsListener across an entire test suite in testng.xml and archiving failure dumps in Jenkins and GitHub Actions.
XML (src/test/resources/testng-diagnostics-suite.xml)
<?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>
YAML (CI/CD Pipeline Artifact Archiving in GitHub Actions)
# .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
CI Pipeline Telemetry: Regression suite ran 450 tests across 4 parallel threads. 449 tests passed silently; 1 test failed. Failure dump uploaded: api-failure-diagnostics.zip containing exact wire dumps and cURL scripts.
Real-Time Example 8: Debugging Listener Pitfalls & Memory Leak Triage
Troubleshooting common listener issues: preventing memory leaks in long-running suites, handling skipped test cleanups, and avoiding concurrent modifications in ThreadLocal buffers.
Java (Triage: Diagnosing ThreadLocal Leaks & Cleanups)
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.");
    }
}
Triage Diagnostic Breakdown: - Problem: Stale wire logs appearing in reports of unrelated tests. - Root Cause: Reused thread pool threads did not clear the ThreadLocal list. - Fix Applied: Ensured clear() is called in all ITestListener status callback methods. - Result: Clean, isolated diagnostic logs for every test method.
Real-Time Example 9: Custom Listeners & Diagnostics Reference Matrix
A comprehensive reference summary pairing TestNG listener interfaces, REST Assured filter hooks, diagnostic components, and operational best practices for enterprise API test observability.
Failure Diagnostics Specification Reference Matrix
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.     β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Engineering Best Practice: Custom failure diagnostics transform test failures from cryptic stack traces into actionable incident reports. By coupling in-memory ThreadLocal buffering with TestNG failure listeners, automated cURL generators, and structured log archiving, you eliminate triage friction and enable engineering teams to resolve API regressions rapidly.