This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

API Reference

Complete API reference for Verifyica annotations, interfaces, and utilities

This section provides detailed API documentation for all Verifyica components.

Core APIs

Utility APIs

  • Utilities - CleanupExecutor, TemporaryDirectory, RandomUtil
  • Concurrency - KeyedMutexManager, KeyedLatchManager, KeyedSemaphoreManager

Quick Reference

Lifecycle Annotations

AnnotationWhen It RunsReceives Argument
@PrepareOnce before all argumentsNo
@BeforeAllOnce per argument, before testsYes
@BeforeEachBefore each test methodYes
@TestTest executionYes
@AfterEachAfter each test methodYes
@AfterAllOnce per argument, after testsYes
@ConcludeOnce after all argumentsNo

Key Interfaces

InterfacePurpose
Argument<T>Type-safe argument container
ArgumentContextAccess to current argument execution state
ClassContextAccess to test class execution state
EngineContextAccess to engine-level configuration
ClassInterceptorHook into test lifecycle
EngineInterceptorHook into engine lifecycle

Javadoc

For complete Javadoc, see the Maven Central repository or generate locally:

mvn javadoc:javadoc

Next Steps

Browse the API reference sections to learn about specific components.

1 - Annotations

Complete reference for all @Verifyica annotations

All Verifyica annotations are nested within the @Verifyica interface.

Lifecycle Annotations

@Verifyica.Prepare

Marks a method to execute once before any arguments are processed.

Method signature:

// No parameters
@Verifyica.Prepare
public void prepare() { }

// OR ClassContext only
@Verifyica.Prepare
public void prepare(ClassContext classContext) { }

Supported parameters: None OR ClassContext only (NOT EngineContext, NOT ArgumentContext)

Execution: Once per test class, before argument processing Use for: Global setup, starting services, initializing shared resources

@Verifyica.ArgumentSupplier

Marks a static method that provides test arguments.

Method signature:

@Verifyica.ArgumentSupplier
public static Object arguments() { }

// With parallelism
@Verifyica.ArgumentSupplier(parallelism = 4)
public static Collection<String> arguments() { }

Parameters:

  • parallelism - Number of arguments to execute in parallel (default: 1)

Return types: Collection, Array, Stream, or Argument instances

@Verifyica.BeforeAll

Marks a method to execute once per argument before its tests.

Method signature:

// Unwrapped argument
@Verifyica.BeforeAll
public void beforeAll(ArgumentType argument) { }

// OR ArgumentContext
@Verifyica.BeforeAll
public void beforeAll(ArgumentContext argumentContext) { }

Supported parameters: Unwrapped argument OR ArgumentContext only (choose one, not both)

Execution: Once per argument, before test methods Use for: Argument-specific setup, creating connections

@Verifyica.BeforeEach

Marks a method to execute before each test method.

Method signature:

@Verifyica.BeforeEach
public void beforeEach(ArgumentType argument) { }

Execution: Before each @Test method for each argument Use for: Test-specific setup, resetting state

@Verifyica.Test

Marks a test method.

Method signature:

// Unwrapped argument
@Verifyica.Test
public void testMethod(ArgumentType argument) { }

// OR ArgumentContext
@Verifyica.Test
public void testMethod(ArgumentContext argumentContext) { }

Supported parameters: Unwrapped argument OR ArgumentContext only (choose one, not both)

Execution: Once per argument Use for: Test logic

@Verifyica.AfterEach

Marks a method to execute after each test method.

Method signature:

@Verifyica.AfterEach
public void afterEach(ArgumentType argument) { }

Execution: After each @Test method for each argument Use for: Test-specific cleanup

@Verifyica.AfterAll

Marks a method to execute once per argument after its tests.

Method signature:

@Verifyica.AfterAll
public void afterAll(ArgumentType argument) { }

Execution: Once per argument, after all test methods Use for: Argument-specific cleanup, closing connections

@Verifyica.Conclude

Marks a method to execute once after all arguments are processed.

Method signature:

// No parameters
@Verifyica.Conclude
public void conclude() { }

// OR ClassContext only
@Verifyica.Conclude
public void conclude(ClassContext classContext) { }

Supported parameters: None OR ClassContext only (NOT EngineContext, NOT ArgumentContext)

Execution: Once per test class, after all argument processing Use for: Global cleanup, stopping services

Supporting Annotations

@Tag

Marks tests with tags for filtering.

import org.verifyica.api.Tag;

@Tag("integration")
@Tag("database")
public class DatabaseTest { }

