From bbd3fd72f20338d033f73ed03144e83a05d83b00 Mon Sep 17 00:00:00 2001
From: Yury Semikhatsky <yurys@chromium.org>
Date: Wed, 10 Aug 2022 11:27:26 -0700
Subject: [PATCH] cherry-pick(#16421): docs: test.step return value (#16422)

---
 docs/src/test-api/class-test.md          | 27 ++++++++++++++++++++++++
 packages/playwright-test/types/test.d.ts | 14 ++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/docs/src/test-api/class-test.md b/docs/src/test-api/class-test.md
index 93deea5d973b6..c0f0f8bb3ee2d 100644
--- a/docs/src/test-api/class-test.md
+++ b/docs/src/test-api/class-test.md
@@ -1457,6 +1457,7 @@ Optional description that will be reflected in a test report.
 
 ## async method: Test.step
 * since: v1.10
+- returns: <[any]>
 
 Declares a test step.
 
@@ -1480,6 +1481,32 @@ test('test', async ({ page }) => {
 });
 ```
 
+The method returns value retuned by the step callback.
+
+```js tab=js-js
+const { test, expect } = require('@playwright/test');
+
+test('test', async ({ page }) => {
+  const user = await test.step('Log in', async () => {
+    // ...
+    return 'john';
+  });
+  expect(user).toBe('john');
+});
+```
+
+```js tab=js-ts
+import { test, expect } from '@playwright/test';
+
+test('test', async ({ page }) => {
+  const user = await test.step('Log in', async () => {
+    // ...
+    return 'john';
+  });
+  expect(user).toBe('john');
+});
+```
+
 ### param: Test.step.title
 * since: v1.10
 - `title` <[string]>
diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts
index dbdebf6645f93..5471fed48f8f2 100644
--- a/packages/playwright-test/types/test.d.ts
+++ b/packages/playwright-test/types/test.d.ts
@@ -2509,6 +2509,20 @@ export interface TestType<TestArgs extends KeyValue, WorkerArgs extends KeyValue
    * });
    * ```
    *
+   * The method returns value retuned by the step callback.
+   *
+   * ```js
+   * import { test, expect } from '@playwright/test';
+   *
+   * test('test', async ({ page }) => {
+   *   const user = await test.step('Log in', async () => {
+   *     // ...
+   *     return 'john';
+   *   });
+   *   expect(user).toBe('john');
+   * });
+   * ```
+   *
    * @param title Step name.
    * @param body Step body.
    */