Core Concepts on Verifyica

Arguments

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

Arguments are the foundation of Verifyica testing. They define the test data that your tests will execute against.

The Argument<T> Interface

The Argument<T> interface is a type-safe container that associates a name with a payload:

public interface Argument<T> {
 String getName(); // Display name for test reporting
 T getPayload(); // The actual test data
 boolean hasPayload(); // Check if payload is non-null
 <V> V getPayloadAs(Class<V> type); // Cast payload to specific type
}

Why Use Argument<T>?

While you can use simple types like String or Integer directly, Argument<T> provides:

Lifecycle

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

Verifyica provides a comprehensive test lifecycle that gives you fine-grained control over setup and teardown at multiple levels.

Lifecycle Overview

Unlike traditional testing frameworks that only provide before/after hooks, Verifyica offers a complete lifecycle with five distinct phases:

Prepare - One-time setup before any arguments are processed
BeforeAll - Setup for each argument (before its tests)
BeforeEach - Setup before each individual test method
Test - The actual test execution
AfterEach - Cleanup after each individual test method
AfterAll - Cleanup for each argument (after its tests)
Conclude - One-time cleanup after all arguments are processed

Lifecycle Diagram

sequenceDiagram
 participant Engine as Test Engine
 participant TestClass as Test Class
 participant Interceptors as Interceptors

 Engine->>TestClass: @Prepare
 Engine->>TestClass: @ArgumentSupplier

 loop For Each Argument
 Interceptors->>TestClass: preBeforeAll
 Engine->>TestClass: @BeforeAll(argument)

 loop For Each @Test Method
 Engine->>TestClass: @BeforeEach(argument)
 Engine->>TestClass: @Test(argument)
 Engine->>TestClass: @AfterEach(argument)
 end

 Engine->>TestClass: @AfterAll(argument)
 Interceptors->>TestClass: postAfterAll
 end

 Engine->>TestClass: @Conclude

Lifecycle Annotations

@Prepare

Executes once before any arguments are processed.

Contexts

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

Verifyica provides three context objects that give you access to test execution state and metadata at different levels.

Context Hierarchy

EngineContext (Engine level)
 └── ClassContext (Test class level)
 └── ArgumentContext (Argument level)

Each context provides access to:

Its parent context
Configuration and properties
Test execution metadata
Lifecycle state

Context Types

ArgumentContext

The most commonly used context, providing access to the current argument and test execution state.

Interface

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

Usage in Test Methods

Inject ArgumentContext as a parameter to any lifecycle method:

Interceptors

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

Interceptors provide powerful extension points to hook into test execution for cross-cutting concerns like logging, metrics, resource management, or custom behavior.

Interceptor Types

Verifyica provides two interceptor interfaces:

ClassInterceptor - Intercepts class-level and argument-level execution
EngineInterceptor - Intercepts engine-level execution

ClassInterceptor

The ClassInterceptor interface provides hooks at multiple lifecycle points for each test class and argument.

Interface Overview

public interface ClassInterceptor {
 // Initialization
 void initialize(EngineContext engineContext) throws Throwable;

 // Filter which classes this interceptor applies to
 Predicate<ClassContext> predicate();

 // Class instantiation
 void preInstantiate(EngineContext engineContext, Class<?> testClass) throws Throwable;
 void postInstantiate(EngineContext engineContext, Class<?> testClass,
 Object testInstance, Throwable throwable) throws Throwable;

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

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

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

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

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

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

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

 // Cleanup
 void destroy(EngineContext engineContext) throws Throwable;
}

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

Execution Model

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

Understanding Verifyica’s execution model is crucial for writing efficient, parallel-friendly tests and reasoning about test behavior.

Execution Overview

Verifyica executes tests in a structured lifecycle that provides isolation, parallelism, and predictable ordering.

High-Level Flow

1. Test Discovery
 ↓
2. Engine Initialization
 ↓
3. For each Test Class:
 a. Instantiate test class
 b. Call @Prepare
 c. Call @ArgumentSupplier
 d. For each Argument (potentially parallel):
 - Call @BeforeAll
 - For each @Test method:
 - Call @BeforeEach
 - Call @Test
 - Call @AfterEach
 - Call @AfterAll
 e. Call @Conclude
 ↓
4. Engine Shutdown

Test Discovery

Verifyica uses the JUnit Platform test discovery mechanism to find test classes.