docs(trial): note that modifier keys are pressed regardless of trial …

…option (#32734)
microsoft · Sep 23, 2024 · 281eff1 · 281eff1
1 parent 0cdc7ee
commit 281eff1
Show file tree

Hide file tree

Showing 5 changed files with 53 additions and 24 deletions.
diff --git a/docs/src/api/class-frame.md b/docs/src/api/class-frame.md
@@ -280,7 +280,7 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Frame.click.timeout = %%-input-timeout-js-%%
 * since: v1.8
 
-### option: Frame.click.trial = %%-input-trial-%%
+### option: Frame.click.trial = %%-input-trial-with-modifiers-%%
 * since: v1.11
 
 ## async method: Frame.content
@@ -341,7 +341,7 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Frame.dblclick.timeout = %%-input-timeout-js-%%
 * since: v1.8
 
-### option: Frame.dblclick.trial = %%-input-trial-%%
+### option: Frame.dblclick.trial = %%-input-trial-with-modifiers-%%
 * since: v1.11
 
 ## async method: Frame.dispatchEvent
@@ -1153,7 +1153,7 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Frame.hover.timeout = %%-input-timeout-js-%%
 * since: v1.8
 
-### option: Frame.hover.trial = %%-input-trial-%%
+### option: Frame.hover.trial = %%-input-trial-with-modifiers-%%
 * since: v1.11
 
 ### option: Frame.hover.noWaitAfter = %%-input-no-wait-after-removed-%%
@@ -1703,7 +1703,7 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Frame.tap.timeout = %%-input-timeout-js-%%
 * since: v1.8
 
-### option: Frame.tap.trial = %%-input-trial-%%
+### option: Frame.tap.trial = %%-input-trial-with-modifiers-%%
 * since: v1.11
 
 ## async method: Frame.textContent

diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
@@ -433,7 +433,7 @@ await page.Locator("canvas").ClickAsync(new() {
 ### option: Locator.click.timeout = %%-input-timeout-js-%%
 * since: v1.14
 
-### option: Locator.click.trial = %%-input-trial-%%
+### option: Locator.click.trial = %%-input-trial-with-modifiers-%%
 * since: v1.14
 
 ## async method: Locator.count
@@ -516,7 +516,7 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Locator.dblclick.timeout = %%-input-timeout-js-%%
 * since: v1.14
 
-### option: Locator.dblclick.trial = %%-input-trial-%%
+### option: Locator.dblclick.trial = %%-input-trial-with-modifiers-%%
 * since: v1.14
 
 ## async method: Locator.dispatchEvent
@@ -1266,7 +1266,7 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Locator.hover.timeout = %%-input-timeout-js-%%
 * since: v1.14
 
-### option: Locator.hover.trial = %%-input-trial-%%
+### option: Locator.hover.trial = %%-input-trial-with-modifiers-%%
 * since: v1.14
 
 ### option: Locator.hover.noWaitAfter = %%-input-no-wait-after-removed-%%
@@ -2331,7 +2331,7 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Locator.tap.timeout = %%-input-timeout-js-%%
 * since: v1.14
 
-### option: Locator.tap.trial = %%-input-trial-%%
+### option: Locator.tap.trial = %%-input-trial-with-modifiers-%%
 * since: v1.14
 
 ## async method: Locator.textContent

diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
@@ -812,7 +812,7 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Page.click.timeout = %%-input-timeout-js-%%
 * since: v1.8
 
-### option: Page.click.trial = %%-input-trial-%%
+### option: Page.click.trial = %%-input-trial-with-modifiers-%%
 * since: v1.11
 
 ## async method: Page.close
@@ -915,7 +915,7 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Page.dblclick.timeout = %%-input-timeout-js-%%
 * since: v1.8
 
-### option: Page.dblclick.trial = %%-input-trial-%%
+### option: Page.dblclick.trial = %%-input-trial-with-modifiers-%%
 * since: v1.11
 
 ## async method: Page.dispatchEvent
@@ -2437,7 +2437,7 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Page.hover.timeout = %%-input-timeout-js-%%
 * since: v1.8
 
-### option: Page.hover.trial = %%-input-trial-%%
+### option: Page.hover.trial = %%-input-trial-with-modifiers-%%
 * since: v1.11
 
 ### option: Page.hover.noWaitAfter = %%-input-no-wait-after-removed-%%
@@ -4099,7 +4099,7 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Page.tap.timeout = %%-input-timeout-js-%%
 * since: v1.8
 
-### option: Page.tap.trial = %%-input-trial-%%
+### option: Page.tap.trial = %%-input-trial-with-modifiers-%%
 * since: v1.11
 
 ## async method: Page.textContent

diff --git a/docs/src/api/params.md b/docs/src/api/params.md
@@ -136,6 +136,11 @@ defaults to 1. See [UIEvent.detail].
 
 When set, this method only performs the [actionability](../actionability.md) checks and skips the action. Defaults to `false`. Useful to wait until the element is ready for the action without performing it.
 
+## input-trial-with-modifiers
+- `trial` <[boolean]>
+
+When set, this method only performs the [actionability](../actionability.md) checks and skips the action. Defaults to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys are pressed.
+
 ## input-source-position
 - `sourcePosition` <[Object]>
   - `x` <[float]>

diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
@@ -2120,7 +2120,9 @@ export interface Page {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;
@@ -2233,7 +2235,9 @@ export interface Page {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;
@@ -3125,7 +3129,9 @@ export interface Page {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;
@@ -4266,7 +4272,9 @@ export interface Page {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;
@@ -5845,7 +5853,9 @@ export interface Frame {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;
@@ -5931,7 +5941,9 @@ export interface Frame {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;
@@ -6621,7 +6633,9 @@ export interface Frame {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;
@@ -7308,7 +7322,9 @@ export interface Frame {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;
@@ -12045,7 +12061,9 @@ export interface Locator {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;
@@ -12155,7 +12173,9 @@ export interface Locator {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;
@@ -12825,7 +12845,9 @@ export interface Locator {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;
@@ -13626,7 +13648,9 @@ export interface Locator {
 
     /**
      * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
-     * to `false`. Useful to wait until the element is ready for the action without performing it.
+     * to `false`. Useful to wait until the element is ready for the action without performing it. Note that keyboard
+     * `modifiers` will be pressed regardless of `trial` to allow testing elements which are only visible when those keys
+     * are pressed.
      */
     trial?: boolean;
   }): Promise<void>;