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

Return to the regular view of this page.

Getting Started

Get up and running with Verifyica in minutes

1: Installation
2: Quick Start
3: Your First Test

This section will help you get started with Verifyica, from installation to writing your first test.

Prerequisites

Before you begin, ensure you have:

Java 8 or higher - Verifyica is compatible with Java 8+
Maven - For dependency management
JUnit Platform - Verifyica is a JUnit Platform based TestEngine

Installation - Add Verifyica to your Maven project
Quick Start - Write and run your first test in 5 minutes
First Test - Deep dive into creating and understanding tests

What You’ll Learn

By the end of this section, you’ll be able to:

Add Verifyica as a dependency to your project
Write a simple argument-driven test
Understand the basic test lifecycle
Run tests with your build tool or IDE
Configure basic parallelism

Next Steps

Once you’re comfortable with the basics, explore:

Core Concepts - Understand Verifyica’s architecture
Configuration - Configure Verifyica for your needs
Examples - See more complex examples

1 - Installation

Add Verifyica to your Maven project

Overview

Verifyica is available on Maven Central and can be added to your project using Maven. You need to add two dependencies:

verifyica-api - Contains annotations and API classes
verifyica-engine - The JUnit Platform based TestEngine implementation

Maven

Add the following dependencies to your pom.xml:

<dependencies>
    
    <!-- Verifyica API (compile scope for annotations) -->
    <dependency>
        <groupId>org.verifyica</groupId>
        <artifactId>verifyica-api</artifactId>
        <version>1.0.6</version>
    </dependency>

    <!-- Verifyica Engine (test scope) -->
    <dependency>
        <groupId>org.verifyica</groupId>
        <artifactId>verifyica-engine</artifactId>
        <version>1.0.6</version>
        <scope>test</scope>
    </dependency>

</dependencies>

Maven Surefire Configuration

Configure the Maven Surefire plugin to ignore Verifyica tests (they will be run by the Verifyica Maven Plugin):

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.5.2</version>
            <configuration>
                <excludes>
                    <!-- Exclude Verifyica tests ... this should match standard JUnit tests -->
                    <exclude>**/*</exclude>
                </excludes>
            </configuration>
        </plugin>
    </plugins>
</build>

Verifyica Maven Plugin (Required)

Add the Verifyica Maven Plugin to run your tests:

<build>
    <plugins>
        <plugin>
            <groupId>org.verifyica</groupId>
            <artifactId>verifyica-maven-plugin</artifactId>
            <version>1.0.6</version>
            <executions>
                <execution>
                    <goals>
                        <goal>test</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Complete Build Configuration Example:

<build>
    <plugins>
        <!-- Maven Surefire: Exclude Verifyica tests -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.5.2</version>
            <configuration>
                <excludes>
                    <!-- Exclude Verifyica tests ... this should match standard JUnit tests -->
                    <exclude>**/*</exclude>
                </excludes>
            </configuration>
        </plugin>

        <!-- Verifyica Maven Plugin: Run Verifyica tests -->
        <plugin>
            <groupId>org.verifyica</groupId>
            <artifactId>verifyica-maven-plugin</artifactId>
            <version>1.0.6</version>
            <executions>
                <execution>
                    <goals>
                        <goal>test</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Verifying Installation

After adding the dependencies, verify the installation by running:

mvn clean test

If you don’t have any tests yet, the build should succeed with “No tests found” or similar output.

IDE Support

Verifyica tests work with any IDE that supports JUnit Platform:

IntelliJ IDEA

Automatic: IntelliJ IDEA 2017.3+ automatically detects JUnit Platform tests
Run tests by clicking the green arrow next to test classes or methods
View test results in the integrated test runner

Eclipse

Requires: Eclipse 4.7+ with JUnit 5 support
Install the “JUnit 5” feature if not already present
Run tests using “Run As > JUnit Test”

Visual Studio Code

Extension: Install the “Test Runner for Java” extension
Tests appear in the Test Explorer sidebar
Run tests by clicking the play button

