[docs] Describe the allowUnawaitedPromise assertion option (#2355)

* Describe the allowUnawaitedPromise assertion option

* Fix broken links

* Address remarks

* Update README.md

* Update README.md

docs/articles/documentation/test-api/assertions/README.md

@@ -6,17 +6,18 @@ checked: false
 ---
 # Assertions
 
-You can use *assertions* to check if the tested webpage's state matches your expectations.
+You can use *assertions* to check if the tested webpage's state matches the expected state.
 
 TestCafe provides a comprehensive set of assertions that are based on the Behavior Driven Development style (BDD-style).
-See [Assertion API](assertion-api.md).
+See [Assertion API](assertion-api.md) for more information.
 
-This topic consists of the following sections.
+This topic consists of the following sections:
 
 * [Assertion Structure](#assertion-structure)
 * [Smart Assertion Query Mechanism](#smart-assertion-query-mechanism)
 * [Assertion options](#assertion-options)
   * [options.timeout](#optionstimeout)
+  * [options.allowUnawaitedPromise](#optionsallowunawaitedpromise)
 
 ## Assertion Structure
 
@@ -26,10 +27,12 @@ or a [client function](../obtaining-data-from-the-client/README.md) promise.
 TestCafe automatically waits for node state properties to obtain a value and for client functions to execute.
 See [Smart Assertion Query Mechanism](#smart-assertion-query-mechanism) for details.
 
+> You cannot pass a regular promise to the `expect` method unless the [options.allowUnawaitedPromise](#optionsallowunawaitedpromise) option is enabled.
+
 Next is an [assertion method](assertion-api.md). Assertion methods accept an expected value
 and, optionally, other arguments.
 
-For instance, the deep equality assertion has the following structure.
+For instance, the deep equality assertion has the following structure:
 
 ```text
 await t.expect( actual ).eql( expected, message, options );
@@ -62,9 +65,9 @@ You can perform the required assertions immediately after test action is execute
 ![Synchronous Functional Testing](../../../images/assertions/synchronous-testing.png)
 
 Functional tests are asynchronous on the web. This means that we cannot get the expected changes immediately after an end-user's actions.
-+For example, it can take time for the tested web page to send a request to the server for the required data, or an end-user's action launches an animation after which the web page reaches its final state.
-+All these intervals cannot be pre-calculated because they depend on various factors: computer performance,
- network connection speed, etc. In this case, if we perform assertions immediately after the test action finished,we can get an indefinite result.
+For example, it can take time for the tested web page to send a request to the server for the required data, or an end-user's action launches an animation after which the web page reaches its final state.
+All these intervals cannot be pre-calculated because they depend on various factors: computer performance,
+network connection speed, etc. In this case, if we perform assertions immediately after the test action finished, we can get an indefinite result.
 
 ![Asynchronous Functional Testing](../../../images/assertions/asynchronous-testing.png)
 
@@ -141,4 +144,18 @@ await t.expect(Selector('#elementId').innerText).eql('text', 'check element text
 ```
 
 > In addition to built-in assertions, you also can use assertions from Node's built-in [assert](https://nodejs.org/api/assert.html) module or 3rd-party library (for example [chai](http://chaijs.com/)).
-> In this case, you specify the time required to complete asynchronous actions using the [t.wait(timeout)](../pausing-the-test.md) method.
+> In this case, you specify the time required to complete asynchronous actions using the [t.wait(timeout)](../pausing-the-test.md) method.
+
+### options.allowUnawaitedPromise
+
+Allows a regular promise to be passed to the assertion's `expect` method.
+
+By default, only promises returned by the [selectors](../selecting-page-elements/selectors/using-selectors.md#define-assertion-actual-value)
+and [client functions](../obtaining-data-from-the-client/README.md) can be passed as the assertion's actual value.
+They trigger the [Smart Assertion Query Mechanism](#smart-assertion-query-mechanism).
+If you could pass a regular unawaited promise, this would tell TestCafe to compare the promise itself with the expected value.
+In case this is what you need, set the `allowUnawaitedPromise` option to `true`. Otherwise, an error will be thrown.
+
+```js
+await t.expect(doSomethingAsync()).ok('check that a promise is returned', { allowUnawaitedPromise: true });
+```