Advanced Topics on Verifyica

Advanced Parallelism

Mon, 01 Jan 0001 00:00:00 +0000

This page covers advanced parallelism patterns beyond the basics. See Configuration → Parallelism for basic configuration.

Resource Pooling with Parallel Arguments

When running arguments in parallel with limited resources, use a pool:

public class PooledResourceTest {

 private static final Semaphore resourcePool = new Semaphore(3); // Max 3 concurrent

 public static class TestContext {
 private final Resource resource;

 public TestContext(Resource resource) {
 this.resource = resource;
 }

 public Resource getResource() {
 return resource;
 }
 }

 @Verifyica.ArgumentSupplier(parallelism = 10)
 public static Object arguments() {
 return IntStream.range(0, 10)
 .mapToObj(i -> "arg-" + i)
 .collect(Collectors.toList());
 }

 @Verifyica.BeforeAll
 public void beforeAll(ArgumentContext argumentContext) throws InterruptedException {
 // Acquire from pool (blocks if pool is full)
 resourcePool.acquire();

 Resource resource = ResourcePool.getInstance().acquire();
 TestContext context = new TestContext(resource);
 argumentContext.getMap().put("testContext", context);
 }

 @Verifyica.Test
 public void test(ArgumentContext argumentContext) {
 TestContext context = (TestContext) argumentContext.getMap().get("testContext");
 context.getResource().use();
 }

 @Verifyica.AfterAll
 public void afterAll(ArgumentContext argumentContext) {
 TestContext context = (TestContext) argumentContext.getMap().get("testContext");
 if (context != null && context.getResource() != null) {
 ResourcePool.getInstance().release(context.getResource());
 resourcePool.release(); // Return to pool
 }
 }
}

Dynamic Port Allocation

Avoid port conflicts when running parallel tests:

Test Dependencies

Mon, 01 Jan 0001 00:00:00 +0000

The @DependsOn annotation allows you to specify that a test method should only run if another test method passes.

Overview

Use @DependsOn when a test requires another test to complete successfully first. If the dependency fails or is skipped, the dependent test is also skipped.

Basic Usage

import org.verifyica.api.DependsOn;
import org.verifyica.api.Verifyica;

public class DependencyTest {

 @Verifyica.ArgumentSupplier
 public static Object arguments() {
 return List.of("test-data");
 }

 @Verifyica.Test
 public void prerequisite(String argument) {
 // This must pass for dependent tests to run
 setupEnvironment();
 }

 @Verifyica.Test
 @DependsOn("prerequisite")
 public void dependentTest(String argument) {
 // Only runs if prerequisite passes
 performMainTest();
 }
}

Multiple Dependencies

A test can depend on multiple other tests:

Test Ordering

Mon, 01 Jan 0001 00:00:00 +0000

The @Order annotation allows you to specify the execution order of test methods within an argument.

Overview

By default, test methods execute in an undefined order. Use @Order when tests must run in a specific sequence.

Basic Usage

import org.verifyica.api.Order;
import org.verifyica.api.Verifyica;

public class OrderedTest {

 @Verifyica.ArgumentSupplier
 public static Object arguments() {
 return List.of("test-data");
 }

 @Verifyica.Test
 @Order(1)
 public void firstTest(String argument) {
 System.out.println("Runs first");
 }

 @Verifyica.Test
 @Order(2)
 public void secondTest(String argument) {
 System.out.println("Runs second");
 }

 @Verifyica.Test
 @Order(3)
 public void thirdTest(String argument) {
 System.out.println("Runs third");
 }
}

Order Values

Lower values execute first (e.g., @Order(1) before @Order(2))
Methods without @Order have default order value Integer.MAX_VALUE
Methods with the same order value execute in undefined order

Example: Setup and Teardown Sequence

public class DatabaseMigrationTest {

 @Verifyica.ArgumentSupplier
 public static Object arguments() {
 return List.of(Argument.of("production-db", new DbConfig()));
 }

 @Verifyica.Test
 @Order(1)
 public void createTables(ArgumentContext argumentContext) {
 // Must run first
 database.createTables();
 }

 @Verifyica.Test
 @Order(2)
 public void insertData(ArgumentContext argumentContext) {
 // Runs after tables are created
 database.insertTestData();
 }

 @Verifyica.Test
 @Order(3)
 public void verifyData(ArgumentContext argumentContext) {
 // Runs after data is inserted
 assert database.countRows() > 0;
 }
}

Combining with @DependsOn

You can use both @Order and @DependsOn together:

Test Tagging

Mon, 01 Jan 0001 00:00:00 +0000

The @Tag annotation allows you to label tests for filtering and organization.

Overview

Tags provide a flexible way to categorize tests so you can run specific subsets during different testing scenarios.

Basic Usage

import org.verifyica.api.Tag;
import org.verifyica.api.Verifyica;

@Tag("integration")
public class IntegrationTest {

 @Verifyica.ArgumentSupplier
 public static Object arguments() {
 return List.of("test-data");
 }

 @Verifyica.Test
 public void testDatabaseConnection(String argument) {
 // Tagged as "integration" from class level
 }
}

