Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

docs: document promise unwrapping (#39719)

Andreas9e0470e6d2e0
diff --git a/docs/src/api/class-genericassertions.md b/docs/src/api/class-genericassertions.md
index 40e594fb64..70a857cb38 100644
--- a/docs/src/api/class-genericassertions.md
+++ b/docs/src/api/class-genericassertions.md
@@ -28,6 +28,34 @@ const value = 1;
expect(value).not.toBe(2);
```
+## property: GenericAssertions.resolves
+* since: v1.9
+- returns: <[GenericAssertions]>
+
+Use `resolves` to unwrap the value of a fulfilled promise so any other matcher can be chained. If the promise is rejected the assertion fails.
+
+For example, this code tests that the promise resolves and that the resulting value is `'lemon'`:
+
+```js
+test('resolves to lemon', async () => {
+ await expect(Promise.resolve('lemon')).resolves.toBe('lemon');
+});
+```
+
+## property: GenericAssertions.rejects
+* since: v1.9
+- returns: <[GenericAssertions]>
+
+Use `.rejects` to unwrap the reason of a rejected promise so any other matcher can be chained. If the promise is fulfilled the assertion fails.
+
+For example, this code tests that the promise rejects with reason `'octopus'`:
+
+```js
+test('rejects to octopus', async () => {
+ await expect(Promise.reject(new Error('octopus'))).rejects.toThrow('octopus');
+});
+```
+
## method: GenericAssertions.toBe
* since: v1.9
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index 6ced6b68d5..c38e39d376 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -7915,6 +7915,34 @@ interface GenericAssertions<R> {
*
*/
not: GenericAssertions<R>;
+ /**
+ * Use `resolves` to unwrap the value of a fulfilled promise so any other matcher can be chained. If the promise is
+ * rejected the assertion fails.
+ *
+ * For example, this code tests that the promise resolves and that the resulting value is `'lemon'`:
+ *
+ * ```js
+ * test('resolves to lemon', async () => {
+ * await expect(Promise.resolve('lemon')).resolves.toBe('lemon');
+ * });
+ * ```
+ *
+ */
+ resolves: GenericAssertions<R>;
+ /**
+ * Use `.rejects` to unwrap the reason of a rejected promise so any other matcher can be chained. If the promise is
+ * fulfilled the assertion fails.
+ *
+ * For example, this code tests that the promise rejects with reason `'octopus'`:
+ *
+ * ```js
+ * test('rejects to octopus', async () => {
+ * await expect(Promise.reject(new Error('octopus'))).rejects.toThrow('octopus');
+ * });
+ * ```
+ *
+ */
+ rejects: GenericAssertions<R>;
/**
* Compares value with
* [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-be-option-expected) by
diff --git a/utils/generate_types/overrides-test.d.ts b/utils/generate_types/overrides-test.d.ts
index d4ff176959..ed8346e485 100644
--- a/utils/generate_types/overrides-test.d.ts
+++ b/utils/generate_types/overrides-test.d.ts
@@ -332,6 +332,8 @@ interface AsymmetricMatchers {
interface GenericAssertions<R> {
not: GenericAssertions<R>;
+ resolves: GenericAssertions<R>;
+ rejects: GenericAssertions<R>;
toBe(expected: unknown): R;
toBeCloseTo(expected: number, numDigits?: number): R;
toBeDefined(): R;