cherry-pick(#16421): docs: test.step return value

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]>

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.
    */