docs: clarify use of browser.close (#15255)

docs/src/api/class-browser.md

@@ -92,6 +92,10 @@ were opened).
 In case this browser is connected to, clears all created contexts belonging to this browser and disconnects from the
 browser server.
 
+:::note
+This is similar to force quitting the browser. Therefore, you should call [`method: BrowserContext.close`] on any [BrowserContext]'s you explicitly created earlier with [`method: Browser.newContext`] **before** calling [`method: Browser.close`].
+:::
+
 The [Browser] object itself is considered to be disposed and cannot be used anymore.
 
 ## method: Browser.contexts
@@ -156,6 +160,11 @@ Returns the newly created browser session.
 
 Creates a new browser context. It won't share cookies/cache with other browser contexts.
 
+:::note
+If directly using this method to create [BrowserContext]s, it is best practice to explicilty close the returned context via [`method: BrowserContext.close`] when your code is done with the [BrowserContext],
+and before calling [`method: Browser.close`]. This will ensure the `context` is closed gracefully and any artifacts—like HARs and videos—are fully flushed and saved.
+:::
+
 ```js
 (async () => {
   const browser = await playwright.firefox.launch();  // Or 'chromium' or 'webkit'.
@@ -164,6 +173,10 @@ Creates a new browser context. It won't share cookies/cache with other browser c
   // Create a new page in a pristine context.
   const page = await context.newPage();
   await page.goto('https://example.com');
+
+  // Gracefully close up everything
+  await context.close();
+  await browser.close();
 })();
 ```
 
@@ -174,6 +187,10 @@ BrowserContext context = browser.newContext();
 // Create a new page in a pristine context.
 Page page = context.newPage();
 page.navigate('https://example.com');
+
+// Gracefull close up everything
+context.close();
+browser.close();
 ```
 
 ```python async
@@ -183,6 +200,10 @@ context = await browser.new_context()
 # create a new page in a pristine context.
 page = await context.new_page()
 await page.goto("https://example.com")
+
+# gracefully close up everything
+await context.close()
+await browser.close()
 ```
 
 ```python sync
@@ -192,6 +213,10 @@ context = browser.new_context()
 # create a new page in a pristine context.
 page = context.new_page()
 page.goto("https://example.com")
+
+# gracefully close up everything
+context.close()
+browser.close()
 ```
 
 ```csharp
@@ -202,6 +227,10 @@ var context = await browser.NewContextAsync();
 // Create a new page in a pristine context.
 var page = await context.NewPageAsync(); ;
 await page.GotoAsync("https://www.bing.com");
+
+// Gracefully close up everything
+await context.CloseAsync();
+await browser.CloseAsync();
 ```
 
 ### option: Browser.newContext.-inline- = %%-shared-context-params-list-%%

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

@@ -13224,6 +13224,12 @@ export interface Browser extends EventEmitter {
    * In case this browser is connected to, clears all created contexts belonging to this browser and disconnects from the
    * browser server.
    *
+   * > NOTE: This is similar to force quitting the browser. Therefore, you should call
+   * [browserContext.close()](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) on any
+   * [BrowserContext]'s you explicitly created earlier with
+   * [browser.newContext([options])](https://playwright.dev/docs/api/class-browser#browser-new-context) **before** calling
+   * [browser.close()](https://playwright.dev/docs/api/class-browser#browser-close).
+   *
    * The [Browser] object itself is considered to be disposed and cannot be used anymore.
    */
   close(): Promise<void>;
@@ -13257,6 +13263,12 @@ export interface Browser extends EventEmitter {
   /**
    * Creates a new browser context. It won't share cookies/cache with other browser contexts.
    *
+   * > NOTE: If directly using this method to create [BrowserContext]s, it is best practice to explicilty close the returned
+   * context via [browserContext.close()](https://playwright.dev/docs/api/class-browsercontext#browser-context-close) when
+   * your code is done with the [BrowserContext], and before calling
+   * [browser.close()](https://playwright.dev/docs/api/class-browser#browser-close). This will ensure the `context` is closed
+   * gracefully and any artifacts—like HARs and videos—are fully flushed and saved.
+   *
    * ```js
    * (async () => {
    *   const browser = await playwright.firefox.launch();  // Or 'chromium' or 'webkit'.
@@ -13265,6 +13277,10 @@ export interface Browser extends EventEmitter {
    *   // Create a new page in a pristine context.
    *   const page = await context.newPage();
    *   await page.goto('https://example.com');
+   *
+   *   // Gracefully close up everything
+   *   await context.close();
+   *   await browser.close();
    * })();
    * ```
    *