```java
AtomicInteger atomic = new AtomicInteger(0);
// Do some async stuff that eventually updates the atomic integer
await().untilAtomic(atomic, equalTo(1));
```
等待一個 AtomicBoolean 更簡單:
```java
AtomicBoolean atomic = new AtomicBoolean(false);
// Do some async stuff that eventually updates the atomic boolean
await().untilTrue(atomic);
```
如果您正在使用 Adders,例如 [LongAdder](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/LongAdder.html),則Awaitility 可讓您簡單地等待使其達到一定的值:
```java
await().untilAdder(myLongAdder, equalTo(5L))
```
同樣,如果使用累加器,例如 [LongAccumulator](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/LongAccumulator.html),則可以執行以下操作:
```java
await().untilAccumulator(myLongAccumulator, equalTo(5L))
```
##Advanced
使用100毫秒的輪詢間隔,初始延遲為20毫秒,直到客戶狀態等于 “REGISTERED”。本示例還通過指定別名(“customer registration”)來使用命名的 await。如果您在同一測試中有多個 await,那么很容易找出哪個等待語句失敗。
```java
with().pollInterval(ONE_HUNDERED_MILLISECONDS).and().with().pollDelay(20, MILLISECONDS).await("customer registration").until(
customerStatus(), equalTo(REGISTERED));
```
您還可以指定這樣的別名:
```java
await().with().alias("my alias"). ..
```
要使用非固定的輪詢間隔,請參考 [輪詢間隔](#polling)文檔。
##Lambdas
您可以在條件中使用 lambda 表達式:
```java
await().atMost(5, SECONDS).until(() -> userRepository.size() == 1);
```
或方法引用:
```java
await().atMost(5, SECONDS).until(userRepository::isNotEmpty);
```
或方法引用和 Hamcrest 匹配器的組合:
```java
await().atMost(5, SECONDS).until(userRepository::size, is(1));
```
您還可以使用謂詞:
```java
await().atMost(5, SECONDS).until(userRepository::size, size -> size == 1);
```
有關示例,請參閱 [Jayway小組博客](http://www.jayway.com/2014/04/23/java-8-and-assertj-support-in-awaitility-1-6-0/")。
##Using AssertJ or Fest Assert
您可以使用 [AssertJ](http://joel-costigliola.github.io/assertj/)或 [Fest Assert](https://code.google.com/p/fest/) 代替 Hamcrest(實際上可以使用任何在出錯時引發異常的第三方庫)。
```java
await().atMost(5, SECONDS).untilAsserted(() -> assertThat(fakeRepository.getValue()).isEqualTo(1));
```
##Ignoring Exceptions
在條件評估期間忽略某些類型的異常有時很有用。例如,如果您在等待到達最終狀態之前正在等待將異常作為中間狀態拋出的事件。以Spring的 [SocketUtils](http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/util/SocketUtils.html) 類為例,該類使您可以在給定范圍查找 TCP 端口。如果在給定范圍內沒有端口可用,它將拋出異常。假設我們知道給定范圍內的某些端口不可用,但我們要等待它們可用。這是一個示例,我們可以選擇忽略“SocketUtils”引發的任何異常。例如:
```java
given().ignoreExceptions().await().until(() -> SocketUtils.findAvailableTcpPort(x,y));
```
這指示 Awaitility 在條件評估期間忽略所有捕獲的異常。異常將被視為評估失敗。與提供的異常類型匹配的異常,測試不會失敗(除非超時)。您還可以忽略特定的異常:
```java
given().ignoreException(IllegalStateException.class).await().until(() -> SocketUtils.findAvailableTcpPort(x,y));
```
或使用 Hamcrest 匹配器:
```java
given().ignoreExceptionsMatching(instanceOf(RuntimeException.class)).await().until(() -> SocketUtils.findAvailableTcpPort(x,y));
```
或使用謂詞(Java 8):
```java
given().ignoreExceptionsMatching(e -> e.getMessage().startsWith("Could not find an available")).await().until(something());
```
您也可以忽略 `Throwable` 實例。
##Checked exceptions in Runnable lambda expressions
Java中的 `Runnable` 接口不允許您拋出已檢查的異常。因此,如果您有這樣的方法:
```java
public void waitUntilCompleted() throws Exception { ... }
```
可能會引發異常,如果 `untilAsserted` 將 `Runnable` 作為其參數值,則您必須捕獲該異常:
```java
await().untilAsserted(() -> {
try {
waitUntilCompleted();
} catch(Exception e) {
// Handle exception
}
});
```
幸運的是,Awaitility 通過引入傳遞給 `untilAsserted` 的 [ThrowingRunnable](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/core/ThrowingRunnable.html) 接口來解決此問題。而不是 `Runnable`。因此,您需要編寫的代碼如下所示:
```java
await().untilAsserted(() -> waitUntilCompleted());
```
##At Least
您可以指定 awaitility **最少** 等待一定時間。例如:
```java
await().atLeast(1, SECONDS).and().atMost(2, SECONDS).until(value(), equalTo(1));
```
如果在由 atLeast 指定的持續時間之前滿足條件,則會引發異常,條件不應早于指定的時間完成。
###Ignoring uncaught exceptions
如果要將代碼從使用 `Thread.sleep` 遷移到 Awaitility,請注意,在某些情況下,由于其他線程拋出異常,因此 Awaitility 測試用例可能會失敗。這是因為默認情況下,Awaitility 捕獲所有未捕獲的異常。因此,如果您以前使用過 `Thread.sleep`,那么很有可能您沒有捕獲其他線程的異常。如果您對此行為感到滿意,并且不希望 Awaitility 捕獲這些異常,則可以使用 `dontCatchUncaughtExceptions` 禁用此功能:
```java
@Test
public void dontCatchUncaughtExample() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setMaxPoolSize(1);
executor.afterPropertiesSet();
executor.execute(new ErrorTestTask());
ListenableFuture> future = executor.submitListenable(new ErrorTestTask());
Awaitility.await()
.dontCatchUncaughtExceptions()
.atMost(1, TimeUnit.SECONDS)
.pollInterval(10, TimeUnit.MILLISECONDS)
.until(future::isDone);
}
private static class ErrorTestTask implements Runnable {
@Override
public void run() {
try {
Thread.sleep(100);
} catch (InterruptedException e) {
e.printStackTrace();
}
throw new RuntimeException(Thread.currentThread().getName() + " -> Error");
}
}
```
###Assert that a value is maintained
從4.0.2版開始,可以斷言某個值在特定時間段內得到維護。例如,如果您需要確保存儲庫中的值在 1500毫秒中的 800毫秒內保持特定值:
```java
await().during(800, MILLISECONDS).atMost(1500, MILLISECONDS).until(() -> myRepository.findById("id"), equalTo("something"));
```
Awaitility 將最多等待1500毫秒,而這樣做的話,`myRepository.findById(id)` 必須等于 `something` 至少 800毫秒。
##Thread Handling
Awaitility 允許進行細粒度的線程配置。這是通過提供 Awaility 輪詢條件時將使用的線程提供者或 `ExecutorService` 來完成的。請注意,這是一項高級功能,應謹慎使用。例如:
```java
given().pollThread(Thread::new).await().atMost(1000, MILLISECONDS).until(..);
```
另一種方法是指定 `ExecutorService`:
```java
ExecutorSerivce es = ...
given().pollExecutorService(es).await().atMost(1000, MILLISECONDS).until(..);
```
例如,如果您需要等待輪詢 [ThreadLocal](https://docs.oracle.com/javase/7/docs/api/java/lang/ThreadLocal.html) 變量的條件,這將很有用。
在某些情況下,重要的是能夠指示 Awaitility 使用與啟動 Awaitility 的測試用例相同的線程。因此,Awaitility 3.0.0 引入了 [pollInSameThread](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/core/ConditionFactory.html#pollInSameThread--) 方法:
```java
with().pollInSameThread().await().atMost(1000, MILLISECONDS).until(...);
```
這是一項高級功能,在將 `pollInSameThread` 與永遠等待(或長時間)的條件結合使用時應格外小心,因為當 Awaitility 使用與測試相同的線程時,它不會中斷該線程。
## Exception handling
默認情況下,Awaitility 捕獲所有線程中未捕獲的 `Throwable`,并將其傳播到等待線程。這意味著您的測試用例將指示失敗,即使不是引發未捕獲異常的測試線程也是如此。
您可以選擇忽略某些異常或可拋出對象,請參見 [here](#ignoring-exceptions)。
如果不需要在所有線程中都捕獲異常,則可以使用 [dontCatchUncaughtExceptions](#ignoring-uncaught-exceptions)。
## Deadlock detection
Awaitility自動檢測死鎖,并將 [ConditionTimeoutException](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/core/ConditionTimeoutException.html) 的原因與 [DeadlockException](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/core/DeadlockException.html)。 `DeadlockException` 包含有關導致死鎖的線程的信息。
## Defaults
如果未指定任何超時,則 Awaitility 將等待10秒鐘,然后引發 [ConditionTimeoutException](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/core/ConditionTimeoutException.html)(如果條件尚未滿足)。默認輪詢間隔和輪詢延遲為100毫秒。您還可以自己使用以下命令指定默認值:
```java
Awaitility.setDefaultTimeout(..)
Awaitility.setDefaultPollInterval(..)
Awaitility.setDefaultPollDelay(..)
```
您還可以使用 `Awaitility.reset` 將其重置為默認值。
## Polling
請注意,由于 Awaitility 使用輪詢來驗證條件是否匹配,因此不建議將其用于精確的性能測試。在這些情況下,最好使用 AOP 框架,例如 AspectJ。
另請注意,[Duration.ZERO](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/Duration.html#ZERO) 用作所有非固定輪詢間隔的起始值間隔。對于固定的輪詢間隔,出于向后兼容的原因,輪詢延遲等于 `FixedPollInterval` 的持續時間。
有關其他詳細信息,請參見 [this blog](http://code.haleby.se/2015/11/27/non-fixed-poll-intervals-in-awaitility/)。
## Fixed Poll Interval
這是 Awaitilty 的默認輪詢間隔機制。以正常方式使用DSL時,例如:
```java
with().pollDelay(100, MILLISECONDS).and().pollInterval(200, MILLISECONDS).await().until();
```
Awaitility 將使用 [FixedPollInterval](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/pollinterval/FixedPollInterval.html)。這意味著 Awaitility 將在 poll delay(輪詢開始之前的初始延遲,在上面的示例中為100ms)之后首次檢查是否滿足指定條件。除非明確指定,否則 Awaitility 將使用與輪詢間隔相同的輪詢延遲(請注意,這僅適用于固定輪詢間隔,如上例所示)。這意味著它將首先在給定的輪詢延遲后定期檢查條件,然后再以給定的輪詢間隔進行檢查;那就是在 pollDelay 之后檢查條件,然后pollDelay + pollInterval,然后pollDelay +(2 *pollInterval),依此類推。如果更改輪詢間隔,則輪詢延遲也將更改為與指定的輪詢間隔相匹配,除非您已明確指定了輪詢延遲。
## Fibonacci Poll Interval
[FibonacciPollInterval](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/pollinterval/FibonacciPollInterval.html) 會根據斐波那契序列生成一個非線性輪詢間隔。用法示例:
```java
with().pollInterval(fibonacci()).await().until(..);
```
其中的 `fibonacci()`是從 `org.awaitility.pollinterval.FibonacciPollInterval` 靜態導入的。這將生成一個 "1、2、3、5、8、13,..." 毫秒的輪詢間隔。您可以配置要使用的時間單位,例如秒而不是毫秒:
```java
with().pollInterval(fibonacci(TimeUnit.SECONDS)).await().until(..);
```
或使用 english-like 的配置方式
```java
with().pollInterval(fibonacci().with().timeUnit(SECONDS).and().offset(5)).await().until(..);
```
偏移量表示斐波那契序列從該偏移量開始(默認情況下,偏移量為0)。偏移量也可以是負數(-1)以0開頭(`fib(0)`= 0)。
## Iterative Poll Interval
由函數和開始持續時間生成的輪詢間隔。該函數可以在持續時間內自由地執行任何操作。
例如:
```java
await().with().pollInterval(iterative(duration -> duration.multiply(2)), Duration.FIVE_HUNDRED_MILLISECONDS).until(..);
```
或使用 english-like 的配置方式
```java
await().with().pollInterval(iterative(duration -> duration.multiply(2)).with().startDuration(FIVE_HUNDRED_MILLISECONDS)).until(..);
```
這將生成一個輪詢間隔序列,看起來像這樣(ms):`500,1000,2000,4000,8000,16000,...`
請注意,如果指定輪詢初始延遲,則此延遲將在此輪詢間隔生成第一個輪詢間隔之前。有關更多信息,請參見[javadoc](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/pollinterval/IterativePollInterval.html)。
## Custom Poll Interval
通過實現 [PollInterval](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/pollinterval/PollInterval.html) 接口,可以滾動自己的輪詢間隔。這是一個功能接口,因此在Java 8中,您可以像這樣進行操作:
```java
await().with().pollInterval((__, previous) -> previous.multiply(2).plus(1)).until(..);
```
在此示例中,我們創建一個`PollInterval`,該函數被實現為(bi-)函數,該函數采用先前的輪詢間隔持續時間并將其乘以2并加1。`__` 只是表示我們不在乎 [PollInterval](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/pollinterval/PollInterval.html) 提供的輪詢計數。當創建的輪詢間隔不是(僅)對前一個持續時間感興趣,而是根據其被調用的次數生成其持續時間時,需要輪詢計數。例如,[FibonacciPollInterval](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/pollinterval/FibonacciPollInterval.html) 僅使用輪詢計數:
```java
await().with().pollInterval((pollCount, __) -> new Duration(fib(pollCount), MILLISECONDS)).until(..);
```
在大多數情況下,沒有必要從頭開始實施輪詢間隔。改為向 [IterativePollInterval](#iterative-poll-interval) 提供函數。
## Condition Evaluation Listener
Awaitility 1.6.1引入了 [Condition Evaluation Listener](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/core/ConditionEvaluationListener.html) 的概念。每當 Awaitility 評估條件時,都可以使用它來獲取信息。例如,您可以使用它來在條件滿足之前獲取條件的中間值。它也可以用于打印日志。例如:
```java
with().
conditionEvaluationListener(condition -> System.out.printf("%s (elapsed time %dms, remaining time %dms)\n", condition.getDescription(), condition.getElapsedTimeInMS(), condition.getRemainingTimeInMS())).
await().atMost(Duration.TEN_SECONDS).until(new CountDown(5), is(equalTo(0)));
```
將以下內容打印到控制臺:
```java
org.awaitility.AwaitilityJava8Test$CountDown expected (<0> or a value less than <0>) but was <5> (elapsed time 101ms, remaining time 1899ms)
org.awaitility.AwaitilityJava8Test$CountDown expected (<0> or a value less than <0>) but was <4> (elapsed time 204ms, remaining time 1796ms)
org.awaitility.AwaitilityJava8Test$CountDown expected (<0> or a value less than <0>) but was <3> (elapsed time 306ms, remaining time 1694ms)
org.awaitility.AwaitilityJava8Test$CountDown expected (<0> or a value less than <0>) but was <2> (elapsed time 407ms, remaining time 1593ms)
org.awaitility.AwaitilityJava8Test$CountDown expected (<0> or a value less than <0>) but was <1> (elapsed time 508ms, remaining time 1492ms)
org.awaitility.AwaitilityJava8Test$CountDown reached its end value of (<0> or a value less than <0>) (elapsed time 610ms, remaining time 1390ms)
```
有一個內置的用于記錄日志的 ConditionEvaluationListener,名為 [ConditionEvaluationLogger](http://static.javadoc.io/org.awaitility/awaitility/4.0.2/org/awaitility/core/ConditionEvaluationLogger.html) 可以像這樣使用:
```java
with().conditionEvaluationListener(new ConditionEvaluationLogger()).await(). ...
```
Awaitility 4.0.2在 `ConditionEvaluationListener` 接口中引入了三個新的 hook(默認方法):
| Method | Description |
| ------------------ |-------------|
| `beforeEvaluation` | 在條件評估之前調用 |
| `exceptionIgnored` | 處理條件評估時引發的被忽略異常 |
| `onTimeout` | 當條件超時時調用 |
## Duration
Awaitility提供了一個 [Duration](http://static.javadoc.io/org.awaitility/awaitility/1.6.5/org/awaitility/Duration.html) 類,其中包含一些預定義的持續時間值,例如 `ONE_HUNDRED_MILLISECONDS`,`FIVE_SECONDS` 和 `ONE_MINUTE`。您還可以在 `Duration` 實例上執行一些基本的數學運算。例如:
```java
new Duration(5, SECONDS).plus(17, MILLISECONDS);
```
它將返回新的持續時間5017毫秒。請注意,持續時間是不可變的,因此調用 `plus` 將返回一個新實例。當使用非固定的 [輪詢間隔](#polling) 時這個比較有用。
## Important