docs: document subdomain cookie matching (#23007)

Fixes https://github.com/microsoft/playwright/issues/22977

docs/src/api/class-browsercontext.md

@@ -333,6 +333,10 @@ await context.AddCookiesAsync(new[] { cookie1, cookie2 });
   - `secure` ?<[boolean]> Optional.
   - `sameSite` ?<[SameSiteAttribute]<"Strict"|"Lax"|"None">> Optional.
 
+Adds cookies to the browser context.
+
+For the cookie to apply to all subdomains as well, prefix domain with a dot, like this: ".example.com".
+
 ## async method: BrowserContext.addInitScript
 * since: v1.8
 

docs/src/api/params.md

@@ -237,11 +237,11 @@ Specify environment variables that will be visible to the browser. Defaults to `
 ## js-python-context-option-storage-state
 * langs: js, python
 - `storageState` <[path]|[Object]>
-  - `cookies` <[Array]<[Object]>> cookies to set for context
+  - `cookies` <[Array]<[Object]>> Cookies to set for context
     - `name` <[string]>
     - `value` <[string]>
-    - `domain` <[string]> domain and path are required
-    - `path` <[string]> domain and path are required
+    - `domain` <[string]> Domain and path are required. For the cookie to apply to all subdomains as well, prefix domain with a dot, like this: ".example.com"
+    - `path` <[string]> Domain and path are required
     - `expires` <[float]> Unix time in seconds.
     - `httpOnly` <[boolean]>
     - `secure` <[boolean]>
@@ -254,7 +254,7 @@ Specify environment variables that will be visible to the browser. Defaults to `
 
 Learn more about [storage state and auth](../auth.md).
 
-Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [`method: BrowserContext.storageState`]. Either a path to the file with saved storage, or an object with the following fields:
+Populates context with given storage state. This option can be used to initialize context with logged-in information obtained via [`method: BrowserContext.storageState`].
 
 ## csharp-java-context-option-storage-state
 * langs: csharp, java
@@ -1105,7 +1105,7 @@ When true, takes a screenshot of the full scrollable page, instead of the curren
   - `width` <[float]> width of clipping area
   - `height` <[float]> height of clipping area
 
-An object which specifies clipping of the resulting image. Should have the following fields:
+An object which specifies clipping of the resulting image.
 
 ## screenshot-option-scale
 - `scale` <[ScreenshotScale]<"css"|"device">>

packages/playwright-core/types/types.d.ts

@@ -8066,7 +8066,9 @@ export interface BrowserContext {
    * await browserContext.addCookies([cookieObject1, cookieObject2]);
    * ```
    *
-   * @param cookies
+   * @param cookies Adds cookies to the browser context.
+   *
+   * For the cookie to apply to all subdomains as well, prefix domain with a dot, like this: ".example.com".
    */
   addCookies(cookies: Array<{
     name: string;
@@ -16157,11 +16159,10 @@ export interface Browser extends EventEmitter {
      * Populates context with given storage state. This option can be used to initialize context with logged-in
      * information obtained via
      * [browserContext.storageState([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state).
-     * Either a path to the file with saved storage, or an object with the following fields:
      */
     storageState?: string|{
       /**
-       * cookies to set for context
+       * Cookies to set for context
        */
       cookies: Array<{
         name: string;
@@ -16169,12 +16170,13 @@ export interface Browser extends EventEmitter {
         value: string;
 
         /**
-         * domain and path are required
+         * Domain and path are required. For the cookie to apply to all subdomains as well, prefix domain with a dot, like
+         * this: ".example.com"
          */
         domain: string;
 
         /**
-         * domain and path are required
+         * Domain and path are required
          */
         path: string;
 
@@ -19282,11 +19284,10 @@ export interface BrowserContextOptions {
    * Populates context with given storage state. This option can be used to initialize context with logged-in
    * information obtained via
    * [browserContext.storageState([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state).
-   * Either a path to the file with saved storage, or an object with the following fields:
    */
   storageState?: string|{
     /**
-     * cookies to set for context
+     * Cookies to set for context
      */
     cookies: Array<{
       name: string;
@@ -19294,12 +19295,13 @@ export interface BrowserContextOptions {
       value: string;
 
       /**
-       * domain and path are required
+       * Domain and path are required. For the cookie to apply to all subdomains as well, prefix domain with a dot, like
+       * this: ".example.com"
        */
       domain: string;
 
       /**
-       * domain and path are required
+       * Domain and path are required
        */
       path: string;
 
@@ -19788,7 +19790,7 @@ export interface PageScreenshotOptions {
   caret?: "hide"|"initial";
 
   /**
-   * An object which specifies clipping of the resulting image. Should have the following fields:
+   * An object which specifies clipping of the resulting image.
    */
   clip?: {
     /**

packages/playwright-test/types/test.d.ts

@@ -3922,7 +3922,6 @@ export interface PlaywrightTestOptions {
    * Populates context with given storage state. This option can be used to initialize context with logged-in
    * information obtained via
    * [browserContext.storageState([options])](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state).
-   * Either a path to the file with saved storage, or an object with the following fields:
    */
   storageState: StorageState | undefined;
   /**
@@ -5587,7 +5586,7 @@ interface PageAssertions {
     caret?: "hide"|"initial";
 
     /**
-     * An object which specifies clipping of the resulting image. Should have the following fields:
+     * An object which specifies clipping of the resulting image.
      */
     clip?: {
       /**
@@ -5694,7 +5693,7 @@ interface PageAssertions {
     caret?: "hide"|"initial";
 
     /**
-     * An object which specifies clipping of the resulting image. Should have the following fields:
+     * An object which specifies clipping of the resulting image.
      */
     clip?: {
       /**