jqwik-testing

Overview

jqwik is a JVM property-based testing library for Java and Kotlin that integrates with JUnit 5, so property tests run alongside conventional unit tests in the same Maven / Gradle pipeline (jqwik-home (opens in new window)).

When to use

• A JVM project (Java / Kotlin / Scala) tests via JUnit 5 and needs PBT alongside the existing unit tests.
• The team finds JUnit-QuickCheck or Vavr's PBT awkward; jqwik's JUnit 5 integration is more idiomatic.
• Properties hold for parsers / encoders / round-trip transforms.

Step 1 - Install

Maven:

<dependency>
  <groupId>net.jqwik</groupId>
  <artifactId>jqwik</artifactId>
  <version>1.9.3</version>
  <scope>test</scope>
</dependency>

The artifact pulls in the JUnit 5 platform dependency transitively. Version note: references/jqwik-reference.md.

Gradle:

testImplementation 'net.jqwik:jqwik:1.9.3'

test {
    useJUnitPlatform()
}

Step 2 - Basic property

Per jqwik-home (opens in new window):

import net.jqwik.api.*;

class CartProperties {

    @Property
    boolean addingItemIncreasesCount(@ForAll int qty) {
        Cart cart = new Cart();
        cart.addItem(new Item("BOOK-001", qty));
        return cart.itemCount() == qty;
    }
}

The @Property annotation marks a property test (JUnit 5 hooks in via the platform). @ForAll on a parameter means "jqwik generates values for this." The method returns boolean (or void with assertions).

By default jqwik runs each property with 1000 generated cases (more than Hypothesis's 100 or proptest's 256).

Step 3 - Constrained generators

@Property
boolean validQtyStaysInRange(@ForAll @IntRange(min = 1, max = 100) int qty) {
    Cart cart = new Cart();
    cart.addItem(new Item("BOOK-001", qty));
    return cart.itemCount() >= 1 && cart.itemCount() <= 100;
}

Constraint annotations live in net.jqwik.api.constraints.* (@IntRange, @LongRange, @StringLength, @Size, @NotEmpty, @Email, @Positive, ...). Full table: references/jqwik-reference.md.

Step 4 - Custom arbitraries via @Provide

class UserProperties {

    @Property
    boolean userJsonRoundTrip(@ForAll("validUser") User u) {
        String json = mapper.writeValueAsString(u);
        User back = mapper.readValue(json, User.class);
        return u.equals(back);
    }

    @Provide
    Arbitrary<User> validUser() {
        Arbitrary<Long> id = Arbitraries.longs().between(1, 1_000_000);
        Arbitrary<String> email = Arbitraries.strings()
            .alpha().ofMinLength(3).ofMaxLength(10)
            .map(s -> s + "@example.com");
        Arbitrary<Integer> age = Arbitraries.integers().between(18, 100);
        return Combinators.combine(id, email, age).as(User::new);
    }
}

The @Provide method returns an Arbitrary<T>; its name (or the method name when omitted) is referenced from @ForAll("...").

Combinators.combine(...) is the canonical way to assemble a multi-field arbitrary; .as(...) constructs the target object from the parts.

Step 5 - Arbitraries catalog

Per jqwik-home (opens in new window), the Arbitraries API provides built-in generators:

Arbitraries.integers().between(0, 100);            // bounded int
Arbitraries.strings().alpha().ofLength(8);         // fixed-length alpha string
Arbitraries.of(Status.ACTIVE, Status.SUSPENDED);   // enum-like
Arbitraries.integers().list().ofMinSize(1).ofMaxSize(100);   // List<Integer>

Half-bounded generators, sets, maps, and subsetOf: references/jqwik-reference.md.

Step 6 - Statistics + classification

@Property
@Statistics
boolean evenAndOddDistribution(@ForAll int n) {
    Statistics.label("evenness").collect(n % 2 == 0 ? "even" : "odd");
    return true;
}

Statistics output reports the distribution of generated cases - useful for verifying the strategy generates the intended mix.

Step 7 - Configuration

@Property(tries = 5000, shrinking = ShrinkingMode.FULL, edgeCases = EdgeCasesMode.MIXIN)
boolean expensiveProperty(@ForAll long n) {
    // ...
}

For CI determinism:

@Property(seed = "42")
boolean reproducibleProperty(@ForAll int n) { /* ... */ }

Or globally via jqwik.config.properties:

defaultSeed = 42
defaultTries = 1000

Step 8 - CI integration

mvn test                  # runs JUnit 5 tests including @Property
gradle test               # same

No additional config beyond JUnit 5 platform.

References

• references/jqwik-reference.md - constraint annotations, Arbitraries catalog, anti-patterns, limitations, version note.
• jh (opens in new window) - jqwik overview: @Property, @ForAll, @Provide, Arbitraries API, JUnit 5 integration.
• hypothesis-testing, fast-check-testing, proptest-testing, quickcheck-testing - per-language siblings.