docs: improve execution modes (#35412)

Signed-off-by: Jean-François Greffier <jfgreffier@users.noreply.github.com>
Co-authored-by: Dmitry Gozman <dgozman@gmail.com>

docs/src/test-api/class-test.md

@@ -469,7 +469,18 @@ Learn more about the execution modes [here](../test-parallel.md).
   test('runs in parallel 2', async ({ page }) => {});
   ```
 
-* Running tests serially, retrying from the start.
+* Running tests in order, retrying each failed test independetly.
+
+  This is the default mode. It can be useful to set it explicitly to override project configuration that uses `fullyParallel`.
+
+  ```js
+  // Tests in this file run in order. Retries, if any, run independently.
+  test.describe.configure({ mode: 'default' });
+  test('runs first', async ({ page }) => {});
+  test('runs second', async ({ page }) => {});
+  ```
+
+* Running tests serially, retrying from the start. If one of the serial tests fails, all subsequent tests are skipped.
 
   :::note
   Running serially is not recommended. It is usually better to make your tests isolated, so they can be run independently.

docs/src/test-parallel-js.md

@@ -125,6 +125,17 @@ test('runs second', async () => {
 });
 ```
 
+## Opt out of fully parallel mode
+
+If your configuration applies parallel mode to all tests using [`property: TestConfig.fullyParallel`], you might still want to run some tests with default settings. You can override the mode per describe: 
+```js
+test.describe('runs in parallel with other describes', () => {
+  test.describe.configure({ mode: 'default' });
+  test('in order 1', async ({ page }) => {});
+  test('in order 2', async ({ page }) => {});
+});
+```
+
 ## Shard tests between multiple machines
 
 Playwright Test can shard a test suite, so that it can be executed on multiple machines.

packages/playwright/types/test.d.ts

@@ -3542,7 +3542,20 @@ export interface TestType<TestArgs extends {}, WorkerArgs extends {}> {
    *   test('runs in parallel 2', async ({ page }) => {});
    *   ```
    *
-   * - Running tests serially, retrying from the start.
+   * - Running tests in order, retrying each failed test independetly.
+   *
+   *   This is the default mode. It can be useful to set it explicitly to override project configuration that uses
+   *   `fullyParallel`.
+   *
+   *   ```js
+   *   // Tests in this file run in order. Retries, if any, run independently.
+   *   test.describe.configure({ mode: 'default' });
+   *   test('runs first', async ({ page }) => {});
+   *   test('runs second', async ({ page }) => {});
+   *   ```
+   *
+   * - Running tests serially, retrying from the start. If one of the serial tests fails, all subsequent tests are
+   *   skipped.
    *
    *   **NOTE** Running serially is not recommended. It is usually better to make your tests isolated, so they can be
    *   run independently.