Dependencies and Plugins Overview

Dependencies

Artifact	Purpose	Scope
`verifyica-api`	Annotations and API classes	compile
`verifyica-engine`	TestEngine implementation	test

Plugins

Plugin	Purpose	Phase
`verifyica-maven-plugin`	Runs Verifyica tests	test
`maven-surefire-plugin`	Configured to exclude Verifyica tests	test

Version Compatibility

Verifyica Version	Java Version
1.0.6	8+

Next Steps

Now that Verifyica is installed, proceed to:

Quick Start - Write your first test
First Test - Understand test structure in depth

2 - Quick Start

Write and run your first Verifyica test in 5 minutes. Beginner-friendly guide for Java developers.

This guide will walk you through creating and running your first Verifyica test.

Your First Test

Create a new test class with the following code:

package com.example.tests;

import java.util.ArrayList;
import java.util.Collection;
import org.verifyica.api.Verifyica;

public class MyFirstTest {

    // Arguments are tested in parallel by default
    @Verifyica.ArgumentSupplier
    public static Object arguments() {
        Collection<String> collection = new ArrayList<>();
        for (int i = 0; i < 5; i++) {
            collection.add("argument-" + i);
        }
        return collection;
    }

    @Verifyica.BeforeAll
    public void beforeAll(String argument) {
        System.out.println("Setting up for: " + argument);
    }

    @Verifyica.Test
    public void testWithArgument(String argument) {
        System.out.println("Testing with: " + argument);
        assert argument != null;
        assert argument.startsWith("argument-");
    }

    @Verifyica.AfterAll
    public void afterAll(String argument) {
        System.out.println("Cleaning up: " + argument);
    }
}

Understanding the Test

Let’s break down what’s happening:

1. Argument Supplier

@Verifyica.ArgumentSupplier
public static Object arguments() {
    Collection<String> collection = new ArrayList<>();
    for (int i = 0; i < 5; i++) {
        collection.add("argument-" + i);
    }
    return collection;
}

The @ArgumentSupplier method provides the test arguments. This method:

Must be static
Returns a Collection, array, Stream, or Argument<T> instances
Is called once before test execution begins

2. Test Method

@Verifyica.Test
public void testWithArgument(String argument) {
    System.out.println("Testing with: " + argument);
    assert argument != null;
    assert argument.startsWith("argument-");
}

The @Test method:

Executes once for each argument (5 times in this example)
Receives the current argument as a parameter
Contains your test logic

3. Lifecycle Methods

@Verifyica.BeforeAll
public void beforeAll(String argument) {
    System.out.println("Setting up for: " + argument);
}

@Verifyica.AfterAll
public void afterAll(String argument) {
    System.out.println("Cleaning up: " + argument);
}

@BeforeAll runs once before all tests for each argument
@AfterAll runs once after all tests for each argument

Running the Test

Using Maven

mvn test

Using Your IDE

Run the test class directly from your IDE by:

Right-clicking the class and selecting “Run”
Clicking the green arrow next to the class name

Test Output

When you run the test, you’ll see output like:

Setting up for: argument-0
Testing with: argument-0
Cleaning up: argument-0
Setting up for: argument-1
Testing with: argument-1
Cleaning up: argument-1
... (continues for all 5 arguments)

The test method runs 5 times (once per argument), and each execution has its own setup and cleanup.

Controlling Parallelism

Want to control argument test parallelism? Add parallelism to the argument supplier:

@Verifyica.ArgumentSupplier(parallelism = 2)
public static Object arguments() {
    Collection<String> collection = new ArrayList<>();
    for (int i = 0; i < 10; i++) {
        collection.add("argument-" + i);
    }
    return collection;
}

Now only 2 arguments will execute in parallel.

Complete Example with All Lifecycle Methods

Here’s a more complete example showing the full lifecycle:

package com.example.tests;

import java.util.ArrayList;
import java.util.Collection;

