From 5761a62b1c0a95cb39c2e775eba0dd40adf7b2ec Mon Sep 17 00:00:00 2001
From: Pavel Feldman <pavel.feldman@gmail.com>
Date: Wed, 25 Jan 2023 17:48:18 -0800
Subject: [PATCH] docs: clarify the null value for the viewport (#20333)

Fixes https://github.com/microsoft/playwright/issues/20284
---
 docs/src/api/params.md                    | 18 +++++++++++++++--
 packages/playwright-core/types/types.d.ts | 24 +++++++++++++++++++----
 packages/playwright-test/types/test.d.ts  |  6 +++++-
 3 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/docs/src/api/params.md b/docs/src/api/params.md
index a58da7d775..75873e02c2 100644
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@@ -276,7 +276,14 @@ When using [`method: Page.goto`], [`method: Page.route`], [`method: Page.waitFor
   - `width` <[int]> page width in pixels.
   - `height` <[int]> page height in pixels.
 
-Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.
+Use `null` to disable the consistent viewport emulation.
+
+:::note
+The `null` value opts out from the default presets, makes viewport depend on the
+host window size defined by the operating system. It makes the execution of the
+tests non-deterministic.
+:::
 
 ## csharp-context-option-viewport
 * langs: csharp
@@ -285,7 +292,14 @@ Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `n
   - `width` <[int]> page width in pixels.
   - `height` <[int]> page height in pixels.
 
-Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `ViewportSize.NoViewport` to disable the default viewport.
+Emulates consistent viewport for each page. Defaults to an 1280x720 viewport.
+Use `ViewportSize.NoViewport` to disable the consistent viewport emulation.
+
+:::note
+The `ViewportSize.NoViewport` value opts out from the default presets,
+makes viewport depend on the host window size defined by the operating system.
+It makes the execution of the tests non-deterministic.
+:::
 
 ## context-option-screen
 * langs:
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index b497f8d60f..e61b6edf83 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -12514,7 +12514,11 @@ export interface BrowserType<Unused = {}> {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+     * viewport emulation.
+     *
+     * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
+     * by the operating system. It makes the execution of the tests non-deterministic.
      */
     viewport?: null|{
       /**
@@ -13877,7 +13881,11 @@ export interface AndroidDevice {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+     * viewport emulation.
+     *
+     * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
+     * by the operating system. It makes the execution of the tests non-deterministic.
      */
     viewport?: null|{
       /**
@@ -15779,7 +15787,11 @@ export interface Browser extends EventEmitter {
     videosPath?: string;
 
     /**
-     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+     * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+     * viewport emulation.
+     *
+     * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
+     * by the operating system. It makes the execution of the tests non-deterministic.
      */
     viewport?: null|{
       /**
@@ -18820,7 +18832,11 @@ export interface BrowserContextOptions {
   videosPath?: string;
 
   /**
-   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+   * viewport emulation.
+   *
+   * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
+   * by the operating system. It makes the execution of the tests non-deterministic.
    */
   viewport?: null|ViewportSize;
 }
diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts
index 77ce9df68d..4612371ae2 100644
--- a/packages/playwright-test/types/test.d.ts
+++ b/packages/playwright-test/types/test.d.ts
@@ -3523,7 +3523,11 @@ export interface PlaywrightTestOptions {
    */
   userAgent: string | undefined;
   /**
-   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
+   * Emulates consistent viewport for each page. Defaults to an 1280x720 viewport. Use `null` to disable the consistent
+   * viewport emulation.
+   *
+   * **NOTE** The `null` value opts out from the default presets, makes viewport depend on the host window size defined
+   * by the operating system. It makes the execution of the tests non-deterministic.
    */
   viewport: ViewportSize | null | undefined;
   /**