// Method-level tags
@Verifyica.Test
@Tag("slow")
public void slowTest(String argument) { }

Use for: Filtering tests with include/exclude filters

@Order

Controls test method execution order.

import org.verifyica.api.Order;

@Verifyica.Test
@Order(1)
public void firstTest(String argument) { }

@Verifyica.Test
@Order(2)
public void secondTest(String argument) { }

Note: Lower order values execute first

@DependsOn

Specifies test dependencies.

import org.verifyica.api.DependsOn;

@Verifyica.Test
public void test1(String argument) { }

@Verifyica.Test
@DependsOn("test1")
public void test2(String argument) { }

Use for: Ensuring tests execute in specific order

Annotation Examples

Complete Lifecycle

public class FullLifecycleTest {

    @Verifyica.Prepare
    public void prepare() {
        // Global setup
    }

    @Verifyica.ArgumentSupplier(parallelism = 2)
    public static Collection<String> arguments() {
        return Arrays.asList("arg1", "arg2");
    }

    @Verifyica.BeforeAll
    public void beforeAll(String argument) {
        // Per-argument setup
    }

    @Verifyica.BeforeEach
    public void beforeEach(String argument) {
        // Per-test setup
    }

    @Verifyica.Test
    @Order(1)
    @Tag("unit")
    public void test1(String argument) {
        // Test logic
    }

    @Verifyica.Test
    @Order(2)
    @DependsOn("test1")
    public void test2(String argument) {
        // Depends on test1
    }

    @Verifyica.AfterEach
    public void afterEach(String argument) {
        // Per-test cleanup
    }

    @Verifyica.AfterAll
    public void afterAll(String argument) {
        // Per-argument cleanup
    }

    @Verifyica.Conclude
    public void conclude() {
        // Global cleanup
    }
}

See Also

2 - Argument API

Complete API reference for the Argument interface

The Argument<T> interface provides type-safe containers for test data.

Interface Definition

public interface Argument<T> {
    String getName();
    T getPayload();
    boolean hasPayload();
    <V> V getPayloadAs(Class<V> type);
}

Methods

getName()

Returns the display name of this argument.

Argument<String> arg = Argument.of("test-name", "value");
String name = arg.getName(); // Returns "test-name"

getPayload()

Returns the payload value.

Argument<Config> arg = Argument.of("config", new Config());
Config config = arg.getPayload();

hasPayload()

Checks if the payload is non-null.

Argument<String> arg = Argument.of("name", null);
boolean has = arg.hasPayload(); // Returns false

getPayloadAs(Class)

Casts the payload to a specific type.

Argument<?> arg = Argument.of("name", new DatabaseConfig());
DatabaseConfig config = arg.getPayloadAs(DatabaseConfig.class);

Factory Methods

Generic Arguments

Argument<T> of(String name, T payload)

Creates a named argument with a payload.

Primitive Type Factory Methods

Argument<Boolean> ofBoolean(boolean value)
Argument<Integer> ofInt(int value)
Argument<Long> ofLong(long value)
Argument<Double> ofDouble(double value)
Argument<String> ofString(String value)

BigDecimal and BigInteger

Argument<BigInteger> ofBigInteger(String value)
Argument<BigDecimal> ofBigDecimal(String value)

See Also

3 - Context API

API reference for EngineContext, ClassContext, and ArgumentContext

Context objects provide access to test execution state and metadata.

ArgumentContext

The most commonly used context, providing access to the current argument.

Interface

public interface ArgumentContext extends Context {
    ClassContext getClassContext();
    int getArgumentIndex();
    Argument<?> getArgument();
    <V> Argument<V> getArgumentAs(Class<V> type);
    Map<String, Object> getMap();
}

Methods

MethodDescription
getArgument()Returns the current Argument
getArgumentAs(Class<V>)Returns the argument cast to specific type
getArgumentIndex()Returns the argument’s index (0-based)
getClassContext()Returns the parent ClassContext
getMap()Returns a thread-safe map for storing per-argument state

ClassContext

Provides access to test class-level information.

Interface

public interface ClassContext extends Context {
    EngineContext getEngineContext();
    Class<?> getTestClass();
    Object getTestInstance();
    Map<String, Object> getMap();
}

Methods

MethodDescription
getTestClass()Returns the test class (Class)
getTestInstance()Returns the test instance object
getEngineContext()Returns the parent EngineContext
getMap()Returns a thread-safe map for storing class-level state