import org.verifyica.api.ClassContext;
import org.verifyica.api.Verifyica;

public class CompleteLifecycleTest {

    @Verifyica.ArgumentSupplier(parallelism = 2)
    public static Object arguments() {
        Collection<String> collection = new ArrayList<>();
        for (int i = 0; i < 10; i++) {
            collection.add("string-" + i);
        }
        return collection;
    }

    @Verifyica.Prepare
    public void prepare(ClassContext classContext) {
        System.out.println("Prepare: Called once before all arguments");
    }

    @Verifyica.BeforeAll
    public void beforeAll(String argument) {
        System.out.println("BeforeAll: " + argument);
    }

    @Verifyica.BeforeEach
    public void beforeEach(String argument) {
        System.out.println("BeforeEach: " + argument);
    }

    @Verifyica.Test
    public void test1(String argument) {
        System.out.println("Test1: " + argument);
    }

    @Verifyica.Test
    public void test2(String argument) {
        System.out.println("Test2: " + argument);
    }

    @Verifyica.AfterEach
    public void afterEach(String argument) {
        System.out.println("AfterEach: " + argument);
    }

    @Verifyica.AfterAll
    public void afterAll(String argument) {
        System.out.println("AfterAll: " + argument);
    }

    @Verifyica.Conclude
    public void conclude(ClassContext classContext) {
        System.out.println("Conclude: Called once after all arguments");
    }
}

Execution Flow

For each argument, the lifecycle is:

@Prepare (once for all arguments)
For each argument:
- @BeforeAll (once per argument)
- For each @Test method:
  - @BeforeEach
  - @Test
  - @AfterEach
- @AfterAll (once per argument)
@Conclude (once for all arguments)

With 10 arguments and 2 test methods, this test will execute:

1 Prepare
10 BeforeAll
20 BeforeEach (10 arguments × 2 tests)
20 Test executions
20 AfterEach
10 AfterAll
1 Conclude

Common Patterns

Testing with Different Types

Arguments can be any type:

@Verifyica.ArgumentSupplier
public static Object arguments() {
    return Arrays.asList(
        Argument.of("test1", new DatabaseConfig("localhost", 5432)),
        Argument.of("test2", new DatabaseConfig("prod", 5432))
    );
}

@Verifyica.Test
public void testDatabase(DatabaseConfig config) {
    // Test with config
}

Conditional Execution

Skip tests conditionally:

@Verifyica.Test
public void conditionalTest(String argument) {
    if (argument.equals("skip-me")) {
        throw new TestSkippedException("Skipping this argument");
    }
    // Test logic
}

Next Steps

Now that you’ve created your first test, learn more about:

First Test Deep Dive - Understand test structure in detail
Core Concepts - Learn about Arguments, Lifecycle, and more
Configuration - Configure parallelism and filters
Examples - See more complex examples

3 - Your First Test

Deep dive into creating and understanding Verifyica tests

This guide provides a comprehensive walkthrough of creating Verifyica tests, explaining each component in detail.

Test Class Structure

A Verifyica test class is a plain Java class with annotated methods. Unlike JUnit Jupiter tests that use @Test on every test method, Verifyica tests use several annotations to define the complete lifecycle.

Basic Structure

package com.example.tests;

import java.util.ArrayList;
import java.util.Collection;
import org.verifyica.api.Verifyica;
import org.verifyica.api.ClassContext;

public class MyFirstTest {

  // Arguments are tested in parallel by default
  @Verifyica.ArgumentSupplier
  public static Object arguments() {
    Collection<String> collection = new ArrayList<>();
    for (int i = 0; i < 5; i++) {
      collection.add("argument-" + i);
    }
    return collection;
  }

  /**
   * The actual test.
   */
  @Verifyica.Test
  public void testWithArgument(String argument) {
    System.out.println("Testing with: " + argument);
    assert argument != null;
    assert argument.startsWith("argument-");
  }
}

Required Elements

A minimal Verifyica test requires:

