Run Parallel API Tests with Java Virtual Threads

TL;DR

Use Executors.newVirtualThreadPerTaskExecutor(), submit one Callable result per API scenario, and inspect every Future. Add a Semaphore to cap active requests, use per-request timeouts, and aggregate failures so the test remains fast, responsible, and debuggable.

Key Takeaways

• Use Java 21 or newer so virtual threads are a stable platform feature.
• Create one virtual-thread task per independent API scenario, not per assertion.
• Share the thread-safe Java HttpClient and keep scenario state local.
• Bound outgoing requests with a semaphore even though virtual threads are cheap.
• Collect every Future so one failure cannot disappear in background work.
• Treat this pattern as functional concurrency testing, not a substitute for a load-testing tool.

Java virtual threads parallel API tests let you run many blocking HTTP checks concurrently without maintaining a large pool of platform threads. With Java 21 or newer, JUnit 5, and the built-in HttpClient, you can keep readable request-and-assert code while each scenario waits independently.

This tutorial builds a complete Maven project that starts a local HTTP fixture, sends parallel requests on virtual threads, limits pressure on the target, and reports all failures together. For the broader design choices behind the pattern, read the Java concurrency for test automation complete guide.

You will test a local service so the example is deterministic and safe to repeat. The same runner can target an authorized test environment after you replace the base URI and choose a concurrency limit the service owner approves.

What You Will Build

You will build a JUnit 5 test suite that:

• Starts an in-process HTTP server with a predictable /users/{id} endpoint.
• Executes 40 independent API scenarios through Executors.newVirtualThreadPerTaskExecutor().
• Shares one thread-safe HttpClient while keeping request data local to each task.
• Limits in-flight calls with a fair Semaphore.
• Captures status, body, duration, and thread identity in a typed result.
• Aggregates failures so the report shows every broken scenario, not only the first one.

The finished test is a functional concurrency check. It proves that several API examples can execute together and that your assertions remain isolated. It does not generate calibrated traffic, percentiles, or distributed load, so do not present its timings as performance-test evidence.

Prerequisites

Install JDK 21 or newer and Maven 3.9 or newer. Virtual threads became a final Java feature in JDK 21, so no preview flags are required. Confirm your tools:

java -version
mvn -version

The commands must report Java 21 or later for both the shell and Maven runtime. If Maven shows an older Java home, set JAVA_HOME to your JDK 21 installation before continuing.

Create an empty directory named virtual-thread-api-tests. The tutorial uses only JDK modules plus JUnit Jupiter, which keeps the example easy to audit and paste into a CI job.

Step 1: Create the Java 21 Maven Project

Create this layout:

virtual-thread-api-tests/
├── pom.xml
└── src/
    └── test/
        └── java/
            └── example/
                ├── LocalApiServer.java
                └── VirtualThreadApiTest.java

Add pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId>
  <artifactId>virtual-thread-api-tests</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <junit.version>5.12.2</junit.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.3</version>
        <configuration>
          <useModulePath>false</useModulePath>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

The compiler release prevents accidental use of a different bytecode level. Surefire discovers methods annotated with @Test, and the Jupiter aggregate supplies the API and engine. If your organization pins newer compatible versions, use its approved dependency catalog.

Verify the step: run mvn test. Maven should finish with BUILD SUCCESS and report that no tests were run. A compilation error mentioning source release 21 means Maven is using the wrong JDK.

Step 2: Build a Deterministic Local API

Add src/test/java/example/LocalApiServer.java:

package example;

import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;

import java.io.IOException;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.Executors;

final class LocalApiServer implements AutoCloseable {
    private final HttpServer server;

    LocalApiServer() throws IOException {
        server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
        server.createContext("/users", this::handleUser);
        server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
    }

    void start() {
        server.start();
    }

    String baseUrl() {
        return "http://127.0.0.1:" + server.getAddress().getPort();
    }

    private void handleUser(HttpExchange exchange) throws IOException {
        String method = exchange.getRequestMethod();
        String path = exchange.getRequestURI().getPath();
        String[] parts = path.split("/");

        if (!"GET".equals(method) || parts.length != 3) {
            send(exchange, 404, "{\"error\":\"not found\"}");
            return;
        }

        int id;
        try {
            id = Integer.parseInt(parts[2]);
        } catch (NumberFormatException exception) {
            send(exchange, 400, "{\"error\":\"invalid id\"}");
            return;
        }

        try {
            Thread.sleep(25);
        } catch (InterruptedException exception) {
            Thread.currentThread().interrupt();
            send(exchange, 503, "{\"error\":\"interrupted\"}");
            return;
        }

        send(exchange, 200, "{\"id\":" + id + ",\"name\":\"user-" + id + "\"}");
    }