Multiple Tags

Apply multiple tags to organize tests by different dimensions:

Cleanup Executor

Mon, 01 Jan 0001 00:00:00 +0000

The CleanupExecutor utility helps manage cleanup tasks that must execute in reverse order, even when exceptions occur.

Overview

CleanupExecutor is a specialized utility that:

Executes cleanup tasks in reverse order (LIFO - Last In, First Out)
Continues executing all cleanup tasks even if some fail
Collects all exceptions that occur during cleanup

Basic Usage

import org.verifyica.api.CleanupExecutor;

public class CleanupTest {

 @Verifyica.BeforeAll
 public void beforeAll(ArgumentContext argumentContext) {
 CleanupExecutor cleanupExecutor = new CleanupExecutor();

 try {
 // Setup resources and register cleanup
 Connection conn = database.connect();
 cleanupExecutor.add(() -> conn.close());

 Server server = new Server();
 server.start();
 cleanupExecutor.add(() -> server.stop());

 // Store cleanup executor in context
 argumentContext.getMap().put("cleanup", cleanupExecutor);

 } catch (Exception e) {
 // If setup fails, execute cleanup
 cleanupExecutor.execute();
 throw e;
 }
 }

 @Verifyica.AfterAll
 public void afterAll(ArgumentContext argumentContext) throws Throwable {
 CleanupExecutor cleanupExecutor =
 (CleanupExecutor) argumentContext.getMap().get("cleanup");

 if (cleanupExecutor != null) {
 cleanupExecutor.execute();
 }
 }
}

Example: Nested Resource Setup

public class NestedResourceTest {

 public static class TestContext {
 private final CleanupExecutor cleanupExecutor;

 public TestContext(CleanupExecutor cleanupExecutor) {
 this.cleanupExecutor = cleanupExecutor;
 }

 public CleanupExecutor getCleanupExecutor() {
 return cleanupExecutor;
 }
 }

 @Verifyica.BeforeAll
 public void beforeAll(ArgumentContext argumentContext) {
 CleanupExecutor cleanupExecutor = new CleanupExecutor();

 try {
 // 1. Create database
 Database db = Database.create("test-db");
 cleanupExecutor.add(() -> db.drop());

 // 2. Connect to database
 Connection conn = db.connect();
 cleanupExecutor.add(() -> conn.close());

 // 3. Create schema
 conn.execute("CREATE TABLE users (id INT, name VARCHAR(100))");
 cleanupExecutor.add(() -> conn.execute("DROP TABLE users"));

 // 4. Insert test data
 conn.execute("INSERT INTO users VALUES (1, 'Alice')");
 cleanupExecutor.add(() -> conn.execute("DELETE FROM users"));

 TestContext context = new TestContext(cleanupExecutor);
 argumentContext.getMap().put("testContext", context);

 } catch (Exception e) {
 cleanupExecutor.execute();
 throw new RuntimeException("Setup failed", e);
 }
 }

 @Verifyica.Test
 public void test(ArgumentContext argumentContext) {
 // Test logic
 }

 @Verifyica.AfterAll
 public void afterAll(ArgumentContext argumentContext) throws Throwable {
 TestContext context = (TestContext) argumentContext.getMap().get("testContext");
 if (context != null && context.getCleanupExecutor() != null) {
 // Executes in reverse order:
 // 4. DELETE FROM users
 // 3. DROP TABLE users
 // 2. conn.close()
 // 1. db.drop()
 context.getCleanupExecutor().execute();
 }
 }
}

Error Handling

CleanupExecutor collects all exceptions:

Keyed Concurrency Utilities

Mon, 01 Jan 0001 00:00:00 +0000

Verifyica provides keyed concurrency utilities for fine-grained synchronization in parallel tests.

Overview

Keyed concurrency utilities allow you to synchronize on specific keys rather than globally:

KeyedMutexManager - Mutual exclusion per key
KeyedLatchManager - Count-down latches per key
KeyedSemaphoreManager - Semaphores per key

KeyedMutexManager

Provides mutual exclusion on a per-key basis.

Basic Usage

import org.verifyica.api.concurrent.KeyedMutexManager;

public class MutexTest {

 @Verifyica.ArgumentSupplier(parallelism = 10)
 public static Object arguments() {
 return List.of("user-1", "user-2", "user-3");
 }

 @Verifyica.Test
 public void testConcurrentAccess(String userId) {
 // Only one test can access this user at a time
 KeyedMutexManager.lock(userId);
 try {
 updateUser(userId);
 } finally {
 KeyedMutexManager.unlock(userId);
 }
 }
}

Example: Database Row Locking

public class RowLockTest {

 @Verifyica.Test
 public void testRowUpdate(String rowId) {
 KeyedMutexManager.lock(rowId);
 try {
 // Exclusive access to this row
 Row row = database.getRow(rowId);
 row.setValue(row.getValue() + 1);
 database.updateRow(row);
 } finally {
 KeyedMutexManager.unlock(rowId);
 }
 }
}

KeyedLatchManager

Count-down latches per key for coordination.