One @ArgumentSupplier method - Provides test arguments
At least one @Test method - Contains test logic

The Argument Supplier

The argument supplier is the heart of Verifyica tests. It provides the data that drives your tests.

Method Signature

@Verifyica.ArgumentSupplier
public static Object arguments() {
    // Return Collection, array, Stream, or Argument<T>
}

Requirements:

Must be static
Must be public
Return type must be one of:
- Collection<?> (most common)
- Array (e.g., String[], Object[])
- Stream<?> (for large datasets)
- Iterable<?> (for large datasets)
- Single or multiple Argument<T> objects

Return Type Examples

Collection (Recommended)

@Verifyica.ArgumentSupplier
public static Collection<String> arguments() {
    return Arrays.asList("test1", "test2", "test3");
}

Array

@Verifyica.ArgumentSupplier
public static String[] arguments() {
    return new String[] {"test1", "test2", "test3"};
}

Stream (for large datasets)

@Verifyica.ArgumentSupplier
public static Stream<Integer> arguments() {
    return IntStream.range(0, 1000).boxed();
}

Argument<T> Objects

@Verifyica.ArgumentSupplier
public static Collection<Argument<String>> arguments() {
    return Arrays.asList(
        Argument.of("test-1", "value1"),
        Argument.of("test-2", "value2")
    );
}

The Argument<T> interface provides:

Named arguments (first parameter is the display name)
Type safety
Better test reporting

Parallelism Configuration

Control how many arguments execute in parallel:

@Verifyica.ArgumentSupplier(parallelism = 4)
public static Collection<String> arguments() {
    return generateArguments();
}

parallelism = 1 (default) - Sequential execution
parallelism = 2+ - Number of arguments executing concurrently

Test Lifecycle Annotations

Verifyica provides a complete lifecycle for each argument.

Complete Lifecycle

package com.example.tests;

import java.util.ArrayList;
import java.util.Collection;

import org.verifyica.api.ClassContext;
import org.verifyica.api.Verifyica;

public class CompleteLifecycleTest {

    @Verifyica.ArgumentSupplier(parallelism = 2)
    public static Object arguments() {
      Collection<String> collection = new ArrayList<>();
      for (int i = 0; i < 10; i++) {
        collection.add("string-" + i);
      }
      return collection;
    }

    @Verifyica.Prepare
    public void prepare(ClassContext classContext) {
        System.out.println("Prepare: Called once before all arguments");
    }

    @Verifyica.BeforeAll
    public void beforeAll(String argument) {
        System.out.println("BeforeAll: " + argument);
    }

    @Verifyica.BeforeEach
    public void beforeEach(String argument) {
        System.out.println("BeforeEach: " + argument);
    }

    @Verifyica.Test
    public void test1(String argument) {
        System.out.println("Test1: " + argument);
    }

    @Verifyica.Test
    public void test2(String argument) {
        System.out.println("Test2: " + argument);
    }

    @Verifyica.AfterEach
    public void afterEach(String argument) {
        System.out.println("AfterEach: " + argument);
    }

    @Verifyica.AfterAll
    public void afterAll(String argument) {
        System.out.println("AfterAll: " + argument);
    }

    @Verifyica.Conclude
    public void conclude(ClassContext classContext) {
        System.out.println("Conclude: Called once after all arguments");
    }
}

Lifecycle Execution Order

For 3 arguments and 2 test methods:

1. Prepare (once)
2. For argument-1:
   - BeforeAll
   - BeforeEach → Test1 → AfterEach
   - BeforeEach → Test2 → AfterEach
   - AfterAll
3. For argument-2:
   - BeforeAll
   - BeforeEach → Test1 → AfterEach
   - BeforeEach → Test2 → AfterEach
   - AfterAll
4. For argument-3:
   - BeforeAll
   - BeforeEach → Test1 → AfterEach
   - BeforeEach → Test2 → AfterEach
   - AfterAll
5. Conclude (once)

Method Parameters