EngineContext

Provides access to engine-level configuration.

Interface

public interface EngineContext extends Context {
    Configuration getConfiguration();
    Map<String, Object> getMap();
}

Methods

MethodDescription
getConfiguration()Returns the Configuration object
getMap()Returns a thread-safe map for storing engine-level state

Context Map Usage

All context objects provide a getMap() method that returns a thread-safe map for storing state:

@Verifyica.BeforeAll
public void beforeAll(ArgumentContext argumentContext) {
    TestContext context = new TestContext(/* ... */);
    argumentContext.getMap().put("testContext", context);
}

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

See Also

4 - Interceptor API

API reference for ClassInterceptor and EngineInterceptor

Interceptors allow hooking into the test lifecycle.

ClassInterceptor

Intercepts lifecycle events at the class level.

Interface

public interface ClassInterceptor {
    // Initialization
    void initialize(EngineContext engineContext);
    Predicate<ClassContext> predicate();

    // Lifecycle hooks
    void prePrepare(ClassContext classContext, Method method);
    void postPrepare(ClassContext classContext, Method method, Throwable throwable);

    void preBeforeAll(ArgumentContext argumentContext, Method method);
    void postBeforeAll(ArgumentContext argumentContext, Method method, Throwable throwable);

    void preBeforeEach(ArgumentContext argumentContext, Method method);
    void postBeforeEach(ArgumentContext argumentContext, Method method, Throwable throwable);

    void preTest(ArgumentContext argumentContext, Method method);
    void postTest(ArgumentContext argumentContext, Method method, Throwable throwable);

    void preAfterEach(ArgumentContext argumentContext, Method method);
    void postAfterEach(ArgumentContext argumentContext, Method method, Throwable throwable);

    void preAfterAll(ArgumentContext argumentContext, Method method);
    void postAfterAll(ArgumentContext argumentContext, Method method, Throwable throwable);

    void preConclude(ClassContext classContext, Method method);
    void postConclude(ClassContext classContext, Method method, Throwable throwable);

    void destroy(EngineContext engineContext);
}

All methods have default implementations, so you only need to override the ones you need.

Registration

Register via ServiceLoader in META-INF/services/org.verifyica.api.ClassInterceptor:

com.example.MyClassInterceptor

EngineInterceptor

Intercepts lifecycle events at the engine level.

Interface

public interface EngineInterceptor {
    void initialize(EngineContext engineContext);
    void beforeAll(EngineContext engineContext);
    void afterAll(EngineContext engineContext);
    void destroy(EngineContext engineContext);
}

Registration

Register via ServiceLoader in META-INF/services/org.verifyica.api.EngineInterceptor:

com.example.MyEngineInterceptor

See Also

5 - Utilities

Utility classes for common testing tasks

Verifyica provides utility classes for common testing scenarios.

CleanupExecutor

Manages cleanup tasks in reverse order (LIFO).

CleanupExecutor cleanupExecutor = new CleanupExecutor();

cleanupExecutor.add(() -> resource1.close());
cleanupExecutor.add(() -> resource2.close());

// Executes resource2.close() then resource1.close()
cleanupExecutor.execute();

See Advanced → Cleanup Executor for detailed usage.

TemporaryDirectory

Creates temporary directories for tests.

TemporaryDirectory tempDir = TemporaryDirectory.create();
Path path = tempDir.getPath();

// Use directory...

tempDir.close(); // Deletes directory and contents

RandomUtil

Utilities for random values in tests.

int randomInt = RandomUtil.nextInt(100);
String randomString = RandomUtil.nextString(10);

See Also

6 - Concurrency Utilities

Keyed concurrency utilities for parallel testing

Keyed concurrency utilities for fine-grained synchronization.

KeyedMutexManager

Provides mutual exclusion per key using static methods.

KeyedMutexManager.lock("key");
try {
    // Critical section for this key
} finally {
    KeyedMutexManager.unlock("key");
}

KeyedLatchManager

Count-down latches per key using static methods.

KeyedLatchManager.createLatch("key", 3); // Count of 3
KeyedLatchManager.countDown("key");
KeyedLatchManager.await("key"); // Waits until count reaches 0

KeyedSemaphoreManager

Semaphores per key for resource limiting using static methods.

KeyedSemaphoreManager.createSemaphore("resource", 5); // Max 5 permits
KeyedSemaphoreManager.acquire("resource");
try {
    // Use resource
} finally {
    KeyedSemaphoreManager.release("resource");
}

See Also