From 41d0122b94f41b308536c48ced345dec8c272a49 Mon Sep 17 00:00:00 2001
From: jrandolf <101637635+jrandolf@users.noreply.github.com>
Date: Thu, 6 Oct 2022 17:30:00 +0200
Subject: [PATCH] fix!: deprecate indirect network condition imports (#9074)
---
docs/api/index.md | 25 ++++++++-------
docs/api/puppeteer.networkconditions.md | 20 ++----------
...puppeteer.page.emulatenetworkconditions.md | 12 +++----
docs/api/puppeteer.page.md | 4 +--
docs/api/puppeteer.page.setofflinemode.md | 8 ++---
.../puppeteer.predefinednetworkconditions.md | 32 +++++++++++++++++++
docs/api/puppeteer.puppeteer.md | 7 ++--
.../puppeteer.puppeteer.networkconditions.md | 23 -------------
packages/puppeteer-core/src/api/Page.ts | 26 ++++++++-------
packages/puppeteer-core/src/common/Page.ts | 30 -----------------
...ions.ts => PredefinedNetworkConditions.ts} | 24 +++++++-------
.../puppeteer-core/src/common/Puppeteer.ts | 13 --------
packages/puppeteer-core/src/puppeteer-core.ts | 2 +-
packages/puppeteer-core/src/types.ts | 2 +-
packages/puppeteer/src/puppeteer.ts | 2 +-
packages/puppeteer/src/types.ts | 2 +-
test/src/emulation.spec.ts | 9 +++---
17 files changed, 100 insertions(+), 141 deletions(-)
create mode 100644 docs/api/puppeteer.predefinednetworkconditions.md
delete mode 100644 docs/api/puppeteer.puppeteer.networkconditions.md
rename packages/puppeteer-core/src/common/{NetworkConditions.ts => PredefinedNetworkConditions.ts} (73%)
diff --git a/docs/api/index.md b/docs/api/index.md
index 13251d4168b..38272c2ff31 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -120,18 +120,19 @@ sidebar_label: API
## Variables
-| Variable | Description |
-| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [connect](./puppeteer.connect.md) | |
-| [createBrowserFetcher](./puppeteer.createbrowserfetcher.md) | |
-| [DEFAULT_INTERCEPT_RESOLUTION_PRIORITY](./puppeteer.default_intercept_resolution_priority.md) | The default cooperative request interception resolution priority |
-| [defaultArgs](./puppeteer.defaultargs.md) | |
-| [devices](./puppeteer.devices.md) | A list of devices to be used with page.emulate(options)
. Actual list of devices can be found in [src/common/DeviceDescriptors.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts). |
-| [errors](./puppeteer.errors.md) | |
-| [EVALUATION_SCRIPT_URL](./puppeteer.evaluation_script_url.md) | |
-| [executablePath](./puppeteer.executablepath.md) | |
-| [launch](./puppeteer.launch.md) | |
-| [networkConditions](./puppeteer.networkconditions.md) | A list of network conditions to be used with page.emulateNetworkConditions(networkConditions)
. Actual list of predefined conditions can be found in [src/common/NetworkConditions.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/NetworkConditions.ts). |
+| Variable | Description |
+| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [connect](./puppeteer.connect.md) | |
+| [createBrowserFetcher](./puppeteer.createbrowserfetcher.md) | |
+| [DEFAULT_INTERCEPT_RESOLUTION_PRIORITY](./puppeteer.default_intercept_resolution_priority.md) | The default cooperative request interception resolution priority |
+| [defaultArgs](./puppeteer.defaultargs.md) | |
+| [devices](./puppeteer.devices.md) | A list of devices to be used with page.emulate(options)
. Actual list of devices can be found in [src/common/DeviceDescriptors.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/DeviceDescriptors.ts). |
+| [errors](./puppeteer.errors.md) | |
+| [EVALUATION_SCRIPT_URL](./puppeteer.evaluation_script_url.md) | |
+| [executablePath](./puppeteer.executablepath.md) | |
+| [launch](./puppeteer.launch.md) | |
+| [networkConditions](./puppeteer.networkconditions.md) | |
+| [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md) | A list of network conditions to be used with [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md). |
## Type Aliases
diff --git a/docs/api/puppeteer.networkconditions.md b/docs/api/puppeteer.networkconditions.md
index ec4630bd330..2ed1334918f 100644
--- a/docs/api/puppeteer.networkconditions.md
+++ b/docs/api/puppeteer.networkconditions.md
@@ -4,7 +4,9 @@ sidebar_label: networkConditions
# networkConditions variable
-A list of network conditions to be used with `page.emulateNetworkConditions(networkConditions)`. Actual list of predefined conditions can be found in [src/common/NetworkConditions.ts](https://github.com/puppeteer/puppeteer/blob/main/src/common/NetworkConditions.ts).
+> Warning: This API is now obsolete.
+>
+> Import [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md).
**Signature:**
@@ -14,19 +16,3 @@ networkConditions: Readonly<{
'Fast 3G': NetworkConditions;
}>;
```
-
-## Example
-
-```ts
-const puppeteer = require('puppeteer');
-const slow3G = puppeteer.networkConditions['Slow 3G'];
-
-(async () => {
- const browser = await puppeteer.launch();
- const page = await browser.newPage();
- await page.emulateNetworkConditions(slow3G);
- await page.goto('https://www.google.com');
- // other actions...
- await browser.close();
-})();
-```
diff --git a/docs/api/puppeteer.page.emulatenetworkconditions.md b/docs/api/puppeteer.page.emulatenetworkconditions.md
index 6729e570203..dac0edf0d5a 100644
--- a/docs/api/puppeteer.page.emulatenetworkconditions.md
+++ b/docs/api/puppeteer.page.emulatenetworkconditions.md
@@ -4,6 +4,10 @@ sidebar_label: Page.emulateNetworkConditions
# Page.emulateNetworkConditions() method
+This does not affect WebSockets and WebRTC PeerConnections (see https://crbug.com/563644). To set the page offline, you can use [Page.setOfflineMode()](./puppeteer.page.setofflinemode.md).
+
+A list of predefined network conditions can be used by importing [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md).
+
**Signature:**
```typescript
@@ -24,15 +28,11 @@ class Page {
Promise<void>
-## Remarks
-
-NOTE: This does not affect WebSockets and WebRTC PeerConnections (see https://crbug.com/563644). To set the page offline, you can use \[page.setOfflineMode(enabled)\](\#pagesetofflinemodeenabled).
-
## Example
```ts
-const puppeteer = require('puppeteer');
-const slow3G = puppeteer.networkConditions['Slow 3G'];
+import {PredefinedNetworkConditions} from 'puppeteer';
+const slow3G = PredefinedNetworkConditions['Slow 3G'];
(async () => {
const browser = await puppeteer.launch();
diff --git a/docs/api/puppeteer.page.md b/docs/api/puppeteer.page.md
index abfc4da5d30..8348a2f59e7 100644
--- a/docs/api/puppeteer.page.md
+++ b/docs/api/puppeteer.page.md
@@ -100,7 +100,7 @@ page.off('request', logRequest);
| [emulateIdleState(overrides)](./puppeteer.page.emulateidlestate.md) | | Emulates the idle state. If no arguments set, clears idle state emulation. |
| [emulateMediaFeatures(features)](./puppeteer.page.emulatemediafeatures.md) | | |
| [emulateMediaType(type)](./puppeteer.page.emulatemediatype.md) | | |
-| [emulateNetworkConditions(networkConditions)](./puppeteer.page.emulatenetworkconditions.md) | | |
+| [emulateNetworkConditions(networkConditions)](./puppeteer.page.emulatenetworkconditions.md) | |
This does not affect WebSockets and WebRTC PeerConnections (see https://crbug.com/563644). To set the page offline, you can use [Page.setOfflineMode()](./puppeteer.page.setofflinemode.md).
A list of predefined network conditions can be used by importing [PredefinedNetworkConditions](./puppeteer.predefinednetworkconditions.md).
| | [emulateTimezone(timezoneId)](./puppeteer.page.emulatetimezone.md) | | | | [emulateVisionDeficiency(type)](./puppeteer.page.emulatevisiondeficiency.md) | | Simulates the given vision deficiency on the page. | | [evaluate(pageFunction, args)](./puppeteer.page.evaluate.md) | |Evaluates a function in the page's context and returns the result.
If the function passed to page.evaluteHandle
returns a Promise, the function will wait for the promise to resolve and return its value.
The extra HTTP headers will be sent with every request the page initiates.
:::tip
All HTTP header names are lowercased. (HTTP headers are case-insensitive, so this shouldn’t impact your server code.)
:::
:::note
page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests.
:::
| | [setGeolocation(options)](./puppeteer.page.setgeolocation.md) | | Sets the page's geolocation. | | [setJavaScriptEnabled(enabled)](./puppeteer.page.setjavascriptenabled.md) | | | -| [setOfflineMode(enabled)](./puppeteer.page.setofflinemode.md) | | | +| [setOfflineMode(enabled)](./puppeteer.page.setofflinemode.md) | |Sets the network connection to offline.
It does not change the parameters used in [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md)
| | [setRequestInterception(value)](./puppeteer.page.setrequestinterception.md) | |Activating request interception enables [HTTPRequest.abort()](./puppeteer.httprequest.abort.md), [HTTPRequest.continue()](./puppeteer.httprequest.continue.md) and [HTTPRequest.respond()](./puppeteer.httprequest.respond.md) methods. This provides the capability to modify network requests that are made by a page.
Once request interception is enabled, every request will stall unless it's continued, responded or aborted; or completed using the browser cache.
Enabling request interception disables page caching.
See the [Request interception guide](https://pptr.dev/next/guides/request-interception) for more details.
| | [setUserAgent(userAgent, userAgentMetadata)](./puppeteer.page.setuseragent.md) | | | | [setViewport(viewport)](./puppeteer.page.setviewport.md) | |page.setViewport
will resize the page. A lot of websites don't expect phones to change size, so you should set the viewport before navigating to the page.
In the case of multiple pages in a single browser, each page can have its own viewport size.
| diff --git a/docs/api/puppeteer.page.setofflinemode.md b/docs/api/puppeteer.page.setofflinemode.md index d706b8ded9c..0a1fd7f9616 100644 --- a/docs/api/puppeteer.page.setofflinemode.md +++ b/docs/api/puppeteer.page.setofflinemode.md @@ -4,6 +4,10 @@ sidebar_label: Page.setOfflineMode # Page.setOfflineMode() method +Sets the network connection to offline. + +It does not change the parameters used in [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md) + **Signature:** ```typescript @@ -21,7 +25,3 @@ class Page { **Returns:** Promise<void> - -## Remarks - -NOTE: while this method sets the network connection to offline, it does not change the parameters used in \[page.emulateNetworkConditions(networkConditions)\] (\#pageemulatenetworkconditionsnetworkconditions) diff --git a/docs/api/puppeteer.predefinednetworkconditions.md b/docs/api/puppeteer.predefinednetworkconditions.md new file mode 100644 index 00000000000..ec88b6c088a --- /dev/null +++ b/docs/api/puppeteer.predefinednetworkconditions.md @@ -0,0 +1,32 @@ +--- +sidebar_label: PredefinedNetworkConditions +--- + +# PredefinedNetworkConditions variable + +A list of network conditions to be used with [Page.emulateNetworkConditions()](./puppeteer.page.emulatenetworkconditions.md). + +**Signature:** + +```typescript +PredefinedNetworkConditions: Readonly<{ + 'Slow 3G': NetworkConditions; + 'Fast 3G': NetworkConditions; +}>; +``` + +## Example + +```ts +import {PredefinedNetworkConditions} from 'puppeteer'; +const slow3G = PredefinedNetworkConditions['Slow 3G']; + +(async () => { + const browser = await puppeteer.launch(); + const page = await browser.newPage(); + await page.emulateNetworkConditions(slow3G); + await page.goto('https://www.google.com'); + // other actions... + await browser.close(); +})(); +``` diff --git a/docs/api/puppeteer.puppeteer.md b/docs/api/puppeteer.puppeteer.md index bfc92d795b9..a9e9c7d70f5 100644 --- a/docs/api/puppeteer.puppeteer.md +++ b/docs/api/puppeteer.puppeteer.md @@ -20,10 +20,9 @@ The constructor for this class is marked as internal. Third-party code should no ## Properties -| Property | Modifiers | Type | Description | -| --------------------------------------------------------------- | --------------------- | ------------------------------------------------------------ | ----------- | -| [devices](./puppeteer.puppeteer.devices.md) |readonly
| typeof [devices](./puppeteer.devices.md) | |
-| [networkConditions](./puppeteer.puppeteer.networkconditions.md) | readonly
| typeof [networkConditions](./puppeteer.networkconditions.md) | |
+| Property | Modifiers | Type | Description |
+| ------------------------------------------- | --------------------- | ---------------------------------------- | ----------- |
+| [devices](./puppeteer.puppeteer.devices.md) | readonly
| typeof [devices](./puppeteer.devices.md) | |
## Methods
diff --git a/docs/api/puppeteer.puppeteer.networkconditions.md b/docs/api/puppeteer.puppeteer.networkconditions.md
deleted file mode 100644
index c79ba27265c..00000000000
--- a/docs/api/puppeteer.puppeteer.networkconditions.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-sidebar_label: Puppeteer.networkConditions
----
-
-# Puppeteer.networkConditions property
-
-> Warning: This API is now obsolete.
->
-> Import directly puppeteer.
-
-**Signature:**
-
-```typescript
-class Puppeteer {
- get networkConditions(): typeof networkConditions;
-}
-```
-
-## Example
-
-```ts
-import {networkConditions} from 'puppeteer';
-```
diff --git a/packages/puppeteer-core/src/api/Page.ts b/packages/puppeteer-core/src/api/Page.ts
index faccee57be6..6c45c981cdc 100644
--- a/packages/puppeteer-core/src/api/Page.ts
+++ b/packages/puppeteer-core/src/api/Page.ts
@@ -675,11 +675,11 @@ export class Page extends EventEmitter {
}
/**
+ * Sets the network connection to offline.
+ *
+ * It does not change the parameters used in {@link Page.emulateNetworkConditions}
+ *
* @param enabled - When `true`, enables offline mode for the page.
- * @remarks
- * NOTE: while this method sets the network connection to offline, it does
- * not change the parameters used in [page.emulateNetworkConditions(networkConditions)]
- * (#pageemulatenetworkconditionsnetworkconditions)
*/
setOfflineMode(enabled: boolean): Promise