Lifecycle methods can accept the current argument:

@Verifyica.BeforeAll
public void beforeAll(String argument) {
    // Receives current argument
}

@Verifyica.Test
public void test(String argument) {
    // Receives current argument
}

Methods without the current argument as a parameter:

@Prepare - No argument (called before argument processing)
@Conclude - No argument (called after all arguments)

Methods that can optionally receive the argument:

@BeforeAll, @BeforeEach, @Test, @AfterEach, @AfterAll

Writing Test Methods

Test methods contain your actual test logic.

Basic Test Method

@Verifyica.Test
public void testSomething(String argument) {
    // Arrange
    Service service = new Service(argument);

    // Act
    Result result = service.process();

    // Assert
    assert result.isSuccess();
}

Multiple Test Methods

You can have multiple @Test methods in a class:

@Verifyica.Test
public void testCreation(Config config) {
    Service service = new Service(config);
    assert service != null;
}

@Verifyica.Test
public void testProcessing(Config config) {
    Service service = new Service(config);
    Result result = service.process();
    assert result.isSuccess();
}

Each test method runs for every argument with its own @BeforeEach and @AfterEach.

Using Assertions

You can use any assertion library:

Standard Java Assertions

@Verifyica.Test
public void test(String argument) {
    assert argument != null;
    assert argument.length() > 0;
}

JUnit Jupiter Assertions

import static org.junit.jupiter.api.Assertions.*;

@Verifyica.Test
public void test(String argument) {
    assertNotNull(argument);
    assertTrue(argument.length() > 0);
}

AssertJ

import static org.assertj.core.api.Assertions.*;

@Verifyica.Test
public void test(String argument) {
    assertThat(argument).isNotNull().isNotEmpty();
}

Real-World Example

Here’s a complete example testing a database with multiple configurations:

package com.example.tests;

import org.verifyica.api.Argument;
import org.verifyica.api.Verifyica;
import java.util.Arrays;
import java.util.Collection;

public class DatabaseTest {

    // Define a context class to encapsulate per-argument state
    public static class TestContext {
        private final DatabaseConnection connection;

        public TestContext(DatabaseConnection connection) {
            this.connection = connection;
        }

        public DatabaseConnection getConnection() {
            return connection;
        }
    }

    @Verifyica.ArgumentSupplier(parallelism = 2)
    public static Collection<Argument<DatabaseConfig>> arguments() {
        return Arrays.asList(
            Argument.of("h2-memory", new DatabaseConfig("jdbc:h2:mem:test")),
            Argument.of("h2-file", new DatabaseConfig("jdbc:h2:file:./testdb")),
            Argument.of("postgresql", new DatabaseConfig("jdbc:postgresql://localhost/test"))
        );
    }

    @Verifyica.BeforeAll
    public void beforeAll(ArgumentContext argumentContext) {
        DatabaseConfig config = argumentContext.getArgument().getPayloadAs(DatabaseConfig.class);

        DatabaseConnection connection = new DatabaseConnection(config);
        connection.connect();
        connection.createSchema();

        // Store context in ArgumentContext map (thread-safe)
        TestContext context = new TestContext(connection);
        argumentContext.getMap().put("testContext", context);
    }

    @Verifyica.BeforeEach
    public void beforeEach(ArgumentContext argumentContext) {
        TestContext context = (TestContext) argumentContext.getMap().get("testContext");
        context.getConnection().clearData();
    }

    @Verifyica.Test
    public void testInsert(ArgumentContext argumentContext) {
        TestContext context = (TestContext) argumentContext.getMap().get("testContext");
        DatabaseConnection connection = context.getConnection();

        connection.insert("users", Map.of("id", 1, "name", "Alice"));
        List<User> users = connection.query("SELECT * FROM users");
        assert users.size() == 1;
        assert users.get(0).getName().equals("Alice");
    }