    private static void send(HttpExchange exchange, int status, String body)
            throws IOException {
        byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
        exchange.getResponseHeaders().set("Content-Type", "application/json");
        exchange.sendResponseHeaders(status, bytes.length);
        try (var output = exchange.getResponseBody()) {
            output.write(bytes);
        }
    }

    @Override
    public void close() {
        server.stop(0);
    }
}

Port 0 asks the operating system for a free port, avoiding collisions in CI. The server uses virtual threads too, but that is not required by the client. The short sleep simulates blocking service work and makes concurrency visible without calling a public endpoint.

HttpServer.stop closes the listener. Its executor does not need explicit shutdown here because the virtual-thread-per-task executor creates threads per exchange and has no persistent worker pool. In a production fixture with owned executors, retain and close those resources explicitly.

Verify the step: run mvn test. The new class should compile and the build should succeed. There is still no test method, so Surefire may report zero tests.

Step 3: Run Java Virtual Threads Parallel API Tests

Add the initial src/test/java/example/VirtualThreadApiTest.java:

package example;

import org.junit.jupiter.api.Test;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.ArrayList;
import java.util.concurrent.Callable;
import java.util.concurrent.Executors;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

class VirtualThreadApiTest {
    private final HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(2))
            .build();

    @Test
    void javaVirtualThreadsParallelApiTests() throws Exception {
        try (var api = new LocalApiServer()) {
            api.start();
            var scenarios = new ArrayList<Callable<Void>>();

            for (int id = 1; id <= 40; id++) {
                int userId = id;
                scenarios.add(() -> {
                    HttpRequest request = HttpRequest.newBuilder()
                            .uri(URI.create(api.baseUrl() + "/users/" + userId))
                            .timeout(Duration.ofSeconds(2))
                            .GET()
                            .build();

                    HttpResponse<String> response = client.send(
                            request, HttpResponse.BodyHandlers.ofString());

                    assertTrue(Thread.currentThread().isVirtual());
                    assertEquals(200, response.statusCode());
                    assertTrue(response.body().contains("\"id\":" + userId));
                    return null;
                });
            }

            try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
                for (var future : executor.invokeAll(scenarios)) {
                    future.get();
                }
            }
        }
    }
}

Each lambda is a Callable<Void> containing one complete scenario. Capturing userId creates stable task input. The HttpClient is immutable and thread-safe, so sharing it enables connection reuse and avoids unnecessary clients. HttpRequest and the response remain local.

invokeAll submits every task and waits until all finish. Calling get() on every future is essential because an assertion inside a worker becomes an ExecutionException; it does not automatically fail the JUnit thread. The try-with-resources block closes the executor and waits for submitted work to end.

Verify the step: run mvn test. Expect one passing test. Temporarily change the expected status to 201; the test must fail with an ExecutionException whose cause is an assertion failure. Restore 200 afterward.

Step 4: Return Diagnostic Results Instead of Asserting in Workers

A future that throws proves failure, but a batch stops revealing detail when you inspect only the first failed future. Return a result from each task and aggregate at the JUnit boundary. Replace VirtualThreadApiTest.java with this version:

package example;

import org.junit.jupiter.api.Test;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.Callable;
import java.util.concurrent.Executors;

import static org.junit.jupiter.api.Assertions.assertAll;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

class VirtualThreadApiTest {
    record ApiResult(int userId, int status, String body,
                     Duration elapsed, boolean virtualThread) {}

    private final HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(2))
            .build();

    @Test
    void javaVirtualThreadsParallelApiTests() throws Exception {
        try (var api = new LocalApiServer()) {
            api.start();
            List<Callable<ApiResult>> scenarios = new ArrayList<>();
            for (int id = 1; id <= 40; id++) {
                int userId = id;
                scenarios.add(() -> callUser(api.baseUrl(), userId));
            }

            List<ApiResult> results = new ArrayList<>();
            try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
                for (var future : executor.invokeAll(scenarios)) {
                    results.add(future.get());
                }
            }

            assertEquals(40, results.size());
            assertAll(results.stream().map(result -> () -> {
                assertTrue(result.virtualThread(),
                        "user " + result.userId() + " did not use a virtual thread");
                assertEquals(200, result.status(),
                        "unexpected status for user " + result.userId());
                assertTrue(result.body().contains("\"id\":" + result.userId()),
                        "wrong body for user " + result.userId());
                assertTrue(result.elapsed().compareTo(Duration.ofSeconds(2)) < 0,
                        "slow response for user " + result.userId());
            }));
        }
    }

    private ApiResult callUser(String baseUrl, int userId) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(baseUrl + "/users/" + userId))
                .timeout(Duration.ofSeconds(2))
                .GET()
                .build();
        long started = System.nanoTime();
        HttpResponse<String> response = client.send(
                request, HttpResponse.BodyHandlers.ofString());
        Duration elapsed = Duration.ofNanos(System.nanoTime() - started);
        return new ApiResult(userId, response.statusCode(), response.body(),
                elapsed, Thread.currentThread().isVirtual());
    }
}

