Refactoring

Author: jakubmalek

README.md

@@ -1,2 +1,34 @@
-# assertj-async
+# AssertJ - Async
+
 AssertJ extension for making asynchronous assertions.
+
+## Usage
+
+The entry point for making asynchronous assertion is `AsyncAssertions` class.
+
+Here is an example of test:
+```java
+class AsyncAssertionExampleTest
+{
+    @Test
+    void shouldReceiveChangeMessages() {
+        // given
+        var receivedMessages = new ConcurrentLinkedQueue<String>();
+
+        // when
+        listenToChanges(receivedMessages::offer);
+
+        // then
+        awaitAtMostOneSecond().untilAssertions(async -> async
+            .assertThat(receivedMessages).containsExactly("A", "B", "C"));
+    }
+    
+    private static void listenToChanges(Consumer<String> consumer) {
+        // simulation of asynchronous consumer
+        var scheduler = Executors.newSingleThreadScheduledExecutor();
+        scheduler.schedule(() -> consumer.accept("A"), 100L, TimeUnit.MILLISECONDS);
+        scheduler.schedule(() -> consumer.accept("B"), 200L, TimeUnit.MILLISECONDS);
+        scheduler.schedule(() -> consumer.accept("C"), 300L, TimeUnit.MILLISECONDS);
+    }
+}
+```

build.gradle.kts

@@ -1,11 +1,23 @@
+import nebula.plugin.contacts.Contact
+
 plugins {
+    id("org.owasp.dependencycheck") version "7.1.1"
+    id("nebula.release") version "16.0.0"
+    id("nebula.maven-nebula-publish") version "18.4.0"
+    id("nebula.maven-developer") version "18.4.0"
+    id("nebula.maven-scm") version "18.4.0"
+    id("nebula.contacts") version "6.0.0"
+    id("nebula.info-scm") version "11.3.3"
+    id("tylerthrailkill.nebula-mit-license") version "0.0.3"
+
     jacoco
     `java-library`
     `maven-publish`
     `project-report`
 }
 
 java {
+    sourceCompatibility = JavaVersion.VERSION_11
     targetCompatibility = JavaVersion.VERSION_11
 }
 
