From 01d7eac7adee6b5b4b64fe60a333bc30d60bc142 Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Fri, 8 Jan 2021 15:50:38 -0800 Subject: [PATCH] feat: roll driver, switch to new api.json format (#199) --- .github/workflows/test.yml | 12 +- .../microsoft/playwright/impl/DriverJar.java | 30 +- .../com/microsoft/playwright/TestInstall.java | 22 +- .../com/microsoft/playwright/impl/Driver.java | 2 +- examples/pom.xml | 2 +- .../microsoft/playwright/Accessibility.java | 32 +- .../com/microsoft/playwright/Browser.java | 627 ++++---- .../microsoft/playwright/BrowserContext.java | 213 ++- .../com/microsoft/playwright/BrowserType.java | 566 ++++--- .../microsoft/playwright/ConsoleMessage.java | 10 +- .../playwright/DeviceDescriptor.java | 2 +- .../java/com/microsoft/playwright/Dialog.java | 5 +- .../com/microsoft/playwright/Download.java | 20 +- .../microsoft/playwright/ElementHandle.java | 684 +++++--- .../com/microsoft/playwright/FileChooser.java | 19 +- .../java/com/microsoft/playwright/Frame.java | 901 +++++++---- .../com/microsoft/playwright/JSHandle.java | 40 +- .../com/microsoft/playwright/Keyboard.java | 72 +- .../java/com/microsoft/playwright/Mouse.java | 24 +- .../java/com/microsoft/playwright/Page.java | 1432 ++++++++++------- .../com/microsoft/playwright/Playwright.java | 54 +- .../com/microsoft/playwright/Request.java | 114 +- .../com/microsoft/playwright/Response.java | 6 +- .../java/com/microsoft/playwright/Route.java | 45 +- .../com/microsoft/playwright/Selectors.java | 13 +- .../microsoft/playwright/TimeoutError.java | 6 +- .../com/microsoft/playwright/Touchscreen.java | 4 +- .../java/com/microsoft/playwright/Video.java | 6 +- .../com/microsoft/playwright/WebSocket.java | 6 +- .../java/com/microsoft/playwright/Worker.java | 26 +- .../playwright/impl/DeviceDescriptorImpl.java | 4 +- .../playwright/TestBrowserContextBasic.java | 4 +- .../com/microsoft/playwright/TestClick.java | 2 +- scripts/CLI_VERSION | 2 +- scripts/download_driver_for_all_platforms.sh | 4 +- scripts/generate_api.sh | 2 +- .../playwright/tools/ApiGenerator.java | 257 ++- .../com/microsoft/playwright/tools/Types.java | 276 ++-- 38 files changed, 3473 insertions(+), 2073 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 8c68c027..b0927f53 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -26,12 +26,12 @@ jobs: path: ~/.m2 key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }} restore-keys: ${{ runner.os }}-m2 - - name: Cache Downloaded Drivers - uses: actions/cache@v2 - with: - path: driver-bundle/src/main/resources/driver - key: ${{ runner.os }}-drivers-${{ hashFiles('scripts/*') }} - restore-keys: ${{ runner.os }}-drivers +# - name: Cache Downloaded Drivers +# uses: actions/cache@v2 +# with: +# path: driver-bundle/src/main/resources/driver +# key: ${{ runner.os }}-drivers-${{ hashFiles('scripts/*') }} +# restore-keys: ${{ runner.os }}-drivers - name: Download drivers shell: bash run: scripts/download_driver_for_all_platforms.sh diff --git a/driver-bundle/src/main/java/com/microsoft/playwright/impl/DriverJar.java b/driver-bundle/src/main/java/com/microsoft/playwright/impl/DriverJar.java index f93e3b77..3945c0da 100644 --- a/driver-bundle/src/main/java/com/microsoft/playwright/impl/DriverJar.java +++ b/driver-bundle/src/main/java/com/microsoft/playwright/impl/DriverJar.java @@ -37,7 +37,7 @@ public class DriverJar extends Driver { String cliFileName = super.cliFileName(); Path driver = driverTempDir.resolve(cliFileName); if (!Files.exists(driver)) { - throw new RuntimeException("Failed to find playwright-cli"); + throw new RuntimeException("Failed to find " + cliFileName + " at " + driver); } ProcessBuilder pb = new ProcessBuilder(driver.toString(), "install"); pb.redirectError(ProcessBuilder.Redirect.INHERIT); @@ -50,14 +50,30 @@ public class DriverJar extends Driver { } } + private static boolean isExecutable(Path filePath) { + String name = filePath.getFileName().toString(); + return name.endsWith(".sh") || name.endsWith(".exe") || !name.contains("."); + } + private void extractDriverToTempDir() throws URISyntaxException, IOException { ClassLoader classloader = Thread.currentThread().getContextClassLoader(); URI uri = classloader.getResource("driver/" + platformDir()).toURI(); // Create zip filesystem if loading from jar. try (FileSystem fileSystem = "jar".equals(uri.getScheme()) ? FileSystems.newFileSystem(uri, Collections.emptyMap()) : null) { - Files.list(Paths.get(uri)).forEach(filePath -> { + Path srcRoot = Paths.get(uri); + Files.walk(srcRoot).forEach(fromPath -> { + Path relative = srcRoot.relativize(fromPath); + Path toPath = driverTempDir.resolve(relative.toString()); try { - extractResource(filePath, driverTempDir); + if (Files.isDirectory(fromPath)) { + Files.createDirectories(toPath); + } else { + Files.copy(fromPath, toPath); + if (isExecutable(toPath)) { + toPath.toFile().setExecutable(true, true); + } + } + toPath.toFile().deleteOnExit(); } catch (IOException e) { throw new RuntimeException("Failed to extract driver from " + uri, e); } @@ -79,14 +95,6 @@ public class DriverJar extends Driver { throw new RuntimeException("Unexpected os.name value: " + name); } - private static Path extractResource(Path from, Path toDir) throws IOException { - Path path = toDir.resolve(from.getFileName().toString()); - Files.copy(from, path); - path.toFile().setExecutable(true); - path.toFile().deleteOnExit(); - return path; - } - @Override Path driverDir() { return driverTempDir; diff --git a/driver-bundle/src/test/java/com/microsoft/playwright/TestInstall.java b/driver-bundle/src/test/java/com/microsoft/playwright/TestInstall.java index d829a5fe..6c28f71b 100644 --- a/driver-bundle/src/test/java/com/microsoft/playwright/TestInstall.java +++ b/driver-bundle/src/test/java/com/microsoft/playwright/TestInstall.java @@ -23,6 +23,7 @@ import java.nio.file.Files; import java.nio.file.Path; import java.util.concurrent.TimeUnit; +import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertTrue; public class TestInstall { @@ -30,14 +31,19 @@ public class TestInstall { void playwrightCliInstalled() throws Exception { // Clear system property to ensure that the driver is loaded from jar. System.clearProperty("playwright.cli.dir"); - Path cli = Driver.ensureDriverInstalled(); - assertTrue(Files.exists(cli)); + try { + Path cli = Driver.ensureDriverInstalled(); + assertTrue(Files.exists(cli)); - ProcessBuilder pb = new ProcessBuilder(cli.toString(), "install"); - pb.redirectError(ProcessBuilder.Redirect.INHERIT); - pb.redirectOutput(ProcessBuilder.Redirect.INHERIT); - Process p = pb.start(); - boolean result = p.waitFor(1, TimeUnit.MINUTES); - assertTrue(result, "Timed out waiting for browsers to install"); + ProcessBuilder pb = new ProcessBuilder(cli.toString(), "install"); + pb.redirectError(ProcessBuilder.Redirect.INHERIT); + pb.redirectOutput(ProcessBuilder.Redirect.INHERIT); + Process p = pb.start(); + boolean result = p.waitFor(1, TimeUnit.MINUTES); + assertTrue(result, "Timed out waiting for browsers to install"); + } catch (Exception e) { + e.printStackTrace(); + assertNull(e); + } } } diff --git a/driver/src/main/java/com/microsoft/playwright/impl/Driver.java b/driver/src/main/java/com/microsoft/playwright/impl/Driver.java index 3eebd491..223b7f1b 100644 --- a/driver/src/main/java/com/microsoft/playwright/impl/Driver.java +++ b/driver/src/main/java/com/microsoft/playwright/impl/Driver.java @@ -52,7 +52,7 @@ public abstract class Driver { protected String cliFileName() { return System.getProperty("os.name").toLowerCase().contains("windows") ? - "playwright-cli.exe" : "playwright-cli"; + "playwright.cmd" : "playwright.sh"; } private static Driver createDriver() throws Exception { diff --git a/examples/pom.xml b/examples/pom.xml index a9d722cd..d736d7c3 100644 --- a/examples/pom.xml +++ b/examples/pom.xml @@ -15,7 +15,7 @@ com.microsoft.playwright playwright - 0.171.0 + 0.180.0-SNAPSHOT diff --git a/playwright/src/main/java/com/microsoft/playwright/Accessibility.java b/playwright/src/main/java/com/microsoft/playwright/Accessibility.java index a4be4990..94cac91d 100644 --- a/playwright/src/main/java/com/microsoft/playwright/Accessibility.java +++ b/playwright/src/main/java/com/microsoft/playwright/Accessibility.java @@ -19,13 +19,25 @@ package com.microsoft.playwright; import java.util.*; /** - * The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as screen readers or switches. + * The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by *

- * Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output. + * assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or *

- * Blink - Chromium's rendering engine - has a concept of "accessibility tree", which is then translated into different platform-specific APIs. Accessibility namespace gives users access to the Blink Accessibility Tree. + * [switches](https://en.wikipedia.org/wiki/Switch_access). *

- * Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or by assistive technologies themselves. By default, Playwright tries to approximate this filtering, exposing only the "interesting" nodes of the tree. + * Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might + *

+ * have wildly different output. + *

+ * Blink - Chromium's rendering engine - has a concept of "accessibility tree", which is then translated into different + *

+ * platform-specific APIs. Accessibility namespace gives users access to the Blink Accessibility Tree. + *

+ * Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or by + *

+ * assistive technologies themselves. By default, Playwright tries to approximate this filtering, exposing only the + *

+ * "interesting" nodes of the tree. */ public interface Accessibility { class SnapshotOptions { @@ -51,9 +63,17 @@ public interface Accessibility { return snapshot(null); } /** - * Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page. + * Captures the current state of the accessibility tree. The returned object represents the root accessible node of the *

- * NOTE The Chromium accessibility tree contains nodes that go unused on most platforms and by most screen readers. Playwright will discard them as well for an easier to process tree, unless {@code interestingOnly} is set to {@code false}. + * page. + *

+ * > NOTE The Chromium accessibility tree contains nodes that go unused on most platforms and by most screen readers. + *

+ * Playwright will discard them as well for an easier to process tree, unless {@code interestingOnly} is set to {@code false}. + *

+ * + *

+ * *

*/ AccessibilityNode snapshot(SnapshotOptions options); diff --git a/playwright/src/main/java/com/microsoft/playwright/Browser.java b/playwright/src/main/java/com/microsoft/playwright/Browser.java index 5e415c77..3564ca55 100644 --- a/playwright/src/main/java/com/microsoft/playwright/Browser.java +++ b/playwright/src/main/java/com/microsoft/playwright/Browser.java @@ -20,8 +20,19 @@ import java.nio.file.Path; import java.util.*; /** - * A Browser is created when Playwright connects to a browser instance, either through {@code browserType.launch([options])} or {@code browserType.connect(params)}. + * - extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) *

+ * A Browser is created when Playwright connects to a browser instance, either through [{@code method: BrowserType.launch}] or + *

+ * [{@code method: BrowserType.connect}]. + *

+ * + *

+ * See {@code ChromiumBrowser}, [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that + *

+ * [{@code method: BrowserType.connect}] and [{@code method: BrowserType.launch}] always return a specific browser instance, based on + *

+ * the browser being connected to or launched. */ public interface Browser { class VideoSize { @@ -49,59 +60,10 @@ public interface Browser { void addListener(EventType type, Listener listener); void removeListener(EventType type, Listener listener); class NewContextOptions { - public class RecordHar { - /** - * Optional setting to control whether to omit request content from the HAR. Defaults to {@code false}. - */ - public Boolean omitContent; - /** - * Path on the filesystem to write the HAR file to. - */ - public Path path; - - RecordHar() { - } - public NewContextOptions done() { - return NewContextOptions.this; - } - - public RecordHar withOmitContent(Boolean omitContent) { - this.omitContent = omitContent; - return this; - } - public RecordHar withPath(Path path) { - this.path = path; - return this; - } - } - public class RecordVideo { - /** - * Path to the directory to put videos into. - */ - public Path dir; - /** - * Optional dimensions of the recorded videos. If not specified the size will be equal to {@code viewport}. If {@code viewport} is not configured explicitly the video size defaults to 1280x720. Actual picture of each page will be scaled down if necessary to fit the specified size. - */ - public VideoSize size; - - RecordVideo() { - } - public NewContextOptions done() { - return NewContextOptions.this; - } - - public RecordVideo withDir(Path dir) { - this.dir = dir; - return this; - } - public RecordVideo withSize(int width, int height) { - this.size = new VideoSize(width, height); - return this; - } - } public class Proxy { /** - * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example {@code http://myproxy.com:3128} or {@code socks5://myproxy.com:3128}. Short form {@code myproxy.com:3128} is considered an HTTP proxy. + * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example {@code http://myproxy.com:3128} or + * {@code socks5://myproxy.com:3128}. Short form {@code myproxy.com:3128} is considered an HTTP proxy. */ public String server; /** @@ -140,157 +102,213 @@ public interface Browser { return this; } } + public class RecordHar { + /** + * Optional setting to control whether to omit request content from the HAR. Defaults to {@code false}. + */ + public Boolean omitContent; + /** + * Path on the filesystem to write the HAR file to. + */ + public Path path; + + RecordHar() { + } + public NewContextOptions done() { + return NewContextOptions.this; + } + + public RecordHar withOmitContent(Boolean omitContent) { + this.omitContent = omitContent; + return this; + } + public RecordHar withPath(Path path) { + this.path = path; + return this; + } + } + public class RecordVideo { + /** + * Path to the directory to put videos into. + */ + public Path dir; + /** + * Optional dimensions of the recorded videos. If not specified the size will be equal to {@code viewport}. If {@code viewport} is not + * configured explicitly the video size defaults to 1280x720. Actual picture of each page will be scaled down if necessary + * to fit the specified size. + */ + public VideoSize size; + + RecordVideo() { + } + public NewContextOptions done() { + return NewContextOptions.this; + } + + public RecordVideo withDir(Path dir) { + this.dir = dir; + return this; + } + public RecordVideo withSize(int width, int height) { + this.size = new VideoSize(width, height); + return this; + } + } /** * Whether to automatically download all the attachments. Defaults to {@code false} where all the downloads are canceled. */ public Boolean acceptDownloads; - /** - * Whether to ignore HTTPS errors during navigation. Defaults to {@code false}. - */ - public Boolean ignoreHTTPSErrors; /** * Toggles bypassing page's Content-Security-Policy. */ public Boolean bypassCSP; /** - * Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. {@code null} disables the default viewport. + * Emulates {@code 'prefers-colors-scheme'} media feature, supported values are {@code 'light'}, {@code 'dark'}, {@code 'no-preference'}. See + * [{@code method: Page.emulateMedia}] for more details. Defaults to '{@code light}'. */ - public Page.Viewport viewport; - /** - * Specific user agent to use in this context. - */ - public String userAgent; + public ColorScheme colorScheme; /** * Specify device scale factor (can be thought of as dpr). Defaults to {@code 1}. */ - public Integer deviceScaleFactor; + public Double deviceScaleFactor; /** - * Whether the {@code meta viewport} tag is taken into account and touch events are enabled. Defaults to {@code false}. Not supported in Firefox. + * An object containing additional HTTP headers to be sent with every request. All header values must be strings. */ - public Boolean isMobile; + public Map extraHTTPHeaders; + public Geolocation geolocation; /** * Specifies if viewport supports touch events. Defaults to false. */ public Boolean hasTouch; + /** + * Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). + */ + public BrowserContext.HTTPCredentials httpCredentials; + /** + * Whether to ignore HTTPS errors during navigation. Defaults to {@code false}. + */ + public Boolean ignoreHTTPSErrors; + /** + * Whether the {@code meta viewport} tag is taken into account and touch events are enabled. Defaults to {@code false}. Not supported + * in Firefox. + */ + public Boolean isMobile; /** * Whether or not to enable JavaScript in the context. Defaults to {@code true}. */ public Boolean javaScriptEnabled; /** - * Changes the timezone of the context. See ICU’s {@code metaZones.txt} for a list of supported timezone IDs. - */ - public String timezoneId; - public Geolocation geolocation; - /** - * Specify user locale, for example {@code en-GB}, {@code de-DE}, etc. Locale will affect {@code navigator.language} value, {@code Accept-Language} request header value as well as number and date formatting rules. + * Specify user locale, for example {@code en-GB}, {@code de-DE}, etc. Locale will affect {@code navigator.language} value, {@code Accept-Language} + * request header value as well as number and date formatting rules. */ public String locale; - /** - * A list of permissions to grant to all pages in this context. See {@code browserContext.grantPermissions(permissions[, options])} for more details. - */ - public List permissions; - /** - * An object containing additional HTTP headers to be sent with every request. All header values must be strings. - */ - public Map extraHTTPHeaders; /** * Whether to emulate network being offline. Defaults to {@code false}. */ public Boolean offline; /** - * Credentials for HTTP authentication. + * A list of permissions to grant to all pages in this context. See [{@code method: BrowserContext.grantPermissions}] for more + * details. */ - public BrowserContext.HTTPCredentials httpCredentials; + public List permissions; /** - * Emulates {@code 'prefers-colors-scheme'} media feature, supported values are {@code 'light'}, {@code 'dark'}, {@code 'no-preference'}. See {@code page.emulateMedia(params)} for more details. Defaults to '{@code light}'. - */ - public ColorScheme colorScheme; - /** - * Enables HAR recording for all pages into {@code recordHar.path} file. If not specified, the HAR is not recorded. Make sure to await {@code browserContext.close()} for the HAR to be saved. - */ - public RecordHar recordHar; - /** - * Enables video recording for all pages into {@code recordVideo.dir} directory. If not specified videos are not recorded. Make sure to await {@code browserContext.close()} for videos to be saved. - */ - public RecordVideo recordVideo; - /** - * Network proxy settings to use with this context. Note that browser needs to be launched with the global proxy for this option to work. If all contexts override the proxy, global proxy will be never used and can be any string, for example {@code launch({ proxy: { server: 'per-context' } })}. + * Network proxy settings to use with this context. Note that browser needs to be launched with the global proxy for this + * option to work. If all contexts override the proxy, global proxy will be never used and can be any string, for example + * {@code launch({ proxy: { server: 'per-context' } })}. */ public Proxy proxy; /** - * Populates context with given storage state. This method can be used to initialize context with logged-in information obtained via {@code browserContext.storageState([options])}. Either a path to the file with saved storage, or an object with the following fields: + * Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into {@code recordHar.path} file. If not + * specified, the HAR is not recorded. Make sure to await [{@code method: BrowserContext.close}] for the HAR to be saved. + */ + public RecordHar recordHar; + /** + * Enables video recording for all pages into {@code recordVideo.dir} directory. If not specified videos are not recorded. Make + * sure to await [{@code method: BrowserContext.close}] for videos to be saved. + */ + public RecordVideo recordVideo; + /** + * Populates context with given storage state. This method can be used to initialize context with logged-in information + * obtained via [{@code method: BrowserContext.storageState}]. Either a path to the file with saved storage, or an object with + * the following fields: */ public BrowserContext.StorageState storageState; public Path storageStatePath; + /** + * Changes the timezone of the context. See + * [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) + * for a list of supported timezone IDs. + */ + public String timezoneId; + /** + * Specific user agent to use in this context. + */ + public String userAgent; + /** + * Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. {@code null} disables the default viewport. + */ + public Page.Viewport viewport; public NewContextOptions withAcceptDownloads(Boolean acceptDownloads) { this.acceptDownloads = acceptDownloads; return this; } - public NewContextOptions withIgnoreHTTPSErrors(Boolean ignoreHTTPSErrors) { - this.ignoreHTTPSErrors = ignoreHTTPSErrors; - return this; - } public NewContextOptions withBypassCSP(Boolean bypassCSP) { this.bypassCSP = bypassCSP; return this; } - public NewContextOptions withViewport(int width, int height) { - this.viewport = new Page.Viewport(width, height); + public NewContextOptions withColorScheme(ColorScheme colorScheme) { + this.colorScheme = colorScheme; return this; } - public NewContextOptions withUserAgent(String userAgent) { - this.userAgent = userAgent; - return this; - } - public NewContextOptions withDeviceScaleFactor(Integer deviceScaleFactor) { + public NewContextOptions withDeviceScaleFactor(Double deviceScaleFactor) { this.deviceScaleFactor = deviceScaleFactor; return this; } - public NewContextOptions withIsMobile(Boolean isMobile) { - this.isMobile = isMobile; - return this; - } - public NewContextOptions withHasTouch(Boolean hasTouch) { - this.hasTouch = hasTouch; - return this; - } - public NewContextOptions withJavaScriptEnabled(Boolean javaScriptEnabled) { - this.javaScriptEnabled = javaScriptEnabled; - return this; - } - public NewContextOptions withTimezoneId(String timezoneId) { - this.timezoneId = timezoneId; - return this; - } - public NewContextOptions withGeolocation(Geolocation geolocation) { - this.geolocation = geolocation; - return this; - } - public NewContextOptions withLocale(String locale) { - this.locale = locale; - return this; - } - public NewContextOptions withPermissions(List permissions) { - this.permissions = permissions; - return this; - } public NewContextOptions withExtraHTTPHeaders(Map extraHTTPHeaders) { this.extraHTTPHeaders = extraHTTPHeaders; return this; } - public NewContextOptions withOffline(Boolean offline) { - this.offline = offline; + public NewContextOptions withGeolocation(Geolocation geolocation) { + this.geolocation = geolocation; + return this; + } + public NewContextOptions withHasTouch(Boolean hasTouch) { + this.hasTouch = hasTouch; return this; } public NewContextOptions withHttpCredentials(String username, String password) { this.httpCredentials = new BrowserContext.HTTPCredentials(username, password); return this; } - public NewContextOptions withColorScheme(ColorScheme colorScheme) { - this.colorScheme = colorScheme; + public NewContextOptions withIgnoreHTTPSErrors(Boolean ignoreHTTPSErrors) { + this.ignoreHTTPSErrors = ignoreHTTPSErrors; return this; } + public NewContextOptions withIsMobile(Boolean isMobile) { + this.isMobile = isMobile; + return this; + } + public NewContextOptions withJavaScriptEnabled(Boolean javaScriptEnabled) { + this.javaScriptEnabled = javaScriptEnabled; + return this; + } + public NewContextOptions withLocale(String locale) { + this.locale = locale; + return this; + } + public NewContextOptions withOffline(Boolean offline) { + this.offline = offline; + return this; + } + public NewContextOptions withPermissions(List permissions) { + this.permissions = permissions; + return this; + } + public Proxy setProxy() { + this.proxy = new Proxy(); + return this.proxy; + } public RecordHar setRecordHar() { this.recordHar = new RecordHar(); return this.recordHar; @@ -299,10 +317,6 @@ public interface Browser { this.recordVideo = new RecordVideo(); return this.recordVideo; } - public Proxy setProxy() { - this.proxy = new Proxy(); - return this.proxy; - } public NewContextOptions withStorageState(BrowserContext.StorageState storageState) { this.storageState = storageState; this.storageStatePath = null; @@ -313,6 +327,18 @@ public interface Browser { this.storageStatePath = storageStatePath; return this; } + public NewContextOptions withTimezoneId(String timezoneId) { + this.timezoneId = timezoneId; + return this; + } + public NewContextOptions withUserAgent(String userAgent) { + this.userAgent = userAgent; + return this; + } + public NewContextOptions withViewport(int width, int height) { + this.viewport = new Page.Viewport(width, height); + return this; + } public NewContextOptions withDevice(DeviceDescriptor device) { withViewport(device.viewport().width(), device.viewport().height()); withUserAgent(device.userAgent()); @@ -323,59 +349,10 @@ public interface Browser { } } class NewPageOptions { - public class RecordHar { - /** - * Optional setting to control whether to omit request content from the HAR. Defaults to {@code false}. - */ - public Boolean omitContent; - /** - * Path on the filesystem to write the HAR file to. - */ - public Path path; - - RecordHar() { - } - public NewPageOptions done() { - return NewPageOptions.this; - } - - public RecordHar withOmitContent(Boolean omitContent) { - this.omitContent = omitContent; - return this; - } - public RecordHar withPath(Path path) { - this.path = path; - return this; - } - } - public class RecordVideo { - /** - * Path to the directory to put videos into. - */ - public Path dir; - /** - * Optional dimensions of the recorded videos. If not specified the size will be equal to {@code viewport}. If {@code viewport} is not configured explicitly the video size defaults to 1280x720. Actual picture of each page will be scaled down if necessary to fit the specified size. - */ - public VideoSize size; - - RecordVideo() { - } - public NewPageOptions done() { - return NewPageOptions.this; - } - - public RecordVideo withDir(Path dir) { - this.dir = dir; - return this; - } - public RecordVideo withSize(int width, int height) { - this.size = new VideoSize(width, height); - return this; - } - } public class Proxy { /** - * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example {@code http://myproxy.com:3128} or {@code socks5://myproxy.com:3128}. Short form {@code myproxy.com:3128} is considered an HTTP proxy. + * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example {@code http://myproxy.com:3128} or + * {@code socks5://myproxy.com:3128}. Short form {@code myproxy.com:3128} is considered an HTTP proxy. */ public String server; /** @@ -414,157 +391,213 @@ public interface Browser { return this; } } + public class RecordHar { + /** + * Optional setting to control whether to omit request content from the HAR. Defaults to {@code false}. + */ + public Boolean omitContent; + /** + * Path on the filesystem to write the HAR file to. + */ + public Path path; + + RecordHar() { + } + public NewPageOptions done() { + return NewPageOptions.this; + } + + public RecordHar withOmitContent(Boolean omitContent) { + this.omitContent = omitContent; + return this; + } + public RecordHar withPath(Path path) { + this.path = path; + return this; + } + } + public class RecordVideo { + /** + * Path to the directory to put videos into. + */ + public Path dir; + /** + * Optional dimensions of the recorded videos. If not specified the size will be equal to {@code viewport}. If {@code viewport} is not + * configured explicitly the video size defaults to 1280x720. Actual picture of each page will be scaled down if necessary + * to fit the specified size. + */ + public VideoSize size; + + RecordVideo() { + } + public NewPageOptions done() { + return NewPageOptions.this; + } + + public RecordVideo withDir(Path dir) { + this.dir = dir; + return this; + } + public RecordVideo withSize(int width, int height) { + this.size = new VideoSize(width, height); + return this; + } + } /** * Whether to automatically download all the attachments. Defaults to {@code false} where all the downloads are canceled. */ public Boolean acceptDownloads; - /** - * Whether to ignore HTTPS errors during navigation. Defaults to {@code false}. - */ - public Boolean ignoreHTTPSErrors; /** * Toggles bypassing page's Content-Security-Policy. */ public Boolean bypassCSP; /** - * Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. {@code null} disables the default viewport. + * Emulates {@code 'prefers-colors-scheme'} media feature, supported values are {@code 'light'}, {@code 'dark'}, {@code 'no-preference'}. See + * [{@code method: Page.emulateMedia}] for more details. Defaults to '{@code light}'. */ - public Page.Viewport viewport; - /** - * Specific user agent to use in this context. - */ - public String userAgent; + public ColorScheme colorScheme; /** * Specify device scale factor (can be thought of as dpr). Defaults to {@code 1}. */ - public Integer deviceScaleFactor; + public Double deviceScaleFactor; /** - * Whether the {@code meta viewport} tag is taken into account and touch events are enabled. Defaults to {@code false}. Not supported in Firefox. + * An object containing additional HTTP headers to be sent with every request. All header values must be strings. */ - public Boolean isMobile; + public Map extraHTTPHeaders; + public Geolocation geolocation; /** * Specifies if viewport supports touch events. Defaults to false. */ public Boolean hasTouch; + /** + * Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). + */ + public BrowserContext.HTTPCredentials httpCredentials; + /** + * Whether to ignore HTTPS errors during navigation. Defaults to {@code false}. + */ + public Boolean ignoreHTTPSErrors; + /** + * Whether the {@code meta viewport} tag is taken into account and touch events are enabled. Defaults to {@code false}. Not supported + * in Firefox. + */ + public Boolean isMobile; /** * Whether or not to enable JavaScript in the context. Defaults to {@code true}. */ public Boolean javaScriptEnabled; /** - * Changes the timezone of the context. See ICU’s {@code metaZones.txt} for a list of supported timezone IDs. - */ - public String timezoneId; - public Geolocation geolocation; - /** - * Specify user locale, for example {@code en-GB}, {@code de-DE}, etc. Locale will affect {@code navigator.language} value, {@code Accept-Language} request header value as well as number and date formatting rules. + * Specify user locale, for example {@code en-GB}, {@code de-DE}, etc. Locale will affect {@code navigator.language} value, {@code Accept-Language} + * request header value as well as number and date formatting rules. */ public String locale; - /** - * A list of permissions to grant to all pages in this context. See {@code browserContext.grantPermissions(permissions[, options])} for more details. - */ - public List permissions; - /** - * An object containing additional HTTP headers to be sent with every request. All header values must be strings. - */ - public Map extraHTTPHeaders; /** * Whether to emulate network being offline. Defaults to {@code false}. */ public Boolean offline; /** - * Credentials for HTTP authentication. + * A list of permissions to grant to all pages in this context. See [{@code method: BrowserContext.grantPermissions}] for more + * details. */ - public BrowserContext.HTTPCredentials httpCredentials; + public List permissions; /** - * Emulates {@code 'prefers-colors-scheme'} media feature, supported values are {@code 'light'}, {@code 'dark'}, {@code 'no-preference'}. See {@code page.emulateMedia(params)} for more details. Defaults to '{@code light}'. - */ - public ColorScheme colorScheme; - /** - * Enables HAR recording for all pages into {@code recordHar.path} file. If not specified, the HAR is not recorded. Make sure to await {@code browserContext.close()} for the HAR to be saved. - */ - public RecordHar recordHar; - /** - * Enables video recording for all pages into {@code recordVideo.dir} directory. If not specified videos are not recorded. Make sure to await {@code browserContext.close()} for videos to be saved. - */ - public RecordVideo recordVideo; - /** - * Network proxy settings to use with this context. Note that browser needs to be launched with the global proxy for this option to work. If all contexts override the proxy, global proxy will be never used and can be any string, for example {@code launch({ proxy: { server: 'per-context' } })}. + * Network proxy settings to use with this context. Note that browser needs to be launched with the global proxy for this + * option to work. If all contexts override the proxy, global proxy will be never used and can be any string, for example + * {@code launch({ proxy: { server: 'per-context' } })}. */ public Proxy proxy; /** - * Populates context with given storage state. This method can be used to initialize context with logged-in information obtained via {@code browserContext.storageState([options])}. Either a path to the file with saved storage, or an object with the following fields: + * Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into {@code recordHar.path} file. If not + * specified, the HAR is not recorded. Make sure to await [{@code method: BrowserContext.close}] for the HAR to be saved. + */ + public RecordHar recordHar; + /** + * Enables video recording for all pages into {@code recordVideo.dir} directory. If not specified videos are not recorded. Make + * sure to await [{@code method: BrowserContext.close}] for videos to be saved. + */ + public RecordVideo recordVideo; + /** + * Populates context with given storage state. This method can be used to initialize context with logged-in information + * obtained via [{@code method: BrowserContext.storageState}]. Either a path to the file with saved storage, or an object with + * the following fields: */ public BrowserContext.StorageState storageState; public Path storageStatePath; + /** + * Changes the timezone of the context. See + * [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) + * for a list of supported timezone IDs. + */ + public String timezoneId; + /** + * Specific user agent to use in this context. + */ + public String userAgent; + /** + * Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. {@code null} disables the default viewport. + */ + public Page.Viewport viewport; public NewPageOptions withAcceptDownloads(Boolean acceptDownloads) { this.acceptDownloads = acceptDownloads; return this; } - public NewPageOptions withIgnoreHTTPSErrors(Boolean ignoreHTTPSErrors) { - this.ignoreHTTPSErrors = ignoreHTTPSErrors; - return this; - } public NewPageOptions withBypassCSP(Boolean bypassCSP) { this.bypassCSP = bypassCSP; return this; } - public NewPageOptions withViewport(int width, int height) { - this.viewport = new Page.Viewport(width, height); + public NewPageOptions withColorScheme(ColorScheme colorScheme) { + this.colorScheme = colorScheme; return this; } - public NewPageOptions withUserAgent(String userAgent) { - this.userAgent = userAgent; - return this; - } - public NewPageOptions withDeviceScaleFactor(Integer deviceScaleFactor) { + public NewPageOptions withDeviceScaleFactor(Double deviceScaleFactor) { this.deviceScaleFactor = deviceScaleFactor; return this; } - public NewPageOptions withIsMobile(Boolean isMobile) { - this.isMobile = isMobile; - return this; - } - public NewPageOptions withHasTouch(Boolean hasTouch) { - this.hasTouch = hasTouch; - return this; - } - public NewPageOptions withJavaScriptEnabled(Boolean javaScriptEnabled) { - this.javaScriptEnabled = javaScriptEnabled; - return this; - } - public NewPageOptions withTimezoneId(String timezoneId) { - this.timezoneId = timezoneId; - return this; - } - public NewPageOptions withGeolocation(Geolocation geolocation) { - this.geolocation = geolocation; - return this; - } - public NewPageOptions withLocale(String locale) { - this.locale = locale; - return this; - } - public NewPageOptions withPermissions(List permissions) { - this.permissions = permissions; - return this; - } public NewPageOptions withExtraHTTPHeaders(Map extraHTTPHeaders) { this.extraHTTPHeaders = extraHTTPHeaders; return this; } - public NewPageOptions withOffline(Boolean offline) { - this.offline = offline; + public NewPageOptions withGeolocation(Geolocation geolocation) { + this.geolocation = geolocation; + return this; + } + public NewPageOptions withHasTouch(Boolean hasTouch) { + this.hasTouch = hasTouch; return this; } public NewPageOptions withHttpCredentials(String username, String password) { this.httpCredentials = new BrowserContext.HTTPCredentials(username, password); return this; } - public NewPageOptions withColorScheme(ColorScheme colorScheme) { - this.colorScheme = colorScheme; + public NewPageOptions withIgnoreHTTPSErrors(Boolean ignoreHTTPSErrors) { + this.ignoreHTTPSErrors = ignoreHTTPSErrors; return this; } + public NewPageOptions withIsMobile(Boolean isMobile) { + this.isMobile = isMobile; + return this; + } + public NewPageOptions withJavaScriptEnabled(Boolean javaScriptEnabled) { + this.javaScriptEnabled = javaScriptEnabled; + return this; + } + public NewPageOptions withLocale(String locale) { + this.locale = locale; + return this; + } + public NewPageOptions withOffline(Boolean offline) { + this.offline = offline; + return this; + } + public NewPageOptions withPermissions(List permissions) { + this.permissions = permissions; + return this; + } + public Proxy setProxy() { + this.proxy = new Proxy(); + return this.proxy; + } public RecordHar setRecordHar() { this.recordHar = new RecordHar(); return this.recordHar; @@ -573,10 +606,6 @@ public interface Browser { this.recordVideo = new RecordVideo(); return this.recordVideo; } - public Proxy setProxy() { - this.proxy = new Proxy(); - return this.proxy; - } public NewPageOptions withStorageState(BrowserContext.StorageState storageState) { this.storageState = storageState; this.storageStatePath = null; @@ -587,6 +616,18 @@ public interface Browser { this.storageStatePath = storageStatePath; return this; } + public NewPageOptions withTimezoneId(String timezoneId) { + this.timezoneId = timezoneId; + return this; + } + public NewPageOptions withUserAgent(String userAgent) { + this.userAgent = userAgent; + return this; + } + public NewPageOptions withViewport(int width, int height) { + this.viewport = new Page.Viewport(width, height); + return this; + } public NewPageOptions withDevice(DeviceDescriptor device) { withViewport(device.viewport().width(), device.viewport().height()); withUserAgent(device.userAgent()); @@ -597,16 +638,22 @@ public interface Browser { } } /** - * In case this browser is obtained using {@code browserType.launch([options])}, closes the browser and all of its pages (if any were opened). + * In case this browser is obtained using [{@code method: BrowserType.launch}], closes the browser and all of its pages (if any *

- * In case this browser is obtained using {@code browserType.connect(params)}, clears all created contexts belonging to this browser and disconnects from the browser server. + * were opened). *

- * The Browser object itself is considered to be disposed and cannot be used anymore. + * In case this browser is obtained using [{@code method: BrowserType.connect}], clears all created contexts belonging to this + *

+ * browser and disconnects from the browser server. + *

+ * The {@code Browser} object itself is considered to be disposed and cannot be used anymore. */ void close(); /** * Returns an array of all open browser contexts. In a newly created browser, this will return zero browser contexts. *

+ * + *

*/ List contexts(); /** @@ -619,6 +666,8 @@ public interface Browser { /** * Creates a new browser context. It won't share cookies/cache with other browser contexts. *

+ * + *

*/ BrowserContext newContext(NewContextOptions options); default Page newPage() { @@ -627,7 +676,11 @@ public interface Browser { /** * Creates a new page in a new browser context. Closing this page will close the context as well. *

- * This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and testing frameworks should explicitly create {@code browser.newContext([options])} followed by the {@code browserContext.newPage()} to control their exact life times. + * This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and + *

+ * testing frameworks should explicitly create [{@code method: Browser.newContext}] followed by the + *

+ * [{@code method: BrowserContext.newPage}] to control their exact life times. */ Page newPage(NewPageOptions options); /** diff --git a/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java b/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java index e23d5bad..02715bde 100644 --- a/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java +++ b/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java @@ -23,11 +23,19 @@ import java.util.function.Predicate; import java.util.regex.Pattern; /** + * - extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) + *

* BrowserContexts provide a way to operate multiple independent browser sessions. *

- * If a page opens another page, e.g. with a {@code window.open} call, the popup will belong to the parent page's browser context. + * If a page opens another page, e.g. with a {@code window.open} call, the popup will belong to the parent page's browser *

- * Playwright allows creation of "incognito" browser contexts with {@code browser.newContext()} method. "Incognito" browser contexts don't write any browsing data to disk. + * context. + *

+ * Playwright allows creation of "incognito" browser contexts with {@code browser.newContext()} method. "Incognito" browser + *

+ * contexts don't write any browsing data to disk. + *

+ * *

*/ public interface BrowserContext { @@ -121,23 +129,32 @@ public interface BrowserContext { */ public String value; /** - * either url or domain / path are required + * either url or domain / path are required. Optional. */ public String url; /** - * either url or domain / path are required + * either url or domain / path are required Optional. */ public String domain; /** - * either url or domain / path are required + * either url or domain / path are required Optional. */ public String path; /** - * Unix time in seconds. + * Unix time in seconds. Optional. */ public Long expires; + /** + * Optional. + */ public Boolean httpOnly; + /** + * Optional. + */ public Boolean secure; + /** + * Optional. + */ public SameSite sameSite; public AddCookie withName(String name) { @@ -217,7 +234,8 @@ public interface BrowserContext { } class ExposeBindingOptions { /** - * Whether to pass the argument as a handle, instead of passing by value. When passing a handle, only one argument is supported. When passing by value, multiple arguments are supported. + * Whether to pass the argument as a handle, instead of passing by value. When passing a handle, only one argument is + * supported. When passing by value, multiple arguments are supported. */ public Boolean handle; @@ -228,7 +246,7 @@ public interface BrowserContext { } class GrantPermissionsOptions { /** - * The origin to grant permissions to, e.g. "https://example.com". + * The [origin] to grant permissions to, e.g. "https://example.com". */ public String origin; @@ -239,7 +257,9 @@ public interface BrowserContext { } class StorageStateOptions { /** - * The file path to save the storage state to. If {@code path} is a relative path, then it is resolved relative to current working directory. If no path is provided, storage state is still returned, but won't be saved to the disk. + * The file path to save the storage state to. If {@code path} is a relative path, then it is resolved relative to + * [current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, storage + * state is still returned, but won't be saved to the disk. */ public Path path; @@ -249,7 +269,11 @@ public interface BrowserContext { } } /** - * Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be obtained via {@code browserContext.cookies([urls])}. + * Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be + *

+ * obtained via [{@code method: BrowserContext.cookies}]. + *

+ * *

*/ void addCookies(List cookies); @@ -259,15 +283,23 @@ public interface BrowserContext { /** * Adds a script which would be evaluated in one of the following scenarios: *

- * Whenever a page is created in the browser context or is navigated. + * - Whenever a page is created in the browser context or is navigated. *

- * Whenever a child frame is attached or navigated in any page in the browser context. In this case, the script is evaluated in the context of the newly attached frame. + * - Whenever a child frame is attached or navigated in any page in the browser context. In this case, the script is *

- * The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed {@code Math.random}. + * evaluated in the context of the newly attached frame. + *

+ * The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend + *

+ * the JavaScript environment, e.g. to seed {@code Math.random}. *

* *

- * NOTE The order of evaluation of multiple scripts installed via {@code browserContext.addInitScript(script[, arg])} and {@code page.addInitScript(script[, arg])} is not defined. + * + *

+ * > NOTE The order of evaluation of multiple scripts installed via [{@code method: BrowserContext.addInitScript}] and + *

+ * [{@code method: Page.addInitScript}] is not defined. * @param script Script to be evaluated in all pages in the browser context. * @param arg Optional argument to pass to {@code script} (only supported when passing a function). */ @@ -283,66 +315,90 @@ public interface BrowserContext { /** * Clears all permission overrides for the browser context. *

+ * + *

*/ void clearPermissions(); /** * Closes the browser context. All the pages that belong to the browser context will be closed. *

- * NOTE the default browser context cannot be closed. + * > NOTE the default browser context cannot be closed. */ void close(); default List cookies() { return cookies((List) null); } default List cookies(String url) { return cookies(Arrays.asList(url)); } /** - * If no URLs are specified, this method returns all cookies. If URLs are specified, only cookies that affect those URLs are returned. + * If no URLs are specified, this method returns all cookies. If URLs are specified, only cookies that affect those URLs + *

+ * are returned. * @param urls Optional list of URLs. */ List cookies(List urls); - default void exposeBinding(String name, Page.Binding playwrightBinding) { - exposeBinding(name, playwrightBinding, null); + default void exposeBinding(String name, Page.Binding callback) { + exposeBinding(name, callback, null); } /** - * The method adds a function called {@code name} on the {@code window} object of every frame in every page in the context. When called, the function executes {@code playwrightBinding} and returns a Promise which resolves to the return value of {@code playwrightBinding}. If the {@code playwrightBinding} returns a Promise, it will be awaited. + * The method adds a function called {@code name} on the {@code window} object of every frame in every page in the context. When *

- * The first argument of the {@code playwrightBinding} function contains information about the caller: {@code { browserContext: BrowserContext, page: Page, frame: Frame }}. + * called, the function executes {@code callback} and returns a [Promise] which resolves to the return value of {@code callback}. If *

- * See {@code page.exposeBinding(name, playwrightBinding[, options])} for page-only version. + * the {@code callback} returns a [Promise], it will be awaited. + *

+ * The first argument of the {@code callback} function contains information about the caller: `{ browserContext: BrowserContext, + *

+ * page: Page, frame: Frame }`. + *

+ * See [{@code method: Page.exposeBinding}] for page-only version. + *

+ * + *

+ * + *

+ * * @param name Name of the function on the window object. - * @param playwrightBinding Callback function that will be called in the Playwright's context. + * @param callback Callback function that will be called in the Playwright's context. */ - void exposeBinding(String name, Page.Binding playwrightBinding, ExposeBindingOptions options); + void exposeBinding(String name, Page.Binding callback, ExposeBindingOptions options); /** - * The method adds a function called {@code name} on the {@code window} object of every frame in every page in the context. When called, the function executes {@code playwrightFunction} and returns a Promise which resolves to the return value of {@code playwrightFunction}. + * The method adds a function called {@code name} on the {@code window} object of every frame in every page in the context. When *

- * If the {@code playwrightFunction} returns a Promise, it will be awaited. + * called, the function executes {@code callback} and returns a [Promise] which resolves to the return value of {@code callback}. *

- * See {@code page.exposeFunction(name, playwrightFunction)} for page-only version. + * If the {@code callback} returns a [Promise], it will be awaited. + *

+ * See [{@code method: Page.exposeFunction}] for page-only version. + *

+ * + *

+ * * @param name Name of the function on the window object. - * @param playwrightFunction Callback function that will be called in the Playwright's context. + * @param callback Callback function that will be called in the Playwright's context. */ - void exposeFunction(String name, Page.Function playwrightFunction); + void exposeFunction(String name, Page.Function callback); default void grantPermissions(List permissions) { grantPermissions(permissions, null); } /** - * Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if specified. + * Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if + *

+ * specified. * @param permissions A permission or an array of permissions to grant. Permissions can be one of the following values: - * - {@code 'geolocation'} - * - {@code 'midi'} - * - {@code 'midi-sysex'} (system-exclusive midi) - * - {@code 'notifications'} - * - {@code 'push'} - * - {@code 'camera'} - * - {@code 'microphone'} - * - {@code 'background-sync'} - * - {@code 'ambient-light-sensor'} - * - {@code 'accelerometer'} - * - {@code 'gyroscope'} - * - {@code 'magnetometer'} - * - {@code 'accessibility-events'} - * - {@code 'clipboard-read'} - * - {@code 'clipboard-write'} - * - {@code 'payment-handler'} + * - {@code 'geolocation'} + * - {@code 'midi'} + * - {@code 'midi-sysex'} (system-exclusive midi) + * - {@code 'notifications'} + * - {@code 'push'} + * - {@code 'camera'} + * - {@code 'microphone'} + * - {@code 'background-sync'} + * - {@code 'ambient-light-sensor'} + * - {@code 'accelerometer'} + * - {@code 'gyroscope'} + * - {@code 'magnetometer'} + * - {@code 'accessibility-events'} + * - {@code 'clipboard-read'} + * - {@code 'clipboard-write'} + * - {@code 'payment-handler'} */ void grantPermissions(List permissions, GrantPermissionsOptions options); /** @@ -350,55 +406,71 @@ public interface BrowserContext { */ Page newPage(); /** - * Returns all open pages in the context. Non visible pages, such as {@code "background_page"}, will not be listed here. You can find them using {@code chromiumBrowserContext.backgroundPages()}. + * Returns all open pages in the context. Non visible pages, such as {@code "background_page"}, will not be listed here. You can + *

+ * find them using [{@code method: ChromiumBrowserContext.backgroundPages}]. */ List pages(); void route(String url, Consumer handler); void route(Pattern url, Consumer handler); /** - * Routing provides the capability to modify network requests that are made by any page in the browser context. Once route is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted. + * Routing provides the capability to modify network requests that are made by any page in the browser context. Once route + *

+ * is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted. + *

+ * *

* or the same snippet using a regex pattern instead: *

- * Page routes (set up with {@code page.route(url, handler)}) take precedence over browser context routes when request matches both handlers. + * *

- * NOTE Enabling routing disables http cache. - * @param url A glob pattern, regex pattern or predicate receiving URL to match while routing. + * Page routes (set up with [{@code method: Page.route}]) take precedence over browser context routes when request matches both + *

+ * handlers. + *

+ * > NOTE Enabling routing disables http cache. + * @param url A glob pattern, regex pattern or predicate receiving [URL] to match while routing. * @param handler handler function to route the request. */ void route(Predicate url, Consumer handler); /** * This setting will change the default maximum navigation time for the following methods and related shortcuts: *

- * {@code page.goBack([options])} + * - [{@code method: Page.goBack}] *

- * {@code page.goForward([options])} + * - [{@code method: Page.goForward}] *

- * {@code page.goto(url[, options])} + * - [{@code method: Page.goto}] *

- * {@code page.reload([options])} + * - [{@code method: Page.reload}] *

- * {@code page.setContent(html[, options])} + * - [{@code method: Page.setContent}] *

- * {@code page.waitForNavigation([options])} + * - [{@code method: Page.waitForNavigation}] *

- * + * > NOTE [{@code method: Page.setDefaultNavigationTimeout}] and [{@code method: Page.setDefaultTimeout}] take priority over *

- * NOTE {@code page.setDefaultNavigationTimeout(timeout)} and {@code page.setDefaultTimeout(timeout)} take priority over {@code browserContext.setDefaultNavigationTimeout(timeout)}. + * [{@code method: BrowserContext.setDefaultNavigationTimeout}]. * @param timeout Maximum navigation time in milliseconds */ void setDefaultNavigationTimeout(int timeout); /** * This setting will change the default maximum time for all the methods accepting {@code timeout} option. *

- * NOTE {@code page.setDefaultNavigationTimeout(timeout)}, {@code page.setDefaultTimeout(timeout)} and {@code browserContext.setDefaultNavigationTimeout(timeout)} take priority over {@code browserContext.setDefaultTimeout(timeout)}. + * > NOTE [{@code method: Page.setDefaultNavigationTimeout}], [{@code method: Page.setDefaultTimeout}] and + *

+ * [{@code method: BrowserContext.setDefaultNavigationTimeout}] take priority over [{@code method: BrowserContext.setDefaultTimeout}]. * @param timeout Maximum time in milliseconds */ void setDefaultTimeout(int timeout); /** - * The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged with page-specific extra HTTP headers set with {@code page.setExtraHTTPHeaders(headers)}. If page overrides a particular header, page-specific header value will be used instead of the browser context header value. + * The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged *

- * NOTE {@code browserContext.setExtraHTTPHeaders} does not guarantee the order of headers in the outgoing requests. + * with page-specific extra HTTP headers set with [{@code method: Page.setExtraHTTPHeaders}]. If page overrides a particular + *

+ * header, page-specific header value will be used instead of the browser context header value. + *

+ * > NOTE {@code browserContext.setExtraHTTPHeaders} does not guarantee the order of headers in the outgoing requests. * @param headers An object containing additional HTTP headers to be sent with every request. All header values must be strings. */ void setExtraHTTPHeaders(Map headers); @@ -407,7 +479,9 @@ public interface BrowserContext { *

* *

- * NOTE Consider using {@code browserContext.grantPermissions(permissions[, options])} to grant permissions for the browser context pages to read its geolocation. + * > NOTE Consider using [{@code method: BrowserContext.grantPermissions}] to grant permissions for the browser context pages + *

+ * to read its geolocation. */ void setGeolocation(Geolocation geolocation); /** @@ -428,9 +502,12 @@ public interface BrowserContext { void unroute(String url, Consumer handler); void unroute(Pattern url, Consumer handler); /** - * Removes a route created with {@code browserContext.route(url, handler)}. When {@code handler} is not specified, removes all routes for the {@code url}. - * @param url A glob pattern, regex pattern or predicate receiving URL used to register a routing with {@code browserContext.route(url, handler)}. - * @param handler Optional handler function used to register a routing with {@code browserContext.route(url, handler)}. + * Removes a route created with [{@code method: BrowserContext.route}]. When {@code handler} is not specified, removes all routes for + *

+ * the {@code url}. + * @param url A glob pattern, regex pattern or predicate receiving [URL] used to register a routing with + * [{@code method: BrowserContext.route}]. + * @param handler Optional handler function used to register a routing with [{@code method: BrowserContext.route}]. */ void unroute(Predicate url, Consumer handler); default Deferred> futureEvent(EventType event) { @@ -442,7 +519,11 @@ public interface BrowserContext { return futureEvent(event, options); } /** - * Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will throw an error if the context closes before the event is fired. Returns the event data value. + * Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy + *

+ * value. Will throw an error if the context closes before the event is fired. Returns the event data value. + *

+ * *

* * @param event Event name, same one would pass into {@code browserContext.on(event)}. diff --git a/playwright/src/main/java/com/microsoft/playwright/BrowserType.java b/playwright/src/main/java/com/microsoft/playwright/BrowserType.java index ea625866..0237c235 100644 --- a/playwright/src/main/java/com/microsoft/playwright/BrowserType.java +++ b/playwright/src/main/java/com/microsoft/playwright/BrowserType.java @@ -20,14 +20,19 @@ import java.nio.file.Path; import java.util.*; /** - * BrowserType provides methods to launch a specific browser instance or connect to an existing one. The following is a typical example of using Playwright to drive automation: + * BrowserType provides methods to launch a specific browser instance or connect to an existing one. The following is a + *

+ * typical example of using Playwright to drive automation: + *

+ * *

*/ public interface BrowserType { class LaunchOptions { public class Proxy { /** - * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example {@code http://myproxy.com:3128} or {@code socks5://myproxy.com:3128}. Short form {@code myproxy.com:3128} is considered an HTTP proxy. + * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example {@code http://myproxy.com:3128} or + * {@code socks5://myproxy.com:3128}. Short form {@code myproxy.com:3128} is considered an HTTP proxy. */ public String server; /** @@ -67,38 +72,43 @@ public interface BrowserType { } } /** - * Whether to run browser in headless mode. More details for Chromium and Firefox. Defaults to {@code true} unless the {@code devtools} option is {@code true}. - */ - public Boolean headless; - /** - * Path to a browser executable to run instead of the bundled one. If {@code executablePath} is a relative path, then it is resolved relative to the current working directory. Note that Playwright only works with the bundled Chromium, Firefox or WebKit, use at your own risk. - */ - public Path executablePath; - /** - * Additional arguments to pass to the browser instance. The list of Chromium flags can be found here. + * Additional arguments to pass to the browser instance. The list of Chromium flags can be found + * [here](http://peter.sh/experiments/chromium-command-line-switches/). */ public List args; - /** - * If {@code true}, Playwright does not pass its own configurations args and only uses the ones from {@code args}. If an array is given, then filters out the given default arguments. Dangerous option; use with care. Defaults to {@code false}. - */ - public List ignoreDefaultArgs; - public Boolean ignoreAllDefaultArgs; - /** - * Network proxy settings. - */ - public Proxy proxy; - /** - * If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is deleted when browser is closed. - */ - public Path downloadsPath; /** * Enable Chromium sandboxing. Defaults to {@code false}. */ public Boolean chromiumSandbox; /** - * Firefox user preferences. Learn more about the Firefox user preferences at {@code about:config}. + * **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is {@code true}, the {@code headless} + * option will be set {@code false}. */ - public String firefoxUserPrefs; + public Boolean devtools; + /** + * If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is + * deleted when browser is closed. + */ + public Path downloadsPath; + /** + * Specify environment variables that will be visible to the browser. Defaults to {@code process.env}. + */ + public Map env; + /** + * Path to a browser executable to run instead of the bundled one. If {@code executablePath} is a relative path, then it is + * resolved relative to the current working directory. Note that Playwright only works with the bundled Chromium, Firefox + * or WebKit, use at your own risk. + */ + public Path executablePath; + /** + * Firefox user preferences. Learn more about the Firefox user preferences at + * [{@code about:config}](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). + */ + public Map firefoxUserPrefs; + /** + * Close the browser process on SIGHUP. Defaults to {@code true}. + */ + public Boolean handleSIGHUP; /** * Close the browser process on Ctrl-C. Defaults to {@code true}. */ @@ -108,36 +118,74 @@ public interface BrowserType { */ public Boolean handleSIGTERM; /** - * Close the browser process on SIGHUP. Defaults to {@code true}. + * Whether to run browser in headless mode. More details for + * [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and + * [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to {@code true} unless the + * {@code devtools} option is {@code true}. */ - public Boolean handleSIGHUP; + public Boolean headless; /** - * Maximum time in milliseconds to wait for the browser instance to start. Defaults to {@code 30000} (30 seconds). Pass {@code 0} to disable timeout. + * If {@code true}, Playwright does not pass its own configurations args and only uses the ones from {@code args}. If an array is + * given, then filters out the given default arguments. Dangerous option; use with care. Defaults to {@code false}. */ - public Integer timeout; + public List ignoreDefaultArgs; + public Boolean ignoreAllDefaultArgs; /** - * Specify environment variables that will be visible to the browser. Defaults to {@code process.env}. + * Network proxy settings. */ - public Map env; - /** - * **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is {@code true}, the {@code headless} option will be set {@code false}. - */ - public Boolean devtools; + public Proxy proxy; /** * Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. */ - public Integer slowMo; + public Double slowMo; + /** + * Maximum time in milliseconds to wait for the browser instance to start. Defaults to {@code 30000} (30 seconds). Pass {@code 0} to + * disable timeout. + */ + public Double timeout; - public LaunchOptions withHeadless(Boolean headless) { - this.headless = headless; + public LaunchOptions withArgs(List args) { + this.args = args; + return this; + } + public LaunchOptions withChromiumSandbox(Boolean chromiumSandbox) { + this.chromiumSandbox = chromiumSandbox; + return this; + } + public LaunchOptions withDevtools(Boolean devtools) { + this.devtools = devtools; + return this; + } + public LaunchOptions withDownloadsPath(Path downloadsPath) { + this.downloadsPath = downloadsPath; + return this; + } + public LaunchOptions withEnv(Map env) { + this.env = env; return this; } public LaunchOptions withExecutablePath(Path executablePath) { this.executablePath = executablePath; return this; } - public LaunchOptions withArgs(List args) { - this.args = args; + public LaunchOptions withFirefoxUserPrefs(Map firefoxUserPrefs) { + this.firefoxUserPrefs = firefoxUserPrefs; + return this; + } + public LaunchOptions withHandleSIGHUP(Boolean handleSIGHUP) { + this.handleSIGHUP = handleSIGHUP; + return this; + } + public LaunchOptions withHandleSIGINT(Boolean handleSIGINT) { + this.handleSIGINT = handleSIGINT; + return this; + } + public LaunchOptions withHandleSIGTERM(Boolean handleSIGTERM) { + this.handleSIGTERM = handleSIGTERM; + return this; + } + public LaunchOptions withHeadless(Boolean headless) { + this.headless = headless; return this; } public LaunchOptions withIgnoreDefaultArgs(List argumentNames) { @@ -152,51 +200,20 @@ public interface BrowserType { this.proxy = new Proxy(); return this.proxy; } - public LaunchOptions withDownloadsPath(Path downloadsPath) { - this.downloadsPath = downloadsPath; - return this; - } - public LaunchOptions withChromiumSandbox(Boolean chromiumSandbox) { - this.chromiumSandbox = chromiumSandbox; - return this; - } - public LaunchOptions withFirefoxUserPrefs(String firefoxUserPrefs) { - this.firefoxUserPrefs = firefoxUserPrefs; - return this; - } - public LaunchOptions withHandleSIGINT(Boolean handleSIGINT) { - this.handleSIGINT = handleSIGINT; - return this; - } - public LaunchOptions withHandleSIGTERM(Boolean handleSIGTERM) { - this.handleSIGTERM = handleSIGTERM; - return this; - } - public LaunchOptions withHandleSIGHUP(Boolean handleSIGHUP) { - this.handleSIGHUP = handleSIGHUP; - return this; - } - public LaunchOptions withTimeout(Integer timeout) { - this.timeout = timeout; - return this; - } - public LaunchOptions withEnv(Map env) { - this.env = env; - return this; - } - public LaunchOptions withDevtools(Boolean devtools) { - this.devtools = devtools; - return this; - } - public LaunchOptions withSlowMo(Integer slowMo) { + public LaunchOptions withSlowMo(Double slowMo) { this.slowMo = slowMo; return this; } + public LaunchOptions withTimeout(Double timeout) { + this.timeout = timeout; + return this; + } } class LaunchPersistentContextOptions { public class Proxy { /** - * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example {@code http://myproxy.com:3128} or {@code socks5://myproxy.com:3128}. Short form {@code myproxy.com:3128} is considered an HTTP proxy. + * Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example {@code http://myproxy.com:3128} or + * {@code socks5://myproxy.com:3128}. Short form {@code myproxy.com:3128} is considered an HTTP proxy. */ public String server; /** @@ -291,7 +308,9 @@ public interface BrowserType { */ public Path dir; /** - * Optional dimensions of the recorded videos. If not specified the size will be equal to {@code viewport}. If {@code viewport} is not configured explicitly the video size defaults to 1280x720. Actual picture of each page will be scaled down if necessary to fit the specified size. + * Optional dimensions of the recorded videos. If not specified the size will be equal to {@code viewport}. If {@code viewport} is not + * configured explicitly the video size defaults to 1280x720. Actual picture of each page will be scaled down if necessary + * to fit the specified size. */ public Size size; @@ -311,34 +330,60 @@ public interface BrowserType { } } /** - * Whether to run browser in headless mode. More details for Chromium and Firefox. Defaults to {@code true} unless the {@code devtools} option is {@code true}. + * Whether to automatically download all the attachments. Defaults to {@code false} where all the downloads are canceled. */ - public Boolean headless; + public Boolean acceptDownloads; /** - * Path to a browser executable to run instead of the bundled one. If {@code executablePath} is a relative path, then it is resolved relative to the current working directory. **BEWARE**: Playwright is only guaranteed to work with the bundled Chromium, Firefox or WebKit, use at your own risk. - */ - public Path executablePath; - /** - * Additional arguments to pass to the browser instance. The list of Chromium flags can be found here. + * Additional arguments to pass to the browser instance. The list of Chromium flags can be found + * [here](http://peter.sh/experiments/chromium-command-line-switches/). */ public List args; /** - * If {@code true}, then do not use any of the default arguments. If an array is given, then filter out the given default arguments. Dangerous option; use with care. Defaults to {@code false}. + * Toggles bypassing page's Content-Security-Policy. */ - public List ignoreDefaultArgs; - public Boolean ignoreAllDefaultArgs; - /** - * Network proxy settings. - */ - public Proxy proxy; - /** - * If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is deleted when browser is closed. - */ - public Path downloadsPath; + public Boolean bypassCSP; /** * Enable Chromium sandboxing. Defaults to {@code true}. */ public Boolean chromiumSandbox; + /** + * Emulates {@code 'prefers-colors-scheme'} media feature, supported values are {@code 'light'}, {@code 'dark'}, {@code 'no-preference'}. See + * [{@code method: Page.emulateMedia}] for more details. Defaults to '{@code light}'. + */ + public ColorScheme colorScheme; + /** + * Specify device scale factor (can be thought of as dpr). Defaults to {@code 1}. + */ + public Double deviceScaleFactor; + /** + * **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is {@code true}, the {@code headless} + * option will be set {@code false}. + */ + public Boolean devtools; + /** + * If specified, accepted downloads are downloaded into this directory. Otherwise, temporary directory is created and is + * deleted when browser is closed. + */ + public Path downloadsPath; + /** + * Specify environment variables that will be visible to the browser. Defaults to {@code process.env}. + */ + public Map env; + /** + * Path to a browser executable to run instead of the bundled one. If {@code executablePath} is a relative path, then it is + * resolved relative to the current working directory. **BEWARE**: Playwright is only guaranteed to work with the bundled + * Chromium, Firefox or WebKit, use at your own risk. + */ + public Path executablePath; + /** + * An object containing additional HTTP headers to be sent with every request. All header values must be strings. + */ + public Map extraHTTPHeaders; + public Geolocation geolocation; + /** + * Close the browser process on SIGHUP. Defaults to {@code true}. + */ + public Boolean handleSIGHUP; /** * Close the browser process on Ctrl-C. Defaults to {@code true}. */ @@ -348,129 +393,142 @@ public interface BrowserType { */ public Boolean handleSIGTERM; /** - * Close the browser process on SIGHUP. Defaults to {@code true}. + * Specifies if viewport supports touch events. Defaults to false. */ - public Boolean handleSIGHUP; + public Boolean hasTouch; /** - * Maximum time in milliseconds to wait for the browser instance to start. Defaults to {@code 30000} (30 seconds). Pass {@code 0} to disable timeout. + * Whether to run browser in headless mode. More details for + * [Chromium](https://developers.google.com/web/updates/2017/04/headless-chrome) and + * [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Headless_mode). Defaults to {@code true} unless the + * {@code devtools} option is {@code true}. */ - public Integer timeout; + public Boolean headless; /** - * Specify environment variables that will be visible to the browser. Defaults to {@code process.env}. + * Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). */ - public Map env; + public BrowserContext.HTTPCredentials httpCredentials; /** - * **Chromium-only** Whether to auto-open a Developer Tools panel for each tab. If this option is {@code true}, the {@code headless} option will be set {@code false}. + * If {@code true}, then do not use any of the default arguments. If an array is given, then filter out the given default + * arguments. Dangerous option; use with care. Defaults to {@code false}. */ - public Boolean devtools; - /** - * Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0. - */ - public Integer slowMo; - /** - * Whether to automatically download all the attachments. Defaults to {@code false} where all the downloads are canceled. - */ - public Boolean acceptDownloads; + public List ignoreDefaultArgs; + public Boolean ignoreAllDefaultArgs; /** * Whether to ignore HTTPS errors during navigation. Defaults to {@code false}. */ public Boolean ignoreHTTPSErrors; /** - * Toggles bypassing page's Content-Security-Policy. - */ - public Boolean bypassCSP; - /** - * Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. {@code null} disables the default viewport. - */ - public Page.Viewport viewport; - /** - * Specific user agent to use in this context. - */ - public String userAgent; - /** - * Specify device scale factor (can be thought of as dpr). Defaults to {@code 1}. - */ - public Integer deviceScaleFactor; - /** - * Whether the {@code meta viewport} tag is taken into account and touch events are enabled. Defaults to {@code false}. Not supported in Firefox. + * Whether the {@code meta viewport} tag is taken into account and touch events are enabled. Defaults to {@code false}. Not supported + * in Firefox. */ public Boolean isMobile; - /** - * Specifies if viewport supports touch events. Defaults to false. - */ - public Boolean hasTouch; /** * Whether or not to enable JavaScript in the context. Defaults to {@code true}. */ public Boolean javaScriptEnabled; /** - * Changes the timezone of the context. See ICU’s {@code metaZones.txt} for a list of supported timezone IDs. - */ - public String timezoneId; - public Geolocation geolocation; - /** - * Specify user locale, for example {@code en-GB}, {@code de-DE}, etc. Locale will affect {@code navigator.language} value, {@code Accept-Language} request header value as well as number and date formatting rules. + * Specify user locale, for example {@code en-GB}, {@code de-DE}, etc. Locale will affect {@code navigator.language} value, {@code Accept-Language} + * request header value as well as number and date formatting rules. */ public String locale; - /** - * A list of permissions to grant to all pages in this context. See {@code browserContext.grantPermissions(permissions[, options])} for more details. - */ - public List permissions; - /** - * An object containing additional HTTP headers to be sent with every request. All header values must be strings. - */ - public Map extraHTTPHeaders; /** * Whether to emulate network being offline. Defaults to {@code false}. */ public Boolean offline; /** - * Credentials for HTTP authentication. + * A list of permissions to grant to all pages in this context. See [{@code method: BrowserContext.grantPermissions}] for more + * details. */ - public BrowserContext.HTTPCredentials httpCredentials; + public List permissions; /** - * Emulates {@code 'prefers-colors-scheme'} media feature, supported values are {@code 'light'}, {@code 'dark'}, {@code 'no-preference'}. See {@code page.emulateMedia(params)} for more details. Defaults to '{@code light}'. + * Network proxy settings. */ - public ColorScheme colorScheme; + public Proxy proxy; /** - * Enables HAR recording for all pages into {@code recordHar.path} file. If not specified, the HAR is not recorded. Make sure to await {@code browserContext.close()} for the HAR to be saved. + * Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into {@code recordHar.path} file. If not + * specified, the HAR is not recorded. Make sure to await [{@code method: BrowserContext.close}] for the HAR to be saved. */ public RecordHar recordHar; /** - * Enables video recording for all pages into {@code recordVideo.dir} directory. If not specified videos are not recorded. Make sure to await {@code browserContext.close()} for videos to be saved. + * Enables video recording for all pages into {@code recordVideo.dir} directory. If not specified videos are not recorded. Make + * sure to await [{@code method: BrowserContext.close}] for videos to be saved. */ public RecordVideo recordVideo; + /** + * Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. + * Defaults to 0. + */ + public Double slowMo; + /** + * Maximum time in milliseconds to wait for the browser instance to start. Defaults to {@code 30000} (30 seconds). Pass {@code 0} to + * disable timeout. + */ + public Double timeout; + /** + * Changes the timezone of the context. See + * [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) + * for a list of supported timezone IDs. + */ + public String timezoneId; + /** + * Specific user agent to use in this context. + */ + public String userAgent; + /** + * Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. {@code null} disables the default viewport. + */ + public Page.Viewport viewport; - public LaunchPersistentContextOptions withHeadless(Boolean headless) { - this.headless = headless; - return this; - } - public LaunchPersistentContextOptions withExecutablePath(Path executablePath) { - this.executablePath = executablePath; + public LaunchPersistentContextOptions withAcceptDownloads(Boolean acceptDownloads) { + this.acceptDownloads = acceptDownloads; return this; } public LaunchPersistentContextOptions withArgs(List args) { this.args = args; return this; } - public LaunchPersistentContextOptions withIgnoreDefaultArgs(List argumentNames) { - this.ignoreDefaultArgs = argumentNames; + public LaunchPersistentContextOptions withBypassCSP(Boolean bypassCSP) { + this.bypassCSP = bypassCSP; return this; } - public LaunchPersistentContextOptions withIgnoreAllDefaultArgs(boolean ignore) { - this.ignoreAllDefaultArgs = ignore; + public LaunchPersistentContextOptions withChromiumSandbox(Boolean chromiumSandbox) { + this.chromiumSandbox = chromiumSandbox; return this; } - public Proxy setProxy() { - this.proxy = new Proxy(); - return this.proxy; + public LaunchPersistentContextOptions withColorScheme(ColorScheme colorScheme) { + this.colorScheme = colorScheme; + return this; + } + public LaunchPersistentContextOptions withDeviceScaleFactor(Double deviceScaleFactor) { + this.deviceScaleFactor = deviceScaleFactor; + return this; + } + public LaunchPersistentContextOptions withDevtools(Boolean devtools) { + this.devtools = devtools; + return this; } public LaunchPersistentContextOptions withDownloadsPath(Path downloadsPath) { this.downloadsPath = downloadsPath; return this; } - public LaunchPersistentContextOptions withChromiumSandbox(Boolean chromiumSandbox) { - this.chromiumSandbox = chromiumSandbox; + public LaunchPersistentContextOptions withEnv(Map env) { + this.env = env; + return this; + } + public LaunchPersistentContextOptions withExecutablePath(Path executablePath) { + this.executablePath = executablePath; + return this; + } + public LaunchPersistentContextOptions withExtraHTTPHeaders(Map extraHTTPHeaders) { + this.extraHTTPHeaders = extraHTTPHeaders; + return this; + } + public LaunchPersistentContextOptions withGeolocation(Geolocation geolocation) { + this.geolocation = geolocation; + return this; + } + public LaunchPersistentContextOptions withHandleSIGHUP(Boolean handleSIGHUP) { + this.handleSIGHUP = handleSIGHUP; return this; } public LaunchPersistentContextOptions withHandleSIGINT(Boolean handleSIGINT) { @@ -481,94 +539,54 @@ public interface BrowserType { this.handleSIGTERM = handleSIGTERM; return this; } - public LaunchPersistentContextOptions withHandleSIGHUP(Boolean handleSIGHUP) { - this.handleSIGHUP = handleSIGHUP; - return this; - } - public LaunchPersistentContextOptions withTimeout(Integer timeout) { - this.timeout = timeout; - return this; - } - public LaunchPersistentContextOptions withEnv(Map env) { - this.env = env; - return this; - } - public LaunchPersistentContextOptions withDevtools(Boolean devtools) { - this.devtools = devtools; - return this; - } - public LaunchPersistentContextOptions withSlowMo(Integer slowMo) { - this.slowMo = slowMo; - return this; - } - public LaunchPersistentContextOptions withAcceptDownloads(Boolean acceptDownloads) { - this.acceptDownloads = acceptDownloads; - return this; - } - public LaunchPersistentContextOptions withIgnoreHTTPSErrors(Boolean ignoreHTTPSErrors) { - this.ignoreHTTPSErrors = ignoreHTTPSErrors; - return this; - } - public LaunchPersistentContextOptions withBypassCSP(Boolean bypassCSP) { - this.bypassCSP = bypassCSP; - return this; - } - public LaunchPersistentContextOptions withViewport(int width, int height) { - this.viewport = new Page.Viewport(width, height); - return this; - } - public LaunchPersistentContextOptions withUserAgent(String userAgent) { - this.userAgent = userAgent; - return this; - } - public LaunchPersistentContextOptions withDeviceScaleFactor(Integer deviceScaleFactor) { - this.deviceScaleFactor = deviceScaleFactor; - return this; - } - public LaunchPersistentContextOptions withIsMobile(Boolean isMobile) { - this.isMobile = isMobile; - return this; - } public LaunchPersistentContextOptions withHasTouch(Boolean hasTouch) { this.hasTouch = hasTouch; return this; } - public LaunchPersistentContextOptions withJavaScriptEnabled(Boolean javaScriptEnabled) { - this.javaScriptEnabled = javaScriptEnabled; - return this; - } - public LaunchPersistentContextOptions withTimezoneId(String timezoneId) { - this.timezoneId = timezoneId; - return this; - } - public LaunchPersistentContextOptions withGeolocation(Geolocation geolocation) { - this.geolocation = geolocation; - return this; - } - public LaunchPersistentContextOptions withLocale(String locale) { - this.locale = locale; - return this; - } - public LaunchPersistentContextOptions withPermissions(List permissions) { - this.permissions = permissions; - return this; - } - public LaunchPersistentContextOptions withExtraHTTPHeaders(Map extraHTTPHeaders) { - this.extraHTTPHeaders = extraHTTPHeaders; - return this; - } - public LaunchPersistentContextOptions withOffline(Boolean offline) { - this.offline = offline; + public LaunchPersistentContextOptions withHeadless(Boolean headless) { + this.headless = headless; return this; } public LaunchPersistentContextOptions withHttpCredentials(String username, String password) { this.httpCredentials = new BrowserContext.HTTPCredentials(username, password); return this; } - public LaunchPersistentContextOptions withColorScheme(ColorScheme colorScheme) { - this.colorScheme = colorScheme; + public LaunchPersistentContextOptions withIgnoreDefaultArgs(List argumentNames) { + this.ignoreDefaultArgs = argumentNames; return this; } + public LaunchPersistentContextOptions withIgnoreAllDefaultArgs(boolean ignore) { + this.ignoreAllDefaultArgs = ignore; + return this; + } + public LaunchPersistentContextOptions withIgnoreHTTPSErrors(Boolean ignoreHTTPSErrors) { + this.ignoreHTTPSErrors = ignoreHTTPSErrors; + return this; + } + public LaunchPersistentContextOptions withIsMobile(Boolean isMobile) { + this.isMobile = isMobile; + return this; + } + public LaunchPersistentContextOptions withJavaScriptEnabled(Boolean javaScriptEnabled) { + this.javaScriptEnabled = javaScriptEnabled; + return this; + } + public LaunchPersistentContextOptions withLocale(String locale) { + this.locale = locale; + return this; + } + public LaunchPersistentContextOptions withOffline(Boolean offline) { + this.offline = offline; + return this; + } + public LaunchPersistentContextOptions withPermissions(List permissions) { + this.permissions = permissions; + return this; + } + public Proxy setProxy() { + this.proxy = new Proxy(); + return this.proxy; + } public RecordHar setRecordHar() { this.recordHar = new RecordHar(); return this.recordHar; @@ -577,6 +595,26 @@ public interface BrowserType { this.recordVideo = new RecordVideo(); return this.recordVideo; } + public LaunchPersistentContextOptions withSlowMo(Double slowMo) { + this.slowMo = slowMo; + return this; + } + public LaunchPersistentContextOptions withTimeout(Double timeout) { + this.timeout = timeout; + return this; + } + public LaunchPersistentContextOptions withTimezoneId(String timezoneId) { + this.timezoneId = timezoneId; + return this; + } + public LaunchPersistentContextOptions withUserAgent(String userAgent) { + this.userAgent = userAgent; + return this; + } + public LaunchPersistentContextOptions withViewport(int width, int height) { + this.viewport = new Page.Viewport(width, height); + return this; + } } /** * A path where Playwright expects to find a bundled browser executable. @@ -592,13 +630,33 @@ public interface BrowserType { *

* *

- * **Chromium-only** Playwright can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use {@code executablePath} option with extreme caution. + * > **Chromium-only** Playwright can also be used to control the Chrome browser, but it works best with the version of *

- * If Google Chrome (rather than Chromium) is preferred, a Chrome Canary or Dev Channel build is suggested. + * Chromium it is bundled with. There is no guarantee it will work with any other version. Use {@code executablePath} option with *

- * In {@code browserType.launch([options])} above, any mention of Chromium also applies to Chrome. + * extreme caution. *

- * See {@code this article} for a description of the differences between Chromium and Chrome. {@code This article} describes some differences for Linux users. + * > + *

+ * > If Google Chrome (rather than Chromium) is preferred, a + *

+ * [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or + *

+ * [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. + *

+ * > + *

+ * > In [{@code method: BrowserType.launch}] above, any mention of Chromium also applies to Chrome. + *

+ * > + *

+ * > See [{@code this article}](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for + *

+ * a description of the differences between Chromium and Chrome. + *

+ * [{@code This article}](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md) + *

+ * describes some differences for Linux users. */ Browser launch(LaunchOptions options); default BrowserContext launchPersistentContext(Path userDataDir) { @@ -607,8 +665,12 @@ public interface BrowserType { /** * Returns the persistent browser context instance. *

- * Launches browser that uses persistent storage located at {@code userDataDir} and returns the only context. Closing this context will automatically close the browser. - * @param userDataDir Path to a User Data Directory, which stores browser session data like cookies and local storage. More details for Chromium and Firefox. + * Launches browser that uses persistent storage located at {@code userDataDir} and returns the only context. Closing this + *

+ * context will automatically close the browser. + * @param userDataDir Path to a User Data Directory, which stores browser session data like cookies and local storage. More details for + * [Chromium](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md) and + * [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Command_Line_Options#User_Profile). */ BrowserContext launchPersistentContext(Path userDataDir, LaunchPersistentContextOptions options); /** diff --git a/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java b/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java index 8650be0a..f40854a2 100644 --- a/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java +++ b/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java @@ -19,12 +19,12 @@ package com.microsoft.playwright; import java.util.*; /** - * ConsoleMessage objects are dispatched by page via the page.on('console') event. + * {@code ConsoleMessage} objects are dispatched by page via the [{@code event: Page.console}] event. */ public interface ConsoleMessage { class Location { /** - * URL of the resource if available, otherwise empty string. + * URL of the resource. */ private String url; /** @@ -50,7 +50,11 @@ public interface ConsoleMessage { Location location(); String text(); /** - * One of the following values: {@code 'log'}, {@code 'debug'}, {@code 'info'}, {@code 'error'}, {@code 'warning'}, {@code 'dir'}, {@code 'dirxml'}, {@code 'table'}, {@code 'trace'}, {@code 'clear'}, {@code 'startGroup'}, {@code 'startGroupCollapsed'}, {@code 'endGroup'}, {@code 'assert'}, {@code 'profile'}, {@code 'profileEnd'}, {@code 'count'}, {@code 'timeEnd'}. + * One of the following values: {@code 'log'}, {@code 'debug'}, {@code 'info'}, {@code 'error'}, {@code 'warning'}, {@code 'dir'}, {@code 'dirxml'}, {@code 'table'}, + *

+ * {@code 'trace'}, {@code 'clear'}, {@code 'startGroup'}, {@code 'startGroupCollapsed'}, {@code 'endGroup'}, {@code 'assert'}, {@code 'profile'}, {@code 'profileEnd'}, + *

+ * {@code 'count'}, {@code 'timeEnd'}. */ String type(); } diff --git a/playwright/src/main/java/com/microsoft/playwright/DeviceDescriptor.java b/playwright/src/main/java/com/microsoft/playwright/DeviceDescriptor.java index 45472ebe..50633e0f 100644 --- a/playwright/src/main/java/com/microsoft/playwright/DeviceDescriptor.java +++ b/playwright/src/main/java/com/microsoft/playwright/DeviceDescriptor.java @@ -23,7 +23,7 @@ public interface DeviceDescriptor { } Viewport viewport(); String userAgent(); - int deviceScaleFactor(); + double deviceScaleFactor(); boolean isMobile(); boolean hasTouch(); BrowserType defaultBrowserType(); diff --git a/playwright/src/main/java/com/microsoft/playwright/Dialog.java b/playwright/src/main/java/com/microsoft/playwright/Dialog.java index 1bbb39ce..80475710 100644 --- a/playwright/src/main/java/com/microsoft/playwright/Dialog.java +++ b/playwright/src/main/java/com/microsoft/playwright/Dialog.java @@ -19,7 +19,10 @@ package com.microsoft.playwright; import java.util.*; /** - * Dialog objects are dispatched by page via the page.on('dialog') event. + * {@code Dialog} objects are dispatched by page via the [{@code event: Page.dialog}] event. + *

+ * + *

*/ public interface Dialog { enum Type { ALERT, BEFOREUNLOAD, CONFIRM, PROMPT } diff --git a/playwright/src/main/java/com/microsoft/playwright/Download.java b/playwright/src/main/java/com/microsoft/playwright/Download.java index 4d80a51c..1682e6e5 100644 --- a/playwright/src/main/java/com/microsoft/playwright/Download.java +++ b/playwright/src/main/java/com/microsoft/playwright/Download.java @@ -21,15 +21,21 @@ import java.nio.file.Path; import java.util.*; /** - * Download objects are dispatched by page via the page.on('download') event. + * {@code Download} objects are dispatched by page via the [{@code event: Page.download}] event. *

- * All the downloaded files belonging to the browser context are deleted when the browser context is closed. All downloaded files are deleted when the browser closes. + * All the downloaded files belonging to the browser context are deleted when the browser context is closed. All downloaded + *

+ * files are deleted when the browser closes. *

* Download event is emitted once the download starts. Download path becomes available once download completes: *

* *

- * NOTE Browser context **must** be created with the {@code acceptDownloads} set to {@code true} when user needs access to the downloaded content. If {@code acceptDownloads} is not set or set to {@code false}, download events are emitted, but the actual download is not performed and user has no access to the downloaded files. + * > NOTE Browser context **must** be created with the {@code acceptDownloads} set to {@code true} when user needs access to the + *

+ * downloaded content. If {@code acceptDownloads} is not set or set to {@code false}, download events are emitted, but the actual + *

+ * download is not performed and user has no access to the downloaded files. */ public interface Download { /** @@ -54,7 +60,13 @@ public interface Download { */ void saveAs(Path path); /** - * Returns suggested filename for this download. It is typically computed by the browser from the {@code Content-Disposition} response header or the {@code download} attribute. See the spec on whatwg. Different browsers can use different logic for computing it. + * Returns suggested filename for this download. It is typically computed by the browser from the + *

+ * [{@code Content-Disposition}](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) response header + *

+ * or the {@code download} attribute. See the spec on [whatwg](https://html.spec.whatwg.org/#downloading-resources). Different + *

+ * browsers can use different logic for computing it. */ String suggestedFilename(); /** diff --git a/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java b/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java index 089949e8..19707733 100644 --- a/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java +++ b/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java @@ -20,11 +20,17 @@ import java.nio.file.Path; import java.util.*; /** - * ElementHandle represents an in-page DOM element. ElementHandles can be created with the {@code page.$(selector)} method. + * - extends: {@code JSHandle} *

- * ElementHandle prevents DOM element from garbage collection unless the handle is disposed with {@code jsHandle.dispose()}. ElementHandles are auto-disposed when their origin frame gets navigated. + * ElementHandle represents an in-page DOM element. ElementHandles can be created with the [{@code method: Page.$}] method. *

- * ElementHandle instances can be used as an argument in {@code page.$eval(selector, pageFunction[, arg])} and {@code page.evaluate(pageFunction[, arg])} methods. + * + *

+ * ElementHandle prevents DOM element from garbage collection unless the handle is disposed with + *

+ * [{@code method: JSHandle.dispose}]. ElementHandles are auto-disposed when their origin frame gets navigated. + *

+ * ElementHandle instances can be used as an argument in [{@code method: Page.$eval}] and [{@code method: Page.evaluate}] methods. */ public interface ElementHandle extends JSHandle { class BoundingBox { @@ -53,20 +59,23 @@ public interface ElementHandle extends JSHandle { } } - enum ElementState { DISABLED, ENABLED, HIDDEN, STABLE, VISIBLE } + enum ElementState { VISIBLE, HIDDEN, STABLE, ENABLED, DISABLED } class CheckOptions { /** - * Whether to bypass the actionability checks. Defaults to {@code false}. + * Whether to bypass the [actionability](./actionability.md) checks. Defaults to {@code false}. */ public Boolean force; /** - * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to {@code false}. + * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can + * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to + * inaccessible pages. Defaults to {@code false}. */ public Boolean noWaitAfter; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ - public Integer timeout; + public Double timeout; public CheckOptions withForce(Boolean force) { this.force = force; @@ -76,7 +85,7 @@ public interface ElementHandle extends JSHandle { this.noWaitAfter = noWaitAfter; return this; } - public CheckOptions withTimeout(Integer timeout) { + public CheckOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } @@ -87,33 +96,38 @@ public interface ElementHandle extends JSHandle { */ public Mouse.Button button; /** - * defaults to 1. See UIEvent.detail. + * defaults to 1. See [UIEvent.detail]. */ public Integer clickCount; /** * Time to wait between {@code mousedown} and {@code mouseup} in milliseconds. Defaults to 0. */ - public Integer delay; + public Double delay; /** - * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. - */ - public Position position; - /** - * Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used. - */ - public Set modifiers; - /** - * Whether to bypass the actionability checks. Defaults to {@code false}. + * Whether to bypass the [actionability](./actionability.md) checks. Defaults to {@code false}. */ public Boolean force; /** - * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to {@code false}. + * Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current + * modifiers back. If not specified, currently pressed modifiers are used. + */ + public Set modifiers; + /** + * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can + * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to + * inaccessible pages. Defaults to {@code false}. */ public Boolean noWaitAfter; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the + * element. */ - public Integer timeout; + public Position position; + /** + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. + */ + public Double timeout; public ClickOptions withButton(Mouse.Button button) { this.button = button; @@ -123,10 +137,22 @@ public interface ElementHandle extends JSHandle { this.clickCount = clickCount; return this; } - public ClickOptions withDelay(Integer delay) { + public ClickOptions withDelay(Double delay) { this.delay = delay; return this; } + public ClickOptions withForce(Boolean force) { + this.force = force; + return this; + } + public ClickOptions withModifiers(Keyboard.Modifier... modifiers) { + this.modifiers = new HashSet<>(Arrays.asList(modifiers)); + return this; + } + public ClickOptions withNoWaitAfter(Boolean noWaitAfter) { + this.noWaitAfter = noWaitAfter; + return this; + } public ClickOptions withPosition(Position position) { this.position = position; return this; @@ -134,19 +160,7 @@ public interface ElementHandle extends JSHandle { public ClickOptions withPosition(int x, int y) { return withPosition(new Position(x, y)); } - public ClickOptions withModifiers(Keyboard.Modifier... modifiers) { - this.modifiers = new HashSet<>(Arrays.asList(modifiers)); - return this; - } - public ClickOptions withForce(Boolean force) { - this.force = force; - return this; - } - public ClickOptions withNoWaitAfter(Boolean noWaitAfter) { - this.noWaitAfter = noWaitAfter; - return this; - } - public ClickOptions withTimeout(Integer timeout) { + public ClickOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } @@ -159,36 +173,53 @@ public interface ElementHandle extends JSHandle { /** * Time to wait between {@code mousedown} and {@code mouseup} in milliseconds. Defaults to 0. */ - public Integer delay; + public Double delay; /** - * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. - */ - public Position position; - /** - * Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used. - */ - public Set modifiers; - /** - * Whether to bypass the actionability checks. Defaults to {@code false}. + * Whether to bypass the [actionability](./actionability.md) checks. Defaults to {@code false}. */ public Boolean force; /** - * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to {@code false}. + * Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current + * modifiers back. If not specified, currently pressed modifiers are used. + */ + public Set modifiers; + /** + * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can + * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to + * inaccessible pages. Defaults to {@code false}. */ public Boolean noWaitAfter; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the + * element. */ - public Integer timeout; + public Position position; + /** + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. + */ + public Double timeout; public DblclickOptions withButton(Mouse.Button button) { this.button = button; return this; } - public DblclickOptions withDelay(Integer delay) { + public DblclickOptions withDelay(Double delay) { this.delay = delay; return this; } + public DblclickOptions withForce(Boolean force) { + this.force = force; + return this; + } + public DblclickOptions withModifiers(Keyboard.Modifier... modifiers) { + this.modifiers = new HashSet<>(Arrays.asList(modifiers)); + return this; + } + public DblclickOptions withNoWaitAfter(Boolean noWaitAfter) { + this.noWaitAfter = noWaitAfter; + return this; + } public DblclickOptions withPosition(Position position) { this.position = position; return this; @@ -196,60 +227,62 @@ public interface ElementHandle extends JSHandle { public DblclickOptions withPosition(int x, int y) { return withPosition(new Position(x, y)); } - public DblclickOptions withModifiers(Keyboard.Modifier... modifiers) { - this.modifiers = new HashSet<>(Arrays.asList(modifiers)); - return this; - } - public DblclickOptions withForce(Boolean force) { - this.force = force; - return this; - } - public DblclickOptions withNoWaitAfter(Boolean noWaitAfter) { - this.noWaitAfter = noWaitAfter; - return this; - } - public DblclickOptions withTimeout(Integer timeout) { + public DblclickOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } } class FillOptions { /** - * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to {@code false}. + * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can + * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to + * inaccessible pages. Defaults to {@code false}. */ public Boolean noWaitAfter; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ - public Integer timeout; + public Double timeout; public FillOptions withNoWaitAfter(Boolean noWaitAfter) { this.noWaitAfter = noWaitAfter; return this; } - public FillOptions withTimeout(Integer timeout) { + public FillOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } } class HoverOptions { /** - * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. - */ - public Position position; - /** - * Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used. - */ - public Set modifiers; - /** - * Whether to bypass the actionability checks. Defaults to {@code false}. + * Whether to bypass the [actionability](./actionability.md) checks. Defaults to {@code false}. */ public Boolean force; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current + * modifiers back. If not specified, currently pressed modifiers are used. */ - public Integer timeout; + public Set modifiers; + /** + * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the + * element. + */ + public Position position; + /** + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. + */ + public Double timeout; + public HoverOptions withForce(Boolean force) { + this.force = force; + return this; + } + public HoverOptions withModifiers(Keyboard.Modifier... modifiers) { + this.modifiers = new HashSet<>(Arrays.asList(modifiers)); + return this; + } public HoverOptions withPosition(Position position) { this.position = position; return this; @@ -257,15 +290,7 @@ public interface ElementHandle extends JSHandle { public HoverOptions withPosition(int x, int y) { return withPosition(new Position(x, y)); } - public HoverOptions withModifiers(Keyboard.Modifier... modifiers) { - this.modifiers = new HashSet<>(Arrays.asList(modifiers)); - return this; - } - public HoverOptions withForce(Boolean force) { - this.force = force; - return this; - } - public HoverOptions withTimeout(Integer timeout) { + public HoverOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } @@ -274,17 +299,20 @@ public interface ElementHandle extends JSHandle { /** * Time to wait between {@code keydown} and {@code keyup} in milliseconds. Defaults to 0. */ - public Integer delay; + public Double delay; /** - * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to {@code false}. + * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can + * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to + * inaccessible pages. Defaults to {@code false}. */ public Boolean noWaitAfter; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ - public Integer timeout; + public Double timeout; - public PressOptions withDelay(Integer delay) { + public PressOptions withDelay(Double delay) { this.delay = delay; return this; } @@ -292,119 +320,131 @@ public interface ElementHandle extends JSHandle { this.noWaitAfter = noWaitAfter; return this; } - public PressOptions withTimeout(Integer timeout) { + public PressOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } } class ScreenshotOptions { - public enum Type { JPEG, PNG } + public enum Type { PNG, JPEG } /** - * The file path to save the image to. The screenshot type will be inferred from file extension. If {@code path} is a relative path, then it is resolved relative to the current working directory. If no path is provided, the image won't be saved to the disk. + * Hides default white background and allows capturing screenshots with transparency. Not applicable to {@code jpeg} images. + * Defaults to {@code false}. + */ + public Boolean omitBackground; + /** + * The file path to save the image to. The screenshot type will be inferred from file extension. If {@code path} is a relative + * path, then it is resolved relative to the current working directory. If no path is provided, the image won't be saved to + * the disk. */ public Path path; - /** - * Specify screenshot type, defaults to {@code png}. - */ - public Type type; /** * The quality of the image, between 0-100. Not applicable to {@code png} images. */ public Integer quality; /** - * Hides default white background and allows capturing screenshots with transparency. Not applicable to {@code jpeg} images. Defaults to {@code false}. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ - public Boolean omitBackground; + public Double timeout; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Specify screenshot type, defaults to {@code png}. */ - public Integer timeout; + public Type type; - public ScreenshotOptions withPath(Path path) { - this.path = path; + public ScreenshotOptions withOmitBackground(Boolean omitBackground) { + this.omitBackground = omitBackground; return this; } - public ScreenshotOptions withType(Type type) { - this.type = type; + public ScreenshotOptions withPath(Path path) { + this.path = path; return this; } public ScreenshotOptions withQuality(Integer quality) { this.quality = quality; return this; } - public ScreenshotOptions withOmitBackground(Boolean omitBackground) { - this.omitBackground = omitBackground; + public ScreenshotOptions withTimeout(Double timeout) { + this.timeout = timeout; return this; } - public ScreenshotOptions withTimeout(Integer timeout) { - this.timeout = timeout; + public ScreenshotOptions withType(Type type) { + this.type = type; return this; } } class ScrollIntoViewIfNeededOptions { /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ - public Integer timeout; + public Double timeout; - public ScrollIntoViewIfNeededOptions withTimeout(Integer timeout) { + public ScrollIntoViewIfNeededOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } } class SelectOptionOptions { /** - * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to {@code false}. + * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can + * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to + * inaccessible pages. Defaults to {@code false}. */ public Boolean noWaitAfter; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ - public Integer timeout; + public Double timeout; public SelectOptionOptions withNoWaitAfter(Boolean noWaitAfter) { this.noWaitAfter = noWaitAfter; return this; } - public SelectOptionOptions withTimeout(Integer timeout) { + public SelectOptionOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } } class SelectTextOptions { /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ - public Integer timeout; + public Double timeout; - public SelectTextOptions withTimeout(Integer timeout) { + public SelectTextOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } } class SetInputFilesOptions { /** - * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to {@code false}. + * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can + * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to + * inaccessible pages. Defaults to {@code false}. */ public Boolean noWaitAfter; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ - public Integer timeout; + public Double timeout; public SetInputFilesOptions withNoWaitAfter(Boolean noWaitAfter) { this.noWaitAfter = noWaitAfter; return this; } - public SetInputFilesOptions withTimeout(Integer timeout) { + public SetInputFilesOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } } class TapOptions { public class Position { - public int x; - public int y; + public double x; + public double y; Position() { } @@ -412,53 +452,58 @@ public interface ElementHandle extends JSHandle { return TapOptions.this; } - public Position withX(int x) { + public Position withX(double x) { this.x = x; return this; } - public Position withY(int y) { + public Position withY(double y) { this.y = y; return this; } } /** - * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. - */ - public Position position; - /** - * Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used. - */ - public Set modifiers; - /** - * Whether to bypass the actionability checks. Defaults to {@code false}. + * Whether to bypass the [actionability](./actionability.md) checks. Defaults to {@code false}. */ public Boolean force; /** - * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to {@code false}. + * Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current + * modifiers back. If not specified, currently pressed modifiers are used. + */ + public Set modifiers; + /** + * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can + * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to + * inaccessible pages. Defaults to {@code false}. */ public Boolean noWaitAfter; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the + * element. */ - public Integer timeout; + public Position position; + /** + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. + */ + public Double timeout; - public Position setPosition() { - this.position = new Position(); - return this.position; + public TapOptions withForce(Boolean force) { + this.force = force; + return this; } public TapOptions withModifiers(Keyboard.Modifier... modifiers) { this.modifiers = new HashSet<>(Arrays.asList(modifiers)); return this; } - public TapOptions withForce(Boolean force) { - this.force = force; - return this; - } public TapOptions withNoWaitAfter(Boolean noWaitAfter) { this.noWaitAfter = noWaitAfter; return this; } - public TapOptions withTimeout(Integer timeout) { + public Position setPosition() { + this.position = new Position(); + return this.position; + } + public TapOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } @@ -467,17 +512,20 @@ public interface ElementHandle extends JSHandle { /** * Time to wait between key presses in milliseconds. Defaults to 0. */ - public Integer delay; + public Double delay; /** - * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to {@code false}. + * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can + * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to + * inaccessible pages. Defaults to {@code false}. */ public Boolean noWaitAfter; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ - public Integer timeout; + public Double timeout; - public TypeOptions withDelay(Integer delay) { + public TypeOptions withDelay(Double delay) { this.delay = delay; return this; } @@ -485,24 +533,27 @@ public interface ElementHandle extends JSHandle { this.noWaitAfter = noWaitAfter; return this; } - public TypeOptions withTimeout(Integer timeout) { + public TypeOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } } class UncheckOptions { /** - * Whether to bypass the actionability checks. Defaults to {@code false}. + * Whether to bypass the [actionability](./actionability.md) checks. Defaults to {@code false}. */ public Boolean force; /** - * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to {@code false}. + * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can + * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to + * inaccessible pages. Defaults to {@code false}. */ public Boolean noWaitAfter; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ - public Integer timeout; + public Double timeout; public UncheckOptions withForce(Boolean force) { this.force = force; @@ -512,14 +563,15 @@ public interface ElementHandle extends JSHandle { this.noWaitAfter = noWaitAfter; return this; } - public UncheckOptions withTimeout(Integer timeout) { + public UncheckOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } } class WaitForElementStateOptions { /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ public Integer timeout; @@ -529,37 +581,48 @@ public interface ElementHandle extends JSHandle { } } class WaitForSelectorOptions { - public enum State { ATTACHED, DETACHED, HIDDEN, VISIBLE } + public enum State { ATTACHED, DETACHED, VISIBLE, HIDDEN } /** * Defaults to {@code 'visible'}. Can be either: - * - {@code 'attached'} - wait for element to be present in DOM. - * - {@code 'detached'} - wait for element to not be present in DOM. - * - {@code 'visible'} - wait for element to have non-empty bounding box and no {@code visibility:hidden}. Note that element without any content or with {@code display:none} has an empty bounding box and is not considered visible. - * - {@code 'hidden'} - wait for element to be either detached from DOM, or have an empty bounding box or {@code visibility:hidden}. This is opposite to the {@code 'visible'} option. + * - {@code 'attached'} - wait for element to be present in DOM. + * - {@code 'detached'} - wait for element to not be present in DOM. + * - {@code 'visible'} - wait for element to have non-empty bounding box and no {@code visibility:hidden}. Note that element without + * any content or with {@code display:none} has an empty bounding box and is not considered visible. + * - {@code 'hidden'} - wait for element to be either detached from DOM, or have an empty bounding box or {@code visibility:hidden}. + * This is opposite to the {@code 'visible'} option. */ public State state; /** - * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by using the {@code browserContext.setDefaultTimeout(timeout)} or {@code page.setDefaultTimeout(timeout)} methods. + * Maximum time in milliseconds, defaults to 30 seconds, pass {@code 0} to disable timeout. The default value can be changed by + * using the [{@code method: BrowserContext.setDefaultTimeout}] or [{@code method: Page.setDefaultTimeout}] methods. */ - public Integer timeout; + public Double timeout; public WaitForSelectorOptions withState(State state) { this.state = state; return this; } - public WaitForSelectorOptions withTimeout(Integer timeout) { + public WaitForSelectorOptions withTimeout(Double timeout) { this.timeout = timeout; return this; } } /** - * The method finds an element matching the specified selector in the {@code ElementHandle}'s subtree. See Working with selectors for more details. If no elements match the selector, returns {@code null}. - * @param selector A selector to query for. See working with selectors for more details. + * The method finds an element matching the specified selector in the {@code ElementHandle}'s subtree. See + *

+ * [Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector, + *

+ * returns {@code null}. + * @param selector A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details. */ ElementHandle querySelector(String selector); /** - * The method finds all elements matching the specified selector in the {@code ElementHandle}s subtree. See Working with selectors for more details. If no elements match the selector, returns empty array. - * @param selector A selector to query for. See working with selectors for more details. + * The method finds all elements matching the specified selector in the {@code ElementHandle}s subtree. See + *

+ * [Working with selectors](./selectors.md#working-with-selectors) for more details. If no elements match the selector, + *

+ * returns empty array. + * @param selector A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details. */ List querySelectorAll(String selector); default Object evalOnSelector(String selector, String pageFunction) { @@ -568,14 +631,20 @@ public interface ElementHandle extends JSHandle { /** * Returns the return value of {@code pageFunction} *

- * The method finds an element matching the specified selector in the {@code ElementHandle}s subtree and passes it as a first argument to {@code pageFunction}. See Working with selectors for more details. If no elements match the selector, the method throws an error. + * The method finds an element matching the specified selector in the {@code ElementHandle}s subtree and passes it as a first *

- * If {@code pageFunction} returns a Promise, then {@code frame.$eval} would wait for the promise to resolve and return its value. + * argument to {@code pageFunction}. See [Working with selectors](./selectors.md#working-with-selectors) for more details. If no + *

+ * elements match the selector, the method throws an error. + *

+ * If {@code pageFunction} returns a [Promise], then {@code frame.$eval} would wait for the promise to resolve and return its value. *

* Examples: *

* - * @param selector A selector to query for. See working with selectors for more details. + *

+ * + * @param selector A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details. * @param pageFunction Function to be evaluated in browser context * @param arg Optional argument to pass to {@code pageFunction} */ @@ -586,26 +655,46 @@ public interface ElementHandle extends JSHandle { /** * Returns the return value of {@code pageFunction} *

- * The method finds all elements matching the specified selector in the {@code ElementHandle}'s subtree and passes an array of matched elements as a first argument to {@code pageFunction}. See Working with selectors for more details. + * The method finds all elements matching the specified selector in the {@code ElementHandle}'s subtree and passes an array of *

- * If {@code pageFunction} returns a Promise, then {@code frame.$$eval} would wait for the promise to resolve and return its value. + * matched elements as a first argument to {@code pageFunction}. See + *

+ * [Working with selectors](./selectors.md#working-with-selectors) for more details. + *

+ * If {@code pageFunction} returns a [Promise], then {@code frame.$$eval} would wait for the promise to resolve and return its value. *

* Examples: *

* - * @param selector A selector to query for. See working with selectors for more details. + *

+ * + *

+ * + * @param selector A selector to query for. See [working with selectors](./selectors.md#working-with-selectors) for more details. * @param pageFunction Function to be evaluated in browser context * @param arg Optional argument to pass to {@code pageFunction} */ Object evalOnSelectorAll(String selector, String pageFunction, Object arg); /** - * This method returns the bounding box of the element, or {@code null} if the element is not visible. The bounding box is calculated relative to the main frame viewport - which is usually the same as the browser window. + * This method returns the bounding box of the element, or {@code null} if the element is not visible. The bounding box is *

- * Scrolling affects the returned bonding box, similarly to Element.getBoundingClientRect. That means {@code x} and/or {@code y} may be negative. + * calculated relative to the main frame viewport - which is usually the same as the browser window. *

- * Elements from child frames return the bounding box relative to the main frame, unlike the Element.getBoundingClientRect. + * Scrolling affects the returned bonding box, similarly to *

- * Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following snippet should click the center of the element. + * [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect). That + *

+ * means {@code x} and/or {@code y} may be negative. + *

+ * Elements from child frames return the bounding box relative to the main frame, unlike the + *

+ * [Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect). + *

+ * Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following + *

+ * snippet should click the center of the element. + *

+ * *

*/ BoundingBox boundingBox(); @@ -615,21 +704,25 @@ public interface ElementHandle extends JSHandle { /** * This method checks the element by performing the following steps: *

- * Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. + * 1. Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already *

- * Wait for actionability checks on the element, unless {@code force} option is set. + * checked, this method returns immediately. *

- * Scroll the element into view if needed. + * 1. Wait for [actionability](./actionability.md) checks on the element, unless {@code force} option is set. *

- * Use page.mouse to click in the center of the element. + * 1. Scroll the element into view if needed. *

- * Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set. + * 1. Use [{@code property: Page.mouse}] to click in the center of the element. *

- * Ensure that the element is now checked. If not, this method rejects. + * 1. Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set. + *

+ * 1. Ensure that the element is now checked. If not, this method rejects. *

* If the element is detached from the DOM at any moment during the action, this method rejects. *

- * When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this. + * When all steps combined have not finished during the specified {@code timeout}, this method rejects with a {@code TimeoutError}. + *

+ * Passing zero timeout disables this. */ void check(CheckOptions options); default void click() { @@ -638,17 +731,19 @@ public interface ElementHandle extends JSHandle { /** * This method clicks the element by performing the following steps: *

- * Wait for actionability checks on the element, unless {@code force} option is set. + * 1. Wait for [actionability](./actionability.md) checks on the element, unless {@code force} option is set. *

- * Scroll the element into view if needed. + * 1. Scroll the element into view if needed. *

- * Use page.mouse to click in the center of the element, or the specified {@code position}. + * 1. Use [{@code property: Page.mouse}] to click in the center of the element, or the specified {@code position}. *

- * Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set. + * 1. Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set. *

* If the element is detached from the DOM at any moment during the action, this method rejects. *

- * When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this. + * When all steps combined have not finished during the specified {@code timeout}, this method rejects with a {@code TimeoutError}. + *

+ * Passing zero timeout disables this. */ void click(ClickOptions options); /** @@ -661,48 +756,62 @@ public interface ElementHandle extends JSHandle { /** * This method double clicks the element by performing the following steps: *

- * Wait for actionability checks on the element, unless {@code force} option is set. + * 1. Wait for [actionability](./actionability.md) checks on the element, unless {@code force} option is set. *

- * Scroll the element into view if needed. + * 1. Scroll the element into view if needed. *

- * Use page.mouse to double click in the center of the element, or the specified {@code position}. + * 1. Use [{@code property: Page.mouse}] to double click in the center of the element, or the specified {@code position}. *

- * Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set. Note that if the first click of the {@code dblclick()} triggers a navigation event, this method will reject. + * 1. Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set. Note that if the + *

+ * first click of the {@code dblclick()} triggers a navigation event, this method will reject. *

* If the element is detached from the DOM at any moment during the action, this method rejects. *

- * When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this. + * When all steps combined have not finished during the specified {@code timeout}, this method rejects with a {@code TimeoutError}. *

- * NOTE {@code elementHandle.dblclick()} dispatches two {@code click} events and a single {@code dblclick} event. + * Passing zero timeout disables this. + *

+ * > NOTE {@code elementHandle.dblclick()} dispatches two {@code click} events and a single {@code dblclick} event. */ void dblclick(DblclickOptions options); default void dispatchEvent(String type) { dispatchEvent(type, null); } /** - * The snippet below dispatches the {@code click} event on the element. Regardless of the visibility state of the elment, {@code click} is dispatched. This is equivalend to calling element.click(). + * The snippet below dispatches the {@code click} event on the element. Regardless of the visibility state of the elment, {@code click} *

- * Under the hood, it creates an instance of an event based on the given {@code type}, initializes it with {@code eventInit} properties and dispatches it on the element. Events are {@code composed}, {@code cancelable} and bubble by default. + * is dispatched. This is equivalend to calling + *

+ * [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click). + *

+ * + *

+ * Under the hood, it creates an instance of an event based on the given {@code type}, initializes it with {@code eventInit} properties + *

+ * and dispatches it on the element. Events are {@code composed}, {@code cancelable} and bubble by default. *

* Since {@code eventInit} is event-specific, please refer to the events documentation for the lists of initial properties: *

- * DragEvent + * - [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent) *

- * FocusEvent + * - [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent) *

- * KeyboardEvent + * - [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent) *

- * MouseEvent + * - [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/MouseEvent) *

- * PointerEvent + * - [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/PointerEvent) *

- * TouchEvent + * - [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/TouchEvent) *

- * Event + * - [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event) *

* You can also specify {@code JSHandle} as the property value if you want live objects to be passed into the event: *

* + *

+ * * @param type DOM event type: {@code "click"}, {@code "dragstart"}, etc. * @param eventInit Optional event-specific initialization properties. */ @@ -711,12 +820,16 @@ public interface ElementHandle extends JSHandle { fill(value, null); } /** - * This method waits for actionability checks, focuses the element, fills it and triggers an {@code input} event after filling. If the element is not an {@code }, {@code