The worker performs transport work and records observations. The JUnit thread owns assertions. assertAll evaluates every result and reports multiple bad users in one run, which is much more useful when a shared service defect affects a subset of inputs.

The elapsed check is deliberately generous and local. Do not turn a laptop measurement into a universal service-level objective. Apply a latency assertion only when your environment and threshold are controlled.

Verify the step: run mvn test. Expect 40 results and one passing JUnit test. Change the body assertion to search for \"missing\"; the failure should list multiple suppressed assertion failures, proving aggregation works. Restore the original assertion.

Step 5: Limit Parallel API Test Concurrency

Virtual threads reduce thread cost, but they do not make the API, connection pool, database, or rate limit infinite. Add a semaphore around the network call. First add these imports:

import java.util.concurrent.Semaphore;

Add a field to the test class and replace callUser:

private final Semaphore requestSlots = new Semaphore(8, true);

private ApiResult callUser(String baseUrl, int userId) throws Exception {
    requestSlots.acquire();
    try {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(baseUrl + "/users/" + userId))
                .timeout(Duration.ofSeconds(2))
                .GET()
                .build();
        long started = System.nanoTime();
        HttpResponse<String> response = client.send(
                request, HttpResponse.BodyHandlers.ofString());
        Duration elapsed = Duration.ofNanos(System.nanoTime() - started);
        return new ApiResult(userId, response.statusCode(), response.body(),
                elapsed, Thread.currentThread().isVirtual());
    } finally {
        requestSlots.release();
    }
}

Forty virtual threads can exist, while no more than eight occupy the protected HTTP region. A virtual thread waiting in acquire() is parked efficiently. The finally block prevents a leaked permit when request creation, sending, or response handling fails. Fairness is optional, but true makes permit acquisition roughly arrival ordered and easier to reason about in a tutorial.

Choose the permit count from the test environment capacity, rate-limit policy, and purpose of the suite. Eight is an example, not a recommended universal value. For a deeper treatment, see how to control parallel test load with a Java Semaphore.

Verify the step: run mvn test and expect it to pass. For observable proof, temporarily print requestSlots.availablePermits() inside the protected block. Values should remain between zero and seven. Remove the print after checking because interleaved console logs make CI output noisy.

Step 6: Handle Timeouts, Interrupts, and Transport Failures

A robust batch should describe operational failures instead of losing the scenario identity. Extend the result so it can carry an error:

record ApiResult(int userId, int status, String body,
                 Duration elapsed, boolean virtualThread, Throwable error) {
    static ApiResult failed(int userId, Duration elapsed, Throwable error) {
        return new ApiResult(userId, -1, "", elapsed,
                Thread.currentThread().isVirtual(), error);
    }
}

Update the successful return with a final null, then wrap the protected work. Preserve interruption rather than swallowing it:

private ApiResult callUser(String baseUrl, int userId) {
    long started = System.nanoTime();
    boolean acquired = false;
    try {
        requestSlots.acquire();
        acquired = true;
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(baseUrl + "/users/" + userId))
                .timeout(Duration.ofSeconds(2))
                .GET()
                .build();
        HttpResponse<String> response = client.send(
                request, HttpResponse.BodyHandlers.ofString());
        return new ApiResult(userId, response.statusCode(), response.body(),
                Duration.ofNanos(System.nanoTime() - started),
                Thread.currentThread().isVirtual(), null);
    } catch (InterruptedException exception) {
        Thread.currentThread().interrupt();
        return ApiResult.failed(userId,
                Duration.ofNanos(System.nanoTime() - started), exception);
    } catch (Exception exception) {
        return ApiResult.failed(userId,
                Duration.ofNanos(System.nanoTime() - started), exception);
    } finally {
        if (acquired) {
            requestSlots.release();
        }
    }
}