@@ -16,9 +28,9 @@ repositories {
 dependencies {
     // api
     api("org.assertj", "assertj-core", "[3.23.0,3.24.0[")
-    api("org.opentest4j", "opentest4j", "[1.2.0,1.3.0[")
+    compileOnly("org.opentest4j", "opentest4j", "[1.2.0,1.3.0[")
 
-    // Lombok
+    // lombok
     compileOnly(annotationProcessor("org.projectlombok", "lombok", "[1.18.0,2.0.0["))
     testCompileOnly(testAnnotationProcessor("org.projectlombok", "lombok", "[1.18.0,2.0.0["))
 
@@ -33,32 +45,10 @@ tasks {
     }
 }
 
-publishing {
-    publications {
-        create<MavenPublication>("mavenJava") {
-            pom {
-                description.set("AssertJ extension for making asynchronous assertions")
-                url.set("https://github.com/Webfleet-Solutions/assertj-async")
-                licenses {
-                    license {
-                        name.set("The MIT License")
-                        url.set("https://github.com/Webfleet-Solutions/assertj-async/blob/main/LICENSE")
-                    }
-                }
-                developers {
-                    developer {
-                        id.set("jakubmalek")
-                        name.set("Jakub Malek")
-                        email.set("[email protected]")
-                    }
-                }
-                scm {
-                    url.set("https://github.com/Webfleet-Solutions/assertj-async")
-                }
-                issueManagement {
-                    url.set("https://github.com/Webfleet-Solutions/assertj-async/issues")
-                }
-            }
-        }
-    }
+contacts {
+    addPerson("[email protected]", delegateClosureOf<Contact> {
+        github = "jakubmalek"
+        moniker = "Jakub Małek"
+        role("owner")
+    })
 }

gradle.properties

@@ -1,4 +1,2 @@
-version=1.0
-build=SNAPSHOT
-title=assertj-async
-group=com.webfleet
+group=com.webfleet
+release.scope=major

src/main/java/com/webfleet/assertj/AsyncAssert.java

@@ -0,0 +1,66 @@
+package com.webfleet.assertj;
+
+import java.time.Duration;
+import java.util.concurrent.TimeUnit;
+import java.util.function.Consumer;
+
+import org.assertj.core.api.SoftAssertions;
+
+import lombok.NonNull;
+
+
+/**
+ * Asynchronous assertion.
+ */
+public interface AsyncAssert
+{
+    /**
+     * Awaits until all assertions are passed or timeout is exceeded.
+     * Assertions are configured in lambda consumer of {@link SoftAssertions} object on each check.
+     * The checks are executed periodically with check interval delay configured with {@link AsyncAssert#withWaitInterval} method.
+     * After exceeding timeout {@link AssertionError} will be thrown with failures from last assertion check.
+     *
+     * <pre><code class='java'>
+     * awaitAtMostOneSecond().untilAssertions(async -> {
+     *     async.assertThat(getValue()).isEqualTo(expected);
+     *     async.assertThat(isDone()).isTrue();
+     * });
+     * </code></pre>
+     *
+     * @param assertionsConfiguerer lambda consumer configuring {@link SoftAssertions} object
+     */
+    void untilAssertions(Consumer<SoftAssertions> assertionsConfiguerer);
+
+    /**
+     * Configures assertion to use give mutex object for check interval wait logic.
+     *
+     * In multi-threaded applications, the mutex object can be used to notify the other thread about state change.
+     * For asynchronous assertion, the mutex object can be used to reduce the wait time between checks with {@link Object#notifyAll()} call.
+     *
+     * @param waitMutex mutex object
+     * @return new {@link AsyncAssert} using given wait mutex
+     */
+    AsyncAssert usingWaitMutex(Object waitMutex);
+
+    /**
+     * Configures the interval to be waited between assertions checks.
+     * The interval must be greater than zero and lower than timeout.
+     *
+     * @param checkInterval check interval
+     * @return new {@link AsyncAssert} with set check interval
+     */
+    AsyncAssert withCheckInterval(Duration checkInterval);
+
+    /**
+     * Configures the interval to be waited between assertions checks.
+     * The interval must be greater than zero and lower than timeout.
+     *
+     * @param checkInterval check interval
+     * @param unit the time unit of the check interval
+     * @return new {@link AsyncAssert} with set check interval
+     */
+    default AsyncAssert withWaitInterval(final long checkInterval, @NonNull final TimeUnit unit)
+    {
+        return withCheckInterval(Duration.ofMillis(unit.toMillis(checkInterval)));
+    }
+}

src/main/java/com/webfleet/assertj/AsyncAssertImpl.java

@@ -0,0 +1,58 @@
+package com.webfleet.assertj;
+
+import java.time.Duration;
+import java.util.function.Consumer;
+
+import org.assertj.core.api.SoftAssertions;
+
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.NonNull;
+
+
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+final class AsyncAssertImpl implements AsyncAssert
+{
+    private final Time time;
+    private final AsyncAssertTimeoutCondition timeCondition;
+    private final Object waitMutex;
+
+    AsyncAssertImpl(@NonNull final Time time, @NonNull final AsyncAssertTimeoutCondition timeCondition)
+    {
+        this(time, timeCondition, new Object());
+    }
+
+    @Override
+    public AsyncAssert withCheckInterval(@NonNull final Duration checkInterval)
+    {
+        return new AsyncAssertImpl(time, timeCondition.withCheckInterval(checkInterval), waitMutex);
+    }
+
+    @Override
+    public AsyncAssert usingWaitMutex(@NonNull final Object waitMutex)
+    {
+        return new AsyncAssertImpl(time, timeCondition, waitMutex);
+    }
+
+    @Override
+    public void untilAssertions(@NonNull final Consumer<SoftAssertions> assertionsConfigurer)
+    {
+        final var elapsedTime = time.measure();
+        final var waitCondition = time.waitCondition(waitMutex);
+
+        var result = AsyncAssertResult.undefined();
+        while (result.hasFailed() && elapsedTime.isLowerThanOrEqualTo(timeCondition.timeout()) && !Thread.currentThread().isInterrupted())
+        {
+            result = AsyncAssertResult.evaluate(assertionsConfigurer);
+            if (result.hasFailed())
+            {
+                if (!elapsedTime.isLowerThan(timeCondition.timeout()))
+                {
+                    break;
+                }
+                waitCondition.waitFor(timeCondition.checkInterval(elapsedTime));
+            }
+        }
+        result.throwOnFailure(timeCondition);
+    }
+}

src/main/java/com/webfleet/assertj/AsyncAssertResult.java

@@ -0,0 +1,50 @@
+package com.webfleet.assertj;
+
+import static org.assertj.core.api.Assertions.catchThrowableOfType;
+
+import java.util.function.Consumer;
+
+import org.assertj.core.api.SoftAssertions;
+
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.NonNull;
+
+
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+final class AsyncAssertResult
+{
+    private static final AssertionError UNDEFINED_ERROR = new AssertionError("Failed to evaluate async assertions");
+
+    private final AssertionError error;
+
+    static AsyncAssertResult undefined()
+    {
+        return new AsyncAssertResult(UNDEFINED_ERROR);
+    }
+
+    static AsyncAssertResult evaluate(@NonNull final Consumer<SoftAssertions> assertionConfigurer)
+    {
+        final var assertions = new SoftAssertions();
+        // catching error in case assertAll is called explicitly by the consumer
+        final var caughtError = catchThrowableOfType(() -> assertionConfigurer.accept(assertions), AssertionError.class);
+        if (caughtError != null)
+        {
+            return new AsyncAssertResult(caughtError);
+        }
+        return new AsyncAssertResult(catchThrowableOfType(assertions::assertAll, AssertionError.class));
+    }
+
+    boolean hasFailed()
+    {
+        return error != null;
+    }
+
+    void throwOnFailure(@NonNull final AsyncAssertTimeoutCondition timeCondition)
+    {
+        if (hasFailed())
+        {
+            throw AsyncAssertionErrorCreator.create(timeCondition, error);
+        }
+    }
+}

src/main/java/com/webfleet/assertj/AsyncAssertTimeoutCondition.java

@@ -0,0 +1,77 @@
+package com.webfleet.assertj;
+
+import static java.time.Duration.ZERO;
+
+import java.time.Duration;
+
+import com.webfleet.assertj.Time.ElapsedTime;
+
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.NonNull;
+import lombok.ToString;
+import lombok.experimental.Accessors;
+
+
+@AllArgsConstructor(access = AccessLevel.PRIVATE)
+@Accessors(fluent = true)
+@Getter
+@EqualsAndHashCode
+@ToString
+final class AsyncAssertTimeoutCondition
+{
+    private static final Duration DEFAULT_CHECK_INTERVAL = Duration.ofMillis(100L);
+    private static final Duration DEFAULT_SHORT_CHECK_INTERVAL = Duration.ofMillis(50L);
+
+    private final Duration timeout;
+    private final Duration checkInterval;
+
+    static AsyncAssertTimeoutCondition withTimeout(@NonNull final Duration timeout)
+    {
+        if (timeout.compareTo(ZERO) <= 0)
+        {
+            throw new IllegalArgumentException("timeout must be greater than zero");
+        }
+        final var checkInterval = computeCheckInterval(timeout);
+        return new AsyncAssertTimeoutCondition(timeout, checkInterval);
+    }
+
+    AsyncAssertTimeoutCondition withCheckInterval(@NonNull final Duration checkInterval)
+    {
+        if (checkInterval.compareTo(ZERO) <= 0)
+        {
+            throw new IllegalArgumentException("checkInterval must be greater than zero");
+        }
+        if (checkInterval.compareTo(timeout) > 0)
+        {
+            throw new IllegalArgumentException("checkInterval must be lower than or equal to timeout");
+        }
+        return new AsyncAssertTimeoutCondition(timeout, checkInterval);
+    }
+
+    Duration checkInterval(@NonNull final ElapsedTime elapsedTime)
+    {
+        final var elaspsedDuration = elapsedTime.get();
+        if (elaspsedDuration.plus(checkInterval).compareTo(timeout) > 0)
+        {
+            final var shortenedCheckInterval = timeout.minus(elaspsedDuration);
+            return shortenedCheckInterval.isNegative() ? Duration.ZERO : shortenedCheckInterval;
+        }
+        return checkInterval;
+    }
+
+    private static Duration computeCheckInterval(final Duration timeout)
+    {
+        if (DEFAULT_CHECK_INTERVAL.compareTo(timeout) >= 0)
+        {
+            if (timeout.compareTo(DEFAULT_SHORT_CHECK_INTERVAL) > 0)
+            {
+                return DEFAULT_SHORT_CHECK_INTERVAL;
+            }
+            return timeout;
+        }
+        return DEFAULT_CHECK_INTERVAL;
+    }
+}