    @Verifyica.Test
    public void testUpdate(ArgumentContext argumentContext) {
        TestContext context = (TestContext) argumentContext.getMap().get("testContext");
        DatabaseConnection connection = context.getConnection();

        connection.insert("users", Map.of("id", 1, "name", "Alice"));
        connection.update("users", Map.of("name", "Bob"), "id = 1");
        User user = connection.queryOne("SELECT * FROM users WHERE id = 1");
        assert user.getName().equals("Bob");
    }

    @Verifyica.AfterEach
    public void afterEach(ArgumentContext argumentContext) {
        TestContext context = (TestContext) argumentContext.getMap().get("testContext");
        context.getConnection().clearData();
    }

    @Verifyica.AfterAll
    public void afterAll(ArgumentContext argumentContext) {
        TestContext context = (TestContext) argumentContext.getMap().get("testContext");
        if (context != null && context.getConnection() != null) {
            context.getConnection().dropSchema();
            context.getConnection().disconnect();
        }
    }
}

This test:

Runs against 3 different database configurations
Executes 2 arguments in parallel
Has 2 test methods that run for each configuration
Total test executions: 6 (3 configs × 2 tests)
Properly manages connection lifecycle per configuration

Common Patterns

Skipping Arguments Conditionally

@Verifyica.BeforeAll
public void beforeAll(String argument) {
    if (shouldSkip(argument)) {
        throw new TestSkippedException("Skipping: " + argument);
    }
}

Use instance variables (lifecycle methods run for the same argument sequentially):

public class StatefulTest {

    private Service service;

    @Verifyica.BeforeAll
    public void beforeAll(Config config) {
        service = new Service(config);
    }

    @Verifyica.Test
    public void test1(Config config) {
        service.doSomething();
    }

    @Verifyica.Test
    public void test2(Config config) {
        // service is still available from beforeAll
        assert service.getState() == State.READY;
    }
}

Dynamic Argument Generation

@Verifyica.ArgumentSupplier
public static Collection<String> arguments() {
    List<String> args = new ArrayList<>();

    // Read from file
    args.addAll(readConfigsFromFile("configs.txt"));

    // Generate programmatically
    for (int i = 0; i < 10; i++) {
        args.add("generated-" + i);
    }

    // Filter based on environment
    if (System.getenv("RUN_FULL_SUITE") != null) {
        args.addAll(getFullTestSuite());
    }

    return args;
}

Next Steps

Now that you understand the basics, explore:

Core Concepts - Deep dive into Arguments, Lifecycle, and Contexts
Configuration - Configure parallelism and filters
Examples - See more complex patterns
API Reference - Complete annotation reference

Getting Started

Prerequisites

Quick Navigation

What You’ll Learn

Next Steps

1 - Installation

Overview

Maven

Maven Surefire Configuration

Verifyica Maven Plugin (Required)

Verifying Installation

IDE Support

IntelliJ IDEA

Eclipse

Visual Studio Code

Dependencies and Plugins Overview

Dependencies

Plugins

Version Compatibility

Next Steps

2 - Quick Start

Your First Test

Understanding the Test

1. Argument Supplier

2. Test Method

3. Lifecycle Methods

Running the Test

Using Maven

Using Your IDE

Test Output

Controlling Parallelism

Complete Example with All Lifecycle Methods

Execution Flow

Common Patterns

Testing with Different Types

Conditional Execution

Next Steps

3 - Your First Test

Test Class Structure

Basic Structure

Required Elements

The Argument Supplier

Method Signature

Return Type Examples

Collection (Recommended)

Array

Stream (for large datasets)

Argument<T> Objects

Parallelism Configuration

Test Lifecycle Annotations

Complete Lifecycle

Lifecycle Execution Order

Method Parameters

Writing Test Methods

Basic Test Method

Multiple Test Methods

Using Assertions

Standard Java Assertions

JUnit Jupiter Assertions

AssertJ

Real-World Example

Common Patterns

Skipping Arguments Conditionally

Sharing State Between Tests

Dynamic Argument Generation

Next Steps