Add this as the first assertion inside the assertAll lambda:

assertTrue(result.error() == null,
        () -> "request failed for user " + result.userId() + ": " + result.error());

Starting the timer before semaphore acquisition measures scenario wall time, including queueing. Start it after acquisition if you specifically want network time. Name the metric accordingly so readers do not compare different definitions.

Verify the step: run mvn test and expect success. Then change the request timeout to Duration.ofMillis(1). The test should fail with messages that identify user IDs and timeout errors. Restore two seconds.

Step 7: Make the Runner Safe for Real Test Suites

Move variable settings into system properties so CI can control them without editing code:

private static final int SCENARIO_COUNT =
        Integer.getInteger("api.scenarios", 40);
private static final int MAX_CONCURRENCY =
        Integer.getInteger("api.concurrency", 8);

private final Semaphore requestSlots =
        new Semaphore(MAX_CONCURRENCY, true);

Change the loop bound and count assertion from 40 to SCENARIO_COUNT. Run a smaller batch locally or a permitted larger batch in an isolated environment:

mvn test -Dapi.scenarios=12 -Dapi.concurrency=3

Validate configuration before submitting work. Add this near the beginning of the test method:

assertTrue(SCENARIO_COUNT > 0, "api.scenarios must be positive");
assertTrue(MAX_CONCURRENCY > 0, "api.concurrency must be positive");
assertTrue(MAX_CONCURRENCY <= SCENARIO_COUNT,
        "api.concurrency must not exceed api.scenarios");

Do not share mutable test data, authentication refresh state, or a non-thread-safe report object between tasks. Generate unique records per scenario and clean them by ID. If several requests depend on one asynchronous setup operation, coordinate it deliberately with the CompletableFuture test data setup tutorial instead of adding sleeps.

Also separate functional concurrency from load testing:

Verify the step: run the property-based Maven command. Expect one passing test with 12 collected results. Run once with -Dapi.concurrency=0; the validation must fail immediately instead of hanging.

Step 8: Read the Results Without Fooling Yourself

Virtual threads improve the scalability of blocking code. They do not guarantee that a parallel test finishes a fixed multiple faster. DNS, connection establishment, server capacity, HTTP protocol negotiation, semaphore queueing, CI contention, and warm-up all affect elapsed time.

Use the result record to answer functional questions first: Did every scenario return? Did each ID receive the correct representation? Did any request time out? Did isolation hold under overlap? Log structured diagnostics only for failures, including the scenario ID, URI without secrets, status, duration, and exception class. Never log access tokens or full sensitive bodies.

Avoid comparing virtual threads with a cached pool using one casual stopwatch run. A credible benchmark needs warm-up, repeated forks, controlled inputs, and a benchmark harness appropriate to the operation. An HTTP integration test also measures the server and network, not only Java scheduling.

When a result is flaky, reduce api.concurrency to one. If it becomes stable, investigate shared data, non-thread-safe helpers, ordering assumptions, and service limits. The guide to debugging Java test automation race conditions provides a systematic isolation workflow.

Verify the step: run the suite with concurrency 1, 4, and 8. All three runs should produce the same functional assertions. Timing may differ, but correctness must not. If correctness changes, stop increasing concurrency and diagnose the shared-state dependency.

Java Virtual Threads Parallel API Tests: Design Choices

Platform pools remain appropriate when you must cap actual task execution, integrate with a framework-owned executor, or run CPU-bound work sized near available processors. Virtual threads are best when tasks spend much of their time blocked on supported I/O and you want straightforward sequential code.

Do not wrap HttpClient.sendAsync() in a virtual thread merely to call join(). Choose one model. This tutorial intentionally uses blocking send() because virtual threads make that code easy to trace. Use asynchronous stages when composition, racing, or fan-in is the actual requirement.

Structured concurrency APIs may be attractive for scoped cancellation and failure propagation, but availability and preview status depend on the JDK release. The stable Java 21 executor pattern here needs no preview flags and is suitable for a conservative test repository. Reassess the stable APIs when your organization upgrades its JDK baseline.

Troubleshooting

invalid target release: 21 -> Maven is running on an older JDK. Check the Java runtime line in mvn -version, update JAVA_HOME, and reopen the terminal or CI step.

The test passes even when a worker assertion fails -> You submitted tasks but never inspected their futures. Call get() for every future, or return result objects and assert them on the JUnit thread.

Requests receive 429 or 503 responses -> Your concurrency exceeds an authorized service limit or current capacity. Lower the semaphore permits, add policy-compliant retry handling only for retryable operations, and coordinate with the service owner.

The suite hangs after a failure -> Check that every acquired semaphore permit is released in finally, every request has a timeout, and interruption is restored. Capture a thread dump before terminating the run.

Results change only in parallel mode -> Look for shared test accounts, static mutable fields, reused builders, order-dependent cleanup, and non-thread-safe reporters. Reproduce at concurrency two, then instrument scenario IDs around the smallest shared resource.

Virtual threads show unexpected carrier pinning or poor scaling -> Look for long blocking operations inside synchronized sections and native calls. Measure before rewriting, shorten critical sections, and keep network waits outside locks. Pinning is a diagnostic clue, not permission to remove necessary synchronization.

Common Mistakes

• Creating one HttpClient per request, which discards connection reuse and adds setup noise.
• Assuming cheap virtual threads make unlimited downstream concurrency safe.
• Sharing mutable request builders, response buffers, test users, or assertion collectors.
• Calling shutdownNow() immediately and interpreting cancellations as API defects.
• Swallowing InterruptedException, which breaks cancellation and shutdown behavior.
• Using a single batch duration as a performance benchmark or service-level claim.
• Sending parallel tests to production or a third-party API without explicit authorization.
• Retrying every failure, including assertions and non-idempotent operations, until a defect disappears.

Keep one scenario's inputs and outputs together. Bound the external resource, inspect every outcome, and make failure messages identify the exact case. Those habits matter more than the thread implementation.

Interview Questions and Answers

Q: Why are virtual threads useful for parallel API tests?

They allow many blocking HttpClient.send() calls to wait concurrently without dedicating one costly platform thread to every scenario. The code remains sequential inside each task, which simplifies stack traces and exception handling. The API capacity must still be bounded separately.

Q: Does one virtual thread per test remove the need for a semaphore?

No. Virtual threads address the client-side thread resource, while a semaphore protects limited external resources such as sockets, rate limits, databases, and the service itself. Cheap callers can overload a target even faster if concurrency is unbounded.

Q: Why must the test call Future.get()?

Exceptions thrown by executor tasks are stored in their futures. If the JUnit thread ignores those futures, worker assertion failures may never fail the test. Reading each future establishes explicit failure propagation.

Q: Is HttpClient safe to share across virtual threads?

Yes. Java's HttpClient is designed to send multiple requests and is typically shared for connection reuse. Build immutable requests per scenario and avoid shared mutable body or authentication helpers.

Q: Should API tests use send() or sendAsync() with virtual threads?

Use blocking send() when you want simple thread-per-scenario code. Use sendAsync() when completion-stage composition is valuable. Wrapping an asynchronous call only to block on it adds two concurrency models without a clear benefit.

Q: Are virtual threads suitable for CPU-heavy assertions?

They do not make CPU work faster. For sustained CPU-bound tasks, limit parallelism near the available processors or use an appropriately sized platform executor. Virtual threads are most helpful when tasks spend substantial time waiting.

Q: Can this JUnit pattern replace a load-testing tool?

No. It is useful for bounded functional concurrency and integration checks. A dedicated load tool is better for controlled arrival rates, distributed generation, throughput, percentiles, and formal performance reports.

Where To Go Next

Place the runner behind a test tag, start with a low permit count, and execute it against an isolated environment with unique data. Record the approved concurrency in CI configuration and make failures retain scenario identity.

Continue with the complete Java concurrency test automation guide to choose among executors, futures, locks, and coordination tools. Then learn parallel test data setup with CompletableFuture, Semaphore-based API load control, and race-condition debugging for Java automation.

Conclusion

Java virtual threads parallel API tests work well when each scenario performs blocking I/O and can run independently. Create one virtual thread per scenario, share the thread-safe client, keep state local, bound requests with a semaphore, apply timeouts, and bring every result back to the JUnit thread.

Start with the local fixture, prove that results stay correct at several concurrency settings, and only then point the suite at an authorized test environment. Treat virtual threads as a clear concurrency model, not as an excuse for unlimited traffic or unsupported performance claims.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• Generating API tests from OpenAPI with AI (2026)
• Run Playwright Component Tests with Vite in CI: Tutorial
• API contract testing with Pact: A Practical Guide (2026)
• Detecting flaky tests with machine learning (2026)
• Generating Selenium tests with AI (2026)
• Handle Nested Shadow Roots with Selenium Java