honeymoose/playwright-java
1
0
Fork 0
mirror of https://github.com/microsoft/playwright-java.git synced 2025-09-08 21:01:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add javadoc comments to interfaces and methods (#71)

Browse Source
This commit is contained in:
Yury Semikhatsky 2020-11-06 12:37:28 -08:00 committed by GitHub
parent 1db15a7bd1
commit cbcc04d0f0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
32 changed files with 2273 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java
View File

@ -60,6 +60,41 @@ abstract class Element {
static String toTitle(String name) {
return Character.toUpperCase(name.charAt(0)) + name.substring(1);
}
void writeJavadoc(List<String> output, String offset, String text) {
if (text.isEmpty()) {
return;
}
output.add(offset + "/**");
String[] lines = text.split("\\n");
for (String line : lines) {
output.add(offset + " * " + line
.replace("*/", "*\\/")
.replace("**NOTE**", "<strong>NOTE</strong>")
.replaceAll("`([^`]+)`", "{@code $1}"));
}
output.add(offset + " */");
}
String formattedComment() {
return comment()
// Remove any code snippets between ``` and ```.
.replaceAll("```((?<!`)`(?!`)|[^`])+```", "")
.replaceAll("\\nAn example of[^\\n]+\\n", "")
.replaceAll("\\nThis example [^\\n]+\\n", "")
.replaceAll("\\nSee ChromiumBrowser[^\\n]+", "\n")
.replaceAll("\\n\\n", "\n")
.replaceAll("\\n", "\n<p>\n");
// .replaceAll("\\n\\n", "\n<p>\n");
}
String comment() {
JsonObject json = jsonElement.getAsJsonObject();
if (!json.has("comment")) {
return "";
}
return json.get("comment").getAsString();
}
}
// Represents return type of a method, type of a method param or type of a field.
@ -409,8 +444,12 @@ class Method extends Element {
void writeTo(List<String> output, String offset) {
if (customSignature.containsKey(jsonPath)) {
for (String signature : customSignature.get(jsonPath)) {
output.add(offset + signature);
String[] signatures = customSignature.get(jsonPath);
for (int i = 0; i < signatures.length; i++) {
if (i == signatures.length - 1) {
writeJavadoc(output, offset);
}
output.add(offset + signatures[i]);
}
return;
}
@ -421,6 +460,7 @@ class Method extends Element {
}
writeDefaultOverloadedMethod(i, output, offset);
}
writeJavadoc(output, offset);
output.add(offset + toJava());
}
@ -445,6 +485,25 @@ class Method extends Element {
output.add(offset + " " + returns + name + "(" + argList + ");");
output.add(offset + "}");
}
private void writeJavadoc(List<String> output, String offset) {
List<String> sections = new ArrayList<>();
sections.add(formattedComment());
if (!params.isEmpty()) {
for (Param p : params) {
String comment = p.comment();
if (comment.isEmpty()) {
continue;
}
sections.add("@param " + p.name() + " " + comment);
}
}
if (jsonElement.getAsJsonObject().has("returnComment")) {
String returnComment = jsonElement.getAsJsonObject().get("returnComment").getAsString();
sections.add("@return " + returnComment);
}
writeJavadoc(output, offset, String.join("\n", sections));
}
}
class Param extends Element {
@ -465,7 +524,7 @@ class Param extends Element {
return !jsonElement.getAsJsonObject().get("required").getAsBoolean();
}
private String name() {
String name() {
String name = customName.get(jsonPath);
if (name != null) {
return name;
@ -637,7 +696,6 @@ class Interface extends TypeDefinition {
Interface(JsonObject jsonElement) {
super(null, jsonElement);
for (Map.Entry<String, JsonElement> m : jsonElement.get("methods").getAsJsonObject().entrySet()) {
methods.add(new Method(this, m.getValue().getAsJsonObject()));
}
@ -679,6 +737,7 @@ class Interface extends TypeDefinition {
}
}
writeJavadoc(output, offset, formattedComment());
output.add("public interface " + jsonName + implementsClause + " {");
offset = " ";
writeSharedTypes(output, offset);

23
playwright/src/main/java/com/microsoft/playwright/Accessibility.java
View File

@ -18,6 +18,17 @@ 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.
* <p>
* Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output.
* <p>
* Blink - Chromium's rendering engine - has a concept of "accessibility tree", which is then translated into different platform-specific APIs. Accessibility namespace gives users
* <p>
* access to the Blink Accessibility Tree.
* <p>
* 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 {
public Boolean interestingOnly;
@ -35,6 +46,18 @@ public interface Accessibility {
default AccessibilityNode snapshot() {
return snapshot(null);
}
/**
* Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page.
* <p>
* <strong>NOTE</strong> The Chromium accessibility tree contains nodes that go unused on most platforms and by
* <p>
* most screen readers. Playwright will discard them as well for an easier to process tree,
* <p>
* unless {@code interestingOnly} is set to {@code false}.
* <p>
*
* @return An AXNode object with the following properties:
*/
AccessibilityNode snapshot(SnapshotOptions options);
}

32
playwright/src/main/java/com/microsoft/playwright/Browser.java
View File

@ -18,6 +18,10 @@ package com.microsoft.playwright;
import java.util.*;
/**
* A Browser is created when Playwright connects to a browser instance, either through {@code browserType.launch} or {@code browserType.connect}.
* <p>
*/
public interface Browser {
enum EventType {
DISCONNECTED,
@ -385,17 +389,45 @@ public interface Browser {
return this.recordHar;
}
}
/**
* In case this browser is obtained using browserType.launch, closes the browser and all of its pages (if any were opened).
* <p>
* In case this browser is obtained using browserType.connect, clears all created contexts belonging to this browser and disconnects from the browser server.
* <p>
* The 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
* <p>
* browser contexts.
* <p>
*/
List<BrowserContext> contexts();
/**
* Indicates that the browser is connected.
*/
boolean isConnected();
default BrowserContext newContext() {
return newContext(null);
}
/**
* Creates a new browser context. It won't share cookies/cache with other browser contexts.
* <p>
*/
BrowserContext newContext(NewContextOptions options);
default Page newPage() {
return newPage(null);
}
/**
* Creates a new page in a new browser context. Closing this page will close the context as well.
* <p>
* 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 browser.newContext followed by the browserContext.newPage to control their exact life times.
*/
Page newPage(NewPageOptions options);
/**
* Returns the browser version.
*/
String version();
}

174
playwright/src/main/java/com/microsoft/playwright/BrowserContext.java
View File

@ -21,6 +21,18 @@ import java.util.function.Consumer;
import java.util.function.Predicate;
import java.util.regex.Pattern;
/**
* BrowserContexts provide a way to operate multiple independent browser sessions.
* <p>
* If a page opens another page, e.g. with a {@code window.open} call, the popup will belong to the parent page's browser
* <p>
* context.
* <p>
* Playwright allows creation of "incognito" browser contexts with {@code browser.newContext()} method.
* <p>
* "Incognito" browser contexts don't write any browsing data to disk.
* <p>
*/
public interface BrowserContext {
enum SameSite { STRICT, LAX, NONE }
@ -165,38 +177,190 @@ public interface BrowserContext {
default void addInitScript(String script) {
addInitScript(script, null);
}
/**
* Adds a script which would be evaluated in one of the following scenarios:
* <p>
* Whenever a page is created in the browser context or is navigated.
* <p>
* 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.
* <p>
* 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}.
* <p>
*
* <p>
* <strong>NOTE</strong> The order of evaluation of multiple scripts installed via browserContext.addInitScript(script[, arg]) and page.addInitScript(script[, arg]) 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).
*/
void addInitScript(String script, Object arg);
/**
*
* @return Returns the browser instance of the context. If it was launched as a persistent context null gets returned.
*/
Browser browser();
/**
* Clears context cookies.
*/
void clearCookies();
/**
* Clears all permission overrides for the browser context.
* <p>
*/
void clearPermissions();
/**
* Closes the browser context. All the pages that belong to the browser context
* <p>
* will be closed.
* <p>
* <strong>NOTE</strong> the default browser context cannot be closed.
*/
void close();
default List<Cookie> cookies() { return cookies((List<String>) null); }
default List<Cookie> cookies(String url) { return cookies(Arrays.asList(url)); }
/**
* If no URLs are specified, this method returns all cookies.
* <p>
* If URLs are specified, only cookies that affect those URLs are returned.
*/
List<Cookie> cookies(List<String> urls);
default void exposeBinding(String name, Page.Binding playwrightBinding) {
exposeBinding(name, playwrightBinding, null);
}
/**
* The method adds a function called {@code name} on the {@code window} object of every frame in every page in the context.
* <p>
* When called, the function executes {@code playwrightBinding} in Node.js and returns a Promise which resolves to the return value of {@code playwrightBinding}.
* <p>
* If the {@code playwrightBinding} returns a Promise, it will be awaited.
* <p>
* The first argument of the {@code playwrightBinding} function contains information about the caller:
* <p>
* {@code { browserContext: BrowserContext, page: Page, frame: Frame }}.
* <p>
* See page.exposeBinding(name, playwrightBinding) 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.
*/
void exposeBinding(String name, Page.Binding playwrightBinding, ExposeBindingOptions options);
/**
* The method adds a function called {@code name} on the {@code window} object of every frame in every page in the context.
* <p>
* When called, the function executes {@code playwrightFunction} in Node.js and returns a Promise which resolves to the return value of {@code playwrightFunction}.
* <p>
* If the {@code playwrightFunction} returns a Promise, it will be awaited.
* <p>
* See page.exposeFunction(name, playwrightFunction) 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.
*/
void exposeFunction(String name, Page.Function playwrightFunction);
default void grantPermissions(List<String> permissions) {
grantPermissions(permissions, null);
}
/**
* 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'}
*/
void grantPermissions(List<String> permissions, GrantPermissionsOptions options);
/**
* Creates a new page in the browser context.
*/
Page newPage();
/**
*
* @return All open pages in the context. Non visible pages, such as {@code "background_page"}, will not be listed here. You can find them using chromiumBrowserContext.backgroundPages().
*/
List<Page> pages();
void route(String url, Consumer<Route> handler);
void route(Pattern url, Consumer<Route> handler);
/**
* Routing provides the capability to modify network requests that are made by any page in the browser context.
* <p>
* Once route is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
* <p>
* or the same snippet using a regex pattern instead:
* <p>
* Page routes (set up with page.route(url, handler)) take precedence over browser context routes when request matches both handlers.
* <p>
* <strong>NOTE</strong> 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<String> url, Consumer<Route> handler);
/**
* This setting will change the default maximum navigation time for the following methods and related shortcuts:
* <p>
* page.goBack([options])
* <p>
* page.goForward([options])
* <p>
* page.goto(url[, options])
* <p>
* page.reload([options])
* <p>
* page.setContent(html[, options])
* <p>
* page.waitForNavigation([options])
* <p>
*
* <p>
* <strong>NOTE</strong> {@code page.setDefaultNavigationTimeout} and {@code page.setDefaultTimeout} take priority over {@code 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.
* <p>
* <strong>NOTE</strong> {@code page.setDefaultNavigationTimeout}, {@code page.setDefaultTimeout} and {@code browserContext.setDefaultNavigationTimeout} take priority over {@code 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 page.setExtraHTTPHeaders(). If page overrides a particular header, page-specific header value will be used instead of the browser context header value.
* <p>
* <strong>NOTE</strong> {@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<String, String> headers);
/**
* Sets the context's geolocation. Passing {@code null} or {@code undefined} emulates position unavailable.
* <p>
*
* <p>
* <strong>NOTE</strong> Consider using browserContext.grantPermissions to grant permissions for the browser context pages to read its geolocation.
*/
void setGeolocation(Geolocation geolocation);
/**
*
* @param offline Whether to emulate network being offline for the browser context.
*/
void setOffline(boolean offline);
default void unroute(String url) { unroute(url, null); }
default void unroute(Pattern url) { unroute(url, null); }
default void unroute(Predicate<String> url) { unroute(url, null); }
void unroute(String url, Consumer<Route> handler);
void unroute(Pattern url, Consumer<Route> handler);
/**
* Removes a route created with 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 browserContext.route(url, handler).
* @param handler Handler function used to register a routing with browserContext.route(url, handler).
*/
void unroute(Predicate<String> url, Consumer<Route> handler);
default Deferred<Event<EventType>> waitForEvent(EventType event) {
return waitForEvent(event, (WaitForEventOptions) null);
@ -206,6 +370,16 @@ public interface BrowserContext {
options.predicate = predicate;
return waitForEvent(event, options);
}
/**
* Waits for event to fire and passes its value into the predicate function. Resolves when the predicate returns truthy value. Will throw an error if the context closes before the event
* <p>
* is fired.
* <p>
*
* @param event Event name, same one would pass into {@code browserContext.on(event)}.
* @param optionsOrPredicate Either a predicate that receives an event or an options object.
* @return Promise which resolves to the event data value.
*/
Deferred<Event<EventType>> waitForEvent(EventType event, WaitForEventOptions options);
}

34
playwright/src/main/java/com/microsoft/playwright/BrowserType.java
View File

@ -18,6 +18,12 @@ package com.microsoft.playwright;
import java.util.*;
/**
* BrowserType provides methods to launch a specific browser instance or connect to an existing one.
* <p>
* The following is a typical example of using Playwright to drive automation:
* <p>
*/
public interface BrowserType {
class ConnectOptions {
public String wsEndpoint;
@ -511,15 +517,43 @@ public interface BrowserType {
return this;
}
}
/**
*
* @return A path where Playwright expects to find a bundled browser executable.
*/
String executablePath();
default Browser launch() {
return launch(null);
}
/**
* You can use {@code ignoreDefaultArgs} to filter out {@code --mute-audio} from default arguments:
* <p>
*
* <p>
* **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.
* <p>
* If Google Chrome (rather than Chromium) is preferred, a Chrome Canary or Dev Channel build is suggested.
* <p>
* In browserType.launch([options]) above, any mention of Chromium also applies to Chrome.
* <p>
* See {@code this article} for a description of the differences between Chromium and Chrome. {@code This article} describes some differences for Linux users.
* @param options Set of configurable options to set on the browser. Can have the following fields:
* @return Promise which resolves to browser instance.
*/
Browser launch(LaunchOptions options);
default BrowserContext launchPersistentContext(String userDataDir) {
return launchPersistentContext(userDataDir, null);
}
/**
* 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.
* @param options Set of configurable options to set on the browser. Can have the following fields:
* @return Promise that resolves to the persistent browser context instance.
*/
BrowserContext launchPersistentContext(String userDataDir, LaunchPersistentContextOptions options);
/**
* Returns browser name. For example: {@code 'chromium'}, {@code 'webkit'} or {@code 'firefox'}.
*/
String name();
}

24
playwright/src/main/java/com/microsoft/playwright/CDPSession.java
View File

@ -18,11 +18,35 @@ package com.microsoft.playwright;
import java.util.*;
/**
* The {@code CDPSession} instances are used to talk raw Chrome Devtools Protocol:
* <p>
* protocol methods can be called with {@code session.send} method.
* <p>
* protocol events can be subscribed to with {@code session.on} method.
* <p>
* Useful links:
* <p>
* Documentation on DevTools Protocol can be found here: DevTools Protocol Viewer.
* <p>
* Getting Started with DevTools Protocol: https://github.com/aslushnikov/getting-started-with-cdp/blob/master/README.md
* <p>
*/
public interface CDPSession {
/**
* Detaches the CDPSession from the target. Once detached, the CDPSession object won't emit any events and can't be used
* <p>
* to send messages.
*/
void detach();
default Object send(String method) {
return send(method, null);
}
/**
*
* @param method protocol method name
* @param params Optional method parameters
*/
Object send(String method, Object params);
}

19
playwright/src/main/java/com/microsoft/playwright/ChromiumBrowser.java
View File

@ -19,6 +19,12 @@ package com.microsoft.playwright;
import java.nio.file.Path;
import java.util.*;
/**
* Chromium-specific features including Tracing, service worker support, etc.
* <p>
* You can use {@code chromiumBrowser.startTracing} and {@code chromiumBrowser.stopTracing} to create a trace file which can be opened in Chrome DevTools or timeline viewer.
* <p>
*/
public interface ChromiumBrowser extends Browser {
class StartTracingOptions {
public Path path;
@ -38,6 +44,11 @@ public interface ChromiumBrowser extends Browser {
return this;
}
}
/**
*
* @return Promise that resolves to the newly created browser
* session.
*/
CDPSession newBrowserCDPSession();
default void startTracing(Page page) {
startTracing(page, null);
@ -45,7 +56,15 @@ public interface ChromiumBrowser extends Browser {
default void startTracing() {
startTracing(null);
}
/**
* Only one trace can be active at a time per browser.
* @param page Optional, if specified, tracing includes screenshots of the given page.
*/
void startTracing(Page page, StartTracingOptions options);
/**
*
* @return Promise which resolves to buffer with trace data.
*/
byte[] stopTracing();
}

17
playwright/src/main/java/com/microsoft/playwright/ChromiumBrowserContext.java
View File

@ -18,6 +18,10 @@ package com.microsoft.playwright;
import java.util.*;
/**
* Chromium-specific features including background pages, service worker support, etc.
* <p>
*/
public interface ChromiumBrowserContext extends BrowserContext {
enum EventType {
BACKGROUNDPAGE,
@ -26,8 +30,21 @@ public interface ChromiumBrowserContext extends BrowserContext {
void addListener(EventType type, Listener<EventType> listener);
void removeListener(EventType type, Listener<EventType> listener);
/**
*
* @return All existing background pages in the context.
*/
List<Page> backgroundPages();
/**
*
* @param page Page to create new session for.
* @return Promise that resolves to the newly created session.
*/
CDPSession newCDPSession(Page page);
/**
*
* @return All existing service workers in the context.
*/
List<Worker> serviceWorkers();
}

23
playwright/src/main/java/com/microsoft/playwright/ChromiumCoverage.java
View File

@ -18,6 +18,9 @@ package com.microsoft.playwright;
import java.util.*;
/**
* Coverage gathers information about parts of JavaScript and CSS that were used by the page.
*/
public interface ChromiumCoverage {
class StartCSSCoverageOptions {
public Boolean resetOnNavigation;
@ -77,12 +80,32 @@ public interface ChromiumCoverage {
default void startCSSCoverage() {
startCSSCoverage(null);
}
/**
*
* @param options Set of configurable options for coverage
* @return Promise that resolves when coverage is started
*/
void startCSSCoverage(StartCSSCoverageOptions options);
default void startJSCoverage() {
startJSCoverage(null);
}
/**
* <strong>NOTE</strong> Anonymous scripts are ones that don't have an associated url. These are scripts that are dynamically created on the page using {@code eval} or {@code new Function}. If {@code reportAnonymousScripts} is set to {@code true}, anonymous scripts will have {@code __playwright_evaluation_script__} as their URL.
* @param options Set of configurable options for coverage
* @return Promise that resolves when coverage is started
*/
void startJSCoverage(StartJSCoverageOptions options);
/**
* <strong>NOTE</strong> CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
* @return Promise that resolves to the array of coverage reports for all stylesheets
*/
ChromiumCoverageStopCSSCoverage stopCSSCoverage();
/**
* <strong>NOTE</strong> JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are
* <p>
* reported.
* @return Promise that resolves to the array of coverage reports for all scripts
*/
ChromiumCoverageStopJSCoverage stopJSCoverage();
}

6
playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java
View File

@ -18,6 +18,9 @@ package com.microsoft.playwright;
import java.util.*;
/**
* ConsoleMessage objects are dispatched by page via the 'console' event.
*/
public interface ConsoleMessage {
class Location {
private String url;
@ -37,6 +40,9 @@ public interface ConsoleMessage {
List<JSHandle> args();
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'}.
*/
String type();
}

24
playwright/src/main/java/com/microsoft/playwright/Dialog.java
View File

@ -18,16 +18,40 @@ package com.microsoft.playwright;
import java.util.*;
/**
* Dialog objects are dispatched by page via the 'dialog' event.
*/
public interface Dialog {
enum Type { ALERT, BEFOREUNLOAD, CONFIRM, PROMPT }
default void accept() {
accept(null);
}
/**
*
* @param promptText A text to enter in prompt. Does not cause any effects if the dialog's {@code type} is not prompt.
* @return Promise which resolves when the dialog has been accepted.
*/
void accept(String promptText);
/**
*
* @return If dialog is prompt, returns default prompt value. Otherwise, returns empty string.
*/
String defaultValue();
/**
*
* @return Promise which resolves when the dialog has been dismissed.
*/
void dismiss();
/**
*
* @return A message displayed in the dialog.
*/
String message();
/**
*
* @return Dialog's type, can be one of {@code alert}, {@code beforeunload}, {@code confirm} or {@code prompt}.
*/
Type type();
}

35
playwright/src/main/java/com/microsoft/playwright/Download.java
View File

@ -20,13 +20,48 @@ import java.io.InputStream;
import java.nio.file.Path;
import java.util.*;
/**
* Download objects are dispatched by page via the 'download' event.
* <p>
* 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.
* <p>
* Download event is emitted once the download starts. Download path becomes available
* <p>
* once download completes:
* <p>
*
* <p>
* <strong>NOTE</strong> 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 {
/**
* Returns readable stream for current download or {@code null} if download failed.
*/
InputStream createReadStream();
/**
* Deletes the downloaded file.
*/
void delete();
/**
* Returns download error if any.
*/
String failure();
/**
* Returns path to the downloaded file in case of successful download.
*/
Path path();
/**
* Saves the download to a user-specified path.
* @param path Path where the download should be saved.
*/
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.
*/
String suggestedFilename();
/**
* Returns downloaded url.
*/
String url();
}

291
playwright/src/main/java/com/microsoft/playwright/ElementHandle.java
View File

@ -19,6 +19,13 @@ package com.microsoft.playwright;
import java.nio.file.Path;
import java.util.*;
/**
* ElementHandle represents an in-page DOM element. ElementHandles can be created with the page.$ method.
* <p>
* ElementHandle prevents DOM element from garbage collection unless the handle is disposed. ElementHandles are auto-disposed when their origin frame gets navigated.
* <p>
* ElementHandle instances can be used as an argument in {@code page.$eval()} and {@code page.evaluate()} methods.
*/
public interface ElementHandle extends JSHandle {
class BoundingBox {
public double x;
@ -385,58 +392,249 @@ public interface ElementHandle extends JSHandle {
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, the return value resolves to {@code null}.
* @param selector A selector to query element for. See 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, the return value resolves to {@code []}.
* @param selector A selector to query element for. See working with selectors for more details.
*/
List<ElementHandle> querySelectorAll(String selector);
default Object evalOnSelector(String selector, String pageFunction) {
return evalOnSelector(selector, pageFunction, null);
}
/**
* 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.
* <p>
* If {@code pageFunction} returns a Promise, then {@code frame.$eval} would wait for the promise to resolve and return its value.
* <p>
* Examples:
* <p>
*
* @param selector A selector to query element for. See working with selectors for more details.
* @param pageFunction Function to be evaluated in browser context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction}
*/
Object evalOnSelector(String selector, String pageFunction, Object arg);
default Object evalOnSelectorAll(String selector, String pageFunction) {
return evalOnSelectorAll(selector, pageFunction, null);
}
/**
* 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.
* <p>
* If {@code pageFunction} returns a Promise, then {@code frame.$$eval} would wait for the promise to resolve and return its value.
* <p>
* Examples:
* <p>
*
* @param selector A selector to query element for. See working with selectors for more details.
* @param pageFunction Function to be evaluated in browser context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction}
*/
Object evalOnSelectorAll(String selector, String pageFunction, Object arg);
/**
* This method returns the bounding box of the element (relative to the main frame), or {@code null} if the element is not visible.
*/
BoundingBox boundingBox();
default void check() {
check(null);
}
/**
* This method checks the element by performing the following steps:
* <p>
* 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.
* <p>
* Wait for actionability checks on the element, unless {@code force} option is set.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to click in the center of the element.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* Ensure that the element is now checked. If not, this method rejects.
* <p>
* If the element is detached from the DOM at any moment during the action, this method rejects.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* @return Promise that resolves when the element is successfully checked.
*/
void check(CheckOptions options);
default void click() {
click(null);
}
/**
* This method clicks the element by performing the following steps:
* <p>
* Wait for actionability checks on the element, unless {@code force} option is set.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to click in the center of the element, or the specified {@code position}.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* If the element is detached from the DOM at any moment during the action, this method rejects.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* @return Promise that resolves when the element is successfully clicked.
*/
void click(ClickOptions options);
/**
*
* @return Resolves to the content frame for element handles referencing iframe nodes, or {@code null} otherwise
*/
Frame contentFrame();
default void dblclick() {
dblclick(null);
}
/**
* This method double clicks the element by performing the following steps:
* <p>
* Wait for actionability checks on the element, unless {@code force} option is set.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to double click in the center of the element, or the specified {@code position}.
* <p>
* 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.
* <p>
* If the element is detached from the DOM at any moment during the action, this method rejects.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* <p>
* <strong>NOTE</strong> {@code elementHandle.dblclick()} dispatches two {@code click} events and a single {@code dblclick} event.
* @return Promise that resolves when the element is successfully double clicked.
*/
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 {@code element.click()}.
* <p>
* 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.
* <p>
* Since {@code eventInit} is event-specific, please refer to the events documentation for the lists of initial properties:
* <p>
* DragEvent
* <p>
* FocusEvent
* <p>
* KeyboardEvent
* <p>
* MouseEvent
* <p>
* PointerEvent
* <p>
* TouchEvent
* <p>
* Event
* <p>
* You can also specify {@code JSHandle} as the property value if you want live objects to be passed into the event:
* <p>
*
* @param type DOM event type: {@code "click"}, {@code "dragstart"}, etc.
* @param eventInit event-specific initialization properties.
*/
void dispatchEvent(String type, Object eventInit);
default void fill(String value) {
fill(value, null);
}
/**
* This method waits for actionability checks, focuses the element, fills it and triggers an {@code input} event after filling.
* <p>
* If the element is not an {@code <input>}, {@code <textarea>} or {@code [contenteditable]} element, this method throws an error.
* <p>
* Note that you can pass an empty string to clear the input field.
* @param value Value to set for the {@code <input>}, {@code <textarea>} or {@code [contenteditable]} element.
*/
void fill(String value, FillOptions options);
/**
* Calls focus on the element.
*/
void focus();
/**
* Returns element attribute value.
* @param name Attribute name to get the value for.
*/
String getAttribute(String name);
default void hover() {
hover(null);
}
/**
* This method hovers over the element by performing the following steps:
* <p>
* Wait for actionability checks on the element, unless {@code force} option is set.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to hover over the center of the element, or the specified {@code position}.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* If the element is detached from the DOM at any moment during the action, this method rejects.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* @return Promise that resolves when the element is successfully hovered.
*/
void hover(HoverOptions options);
/**
*
* @return Resolves to the {@code element.innerHTML}.
*/
String innerHTML();
/**
*
* @return Resolves to the {@code element.innerText}.
*/
String innerText();
/**
*
* @return Returns the frame containing the given element.
*/
Frame ownerFrame();
default void press(String key) {
press(key, null);
}
/**
* Focuses the element, and then uses {@code keyboard.down} and {@code keyboard.up}.
* <p>
* {@code key} can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the {@code key} values can be found here. Examples of the keys are:
* <p>
* {@code F1} - {@code F12}, {@code Digit0}- {@code Digit9}, {@code KeyA}- {@code KeyZ}, {@code Backquote}, {@code Minus}, {@code Equal}, {@code Backslash}, {@code Backspace}, {@code Tab}, {@code Delete}, {@code Escape}, {@code ArrowDown}, {@code End}, {@code Enter}, {@code Home}, {@code Insert}, {@code PageDown}, {@code PageUp}, {@code ArrowRight}, {@code ArrowUp}, etc.
* <p>
* Following modification shortcuts are also suported: {@code Shift}, {@code Control}, {@code Alt}, {@code Meta}, {@code ShiftLeft}.
* <p>
* Holding down {@code Shift} will type the text that corresponds to the {@code key} in the upper case.
* <p>
* If {@code key} is a single character, it is case-sensitive, so the values {@code a} and {@code A} will generate different respective texts.
* <p>
* Shortcuts such as {@code key: "Control+o"} or {@code key: "Control+Shift+T"} are supported as well. When speficied with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
* @param key Name of the key to press or a character to generate, such as {@code ArrowLeft} or {@code a}.
*/
void press(String key, PressOptions options);
default byte[] screenshot() {
return screenshot(null);
}
/**
* This method waits for the actionability checks, then scrolls element into view before taking a screenshot. If the element is detached from DOM, the method throws an error.
* @param options Screenshot options.
* @return Promise which resolves to buffer with the captured screenshot.
*/
byte[] screenshot(ScreenshotOptions options);
default void scrollIntoViewIfNeeded() {
scrollIntoViewIfNeeded(null);
}
/**
* This method waits for actionability checks, then tries to scroll element into view, unless it is completely visible as defined by IntersectionObserver's {@code ratio}.
* <p>
* Throws when {@code elementHandle} does not point to an element connected to a Document or a ShadowRoot.
*/
void scrollIntoViewIfNeeded(ScrollIntoViewIfNeededOptions options);
default List<String> selectOption(String value) {
return selectOption(value, null);
@ -476,10 +674,22 @@ public interface ElementHandle extends JSHandle {
default List<String> selectOption(ElementHandle[] values) {
return selectOption(values, null);
}
/**
* Triggers a {@code change} and {@code input} event once all the provided options have been selected.
* <p>
* If element is not a {@code <select>} element, the method throws an error.
* <p>
*
* @param values Options to select. If the {@code <select>} has the {@code multiple} attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to {@code {value:'string'}}. Option is considered matching if all specified properties match.
* @return An array of option values that have been successfully selected.
*/
List<String> selectOption(ElementHandle[] values, SelectOptionOptions options);
default void selectText() {
selectText(null);
}
/**
* This method waits for actionability checks, then focuses the element and selects all its text content.
*/
void selectText(SelectTextOptions options);
default void setInputFiles(Path file) { setInputFiles(file, null); }
default void setInputFiles(Path file, SetInputFilesOptions options) { setInputFiles(new Path[]{ file }, options); }
@ -488,28 +698,109 @@ public interface ElementHandle extends JSHandle {
default void setInputFiles(FileChooser.FilePayload file) { setInputFiles(file, null); }
default void setInputFiles(FileChooser.FilePayload file, SetInputFilesOptions options) { setInputFiles(new FileChooser.FilePayload[]{ file }, options); }
default void setInputFiles(FileChooser.FilePayload[] files) { setInputFiles(files, null); }
/**
* This method expects {@code elementHandle} to point to an input element.
* <p>
* Sets the value of the file input to these file paths or files. If some of the {@code filePaths} are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.
*/
void setInputFiles(FileChooser.FilePayload[] files, SetInputFilesOptions options);
default void tap() {
tap(null);
}
/**
* This method taps the element by performing the following steps:
* <p>
* Wait for actionability checks on the element, unless {@code force} option is set.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.touchscreen to tap in the center of the element, or the specified {@code position}.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* If the element is detached from the DOM at any moment during the action, this method rejects.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* <p>
* <strong>NOTE</strong> {@code elementHandle.tap()} requires that the {@code hasTouch} option of the browser context be set to true.
* @return Promise that resolves when the element is successfully tapped.
*/
void tap(TapOptions options);
/**
*
* @return Resolves to the {@code node.textContent}.
*/
String textContent();
String toString();
default void type(String text) {
type(text, null);
}
/**
* Focuses the element, and then sends a {@code keydown}, {@code keypress}/{@code input}, and {@code keyup} event for each character in the text.
* <p>
* To press a special key, like {@code Control} or {@code ArrowDown}, use {@code elementHandle.press}.
* <p>
*
* @param text A text to type into a focused element.
*/
void type(String text, TypeOptions options);
default void uncheck() {
uncheck(null);
}
/**
* This method checks the element by performing the following steps:
* <p>
* Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately.
* <p>
* Wait for actionability checks on the element, unless {@code force} option is set.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to click in the center of the element.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* Ensure that the element is now unchecked. If not, this method rejects.
* <p>
* If the element is detached from the DOM at any moment during the action, this method rejects.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* @return Promise that resolves when the element is successfully unchecked.
*/
void uncheck(UncheckOptions options);
default Deferred<Void> waitForElementState(ElementState state) {
return waitForElementState(state, null);
}
/**
* Depending on the {@code state} parameter, this method waits for one of the actionability checks to pass. This method throws when the element is detached while waiting, unless waiting for the {@code "hidden"} state.
* <p>
* {@code "visible"} Wait until the element is visible.
* <p>
* {@code "hidden"} Wait until the element is not visible or not attached. Note that waiting for hidden does not throw when the element detaches.
* <p>
* {@code "stable"} Wait until the element is both visible and stable.
* <p>
* {@code "enabled"} Wait until the element is enabled.
* <p>
* {@code "disabled"} Wait until the element is not enabled.
* <p>
* If the element does not satisfy the condition for the {@code timeout} milliseconds, this method will throw.
* @param state A state to wait for, see below for more details.
* @return Promise that resolves when the element satisfies the {@code state}.
*/
Deferred<Void> waitForElementState(ElementState state, WaitForElementStateOptions options);
default Deferred<ElementHandle> waitForSelector(String selector) {
return waitForSelector(selector, null);
}
/**
* Wait for the {@code selector} relative to the element handle to satisfy {@code state} option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method {@code selector} already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the {@code timeout} milliseconds, the function will throw.
* <p>
*
* <p>
* <strong>NOTE</strong> This method does not work across navigations, use page.waitForSelector(selector[, options]) instead.
* @param selector A selector of an element to wait for, relative to the element handle. See working with selectors for more details.
* @return Promise that resolves when element specified by selector satisfies {@code state} option. Resolves to {@code null} if waiting for {@code hidden} or {@code detached}.
*/
Deferred<ElementHandle> waitForSelector(String selector, WaitForSelectorOptions options);
}

16
playwright/src/main/java/com/microsoft/playwright/FileChooser.java
View File

@ -19,6 +19,10 @@ package com.microsoft.playwright;
import java.nio.file.Path;
import java.util.*;
/**
* FileChooser objects are dispatched by the page in the 'filechooser' event.
* <p>
*/
public interface FileChooser {
class FilePayload {
public final String name;
@ -45,8 +49,17 @@ public interface FileChooser {
return this;
}
}
/**
* Returns input element associated with this file chooser.
*/
ElementHandle element();
/**
* Returns whether this file chooser accepts multiple files.
*/
boolean isMultiple();
/**
* Returns page this file chooser belongs to.
*/
Page page();
default void setFiles(Path file) { setFiles(file, null); }
default void setFiles(Path file, SetFilesOptions options) { setFiles(new Path[]{ file }, options); }
@ -55,6 +68,9 @@ public interface FileChooser {
default void setFiles(FileChooser.FilePayload file) { setFiles(file, null); }
default void setFiles(FileChooser.FilePayload file, SetFilesOptions options) { setFiles(new FileChooser.FilePayload[]{ file }, options); }
default void setFiles(FileChooser.FilePayload[] files) { setFiles(files, null); }
/**
* Sets the value of the file input this chooser is associated with. If some of the {@code filePaths} are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.
*/
void setFiles(FileChooser.FilePayload[] files, SetFilesOptions options);
}

3
playwright/src/main/java/com/microsoft/playwright/FirefoxBrowser.java
View File

@ -18,6 +18,9 @@ package com.microsoft.playwright;
import java.util.*;
/**
* Firefox browser instance does not expose Firefox-specific features.
*/
public interface FirefoxBrowser extends Browser {
}

410
playwright/src/main/java/com/microsoft/playwright/Frame.java
View File

@ -21,6 +21,18 @@ import java.util.*;
import java.util.function.Predicate;
import java.util.regex.Pattern;
/**
* At every point of time, page exposes its current frame tree via the page.mainFrame() and frame.childFrames() methods.
* <p>
* Frame object's lifecycle is controlled by three events, dispatched on the page object:
* <p>
* 'frameattached' - fired when the frame gets attached to the page. A Frame can be attached to the page only once.
* <p>
* 'framenavigated' - fired when the frame commits navigation to a different URL.
* <p>
* 'framedetached' - fired when the frame gets detached from the page. A Frame can be detached from the page only once.
* <p>
*/
public interface Frame {
enum LoadState { DOMCONTENTLOADED, LOAD, NETWORKIDLE }
class AddScriptTagOptions {
@ -481,31 +493,135 @@ public interface Frame {
return this;
}
}
/**
* The method finds an element matching the specified selector within the frame. See Working with selectors for more details. If no elements match the selector, the return value resolves to {@code null}.
* @param selector A selector to query frame for. See working with selectors for more details.
* @return Promise which resolves to ElementHandle pointing to the frame element.
*/
ElementHandle querySelector(String selector);
/**
* The method finds all elements matching the specified selector within the frame. See Working with selectors for more details. If no elements match the selector, the return value resolves to {@code []}.
* @param selector A selector to query frame for. See working with selectors for more details.
* @return Promise which resolves to ElementHandles pointing to the frame elements.
*/
List<ElementHandle> querySelectorAll(String selector);
default Object evalOnSelector(String selector, String pageFunction) {
return evalOnSelector(selector, pageFunction, null);
}
/**
* The method finds an element matching the specified selector within the frame 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.
* <p>
* If {@code pageFunction} returns a Promise, then {@code frame.$eval} would wait for the promise to resolve and return its value.
* <p>
* Examples:
* <p>
*
* @param selector A selector to query frame for. See working with selectors for more details.
* @param pageFunction Function to be evaluated in browser context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction}
*/
Object evalOnSelector(String selector, String pageFunction, Object arg);
default Object evalOnSelectorAll(String selector, String pageFunction) {
return evalOnSelectorAll(selector, pageFunction, null);
}
/**
* The method finds all elements matching the specified selector within the frame and passes an array of matched elements as a first argument to {@code pageFunction}. See Working with selectors for more details.
* <p>
* If {@code pageFunction} returns a Promise, then {@code frame.$$eval} would wait for the promise to resolve and return its value.
* <p>
* Examples:
* <p>
*
* @param selector A selector to query frame for. See working with selectors for more details.
* @param pageFunction Function to be evaluated in browser context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction}
*/
Object evalOnSelectorAll(String selector, String pageFunction, Object arg);
/**
* Adds a {@code <script>} tag into the page with the desired url or content.
* @return which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
*/
ElementHandle addScriptTag(AddScriptTagOptions options);
/**
* Adds a {@code <link rel="stylesheet">} tag into the page with the desired url or a {@code <style type="text/css">} tag with the content.
* @return which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
*/
ElementHandle addStyleTag(AddStyleTagOptions options);
default void check(String selector) {
check(selector, null);
}
/**
* This method checks an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to click in the center of the element.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* Ensure that the element is now checked. If not, this method rejects.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* @param selector A selector to search for checkbox to check. If there are multiple elements satisfying the selector, the first will be checked. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully checked.
*/
void check(String selector, CheckOptions options);
List<Frame> childFrames();
default void click(String selector) {
click(selector, null);
}
/**
* This method clicks an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to click in the center of the element, or the specified {@code position}.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* @param selector A selector to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully clicked.
*/
void click(String selector, ClickOptions options);
/**
* Gets the full HTML contents of the frame, including the doctype.
*/
String content();
default void dblclick(String selector) {
dblclick(selector, null);
}
/**
* This method double clicks an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to double click in the center of the element, or the specified {@code position}.
* <p>
* 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.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* <p>
* <strong>NOTE</strong> {@code frame.dblclick()} dispatches two {@code click} events and a single {@code dblclick} event.
* @param selector A selector to search for element to double click. If there are multiple elements satisfying the selector, the first will be double clicked. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully double clicked.
*/
void dblclick(String selector, DblclickOptions options);
default void dispatchEvent(String selector, String type, Object eventInit) {
dispatchEvent(selector, type, eventInit, null);
@ -513,51 +629,219 @@ public interface Frame {
default void dispatchEvent(String selector, String type) {
dispatchEvent(selector, 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 {@code element.click()}.
* <p>
* 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.
* <p>
* Since {@code eventInit} is event-specific, please refer to the events documentation for the lists of initial properties:
* <p>
* DragEvent
* <p>
* FocusEvent
* <p>
* KeyboardEvent
* <p>
* MouseEvent
* <p>
* PointerEvent
* <p>
* TouchEvent
* <p>
* Event
* <p>
* You can also specify {@code JSHandle} as the property value if you want live objects to be passed into the event:
* <p>
*
* @param selector A selector to search for element to use. If there are multiple elements satisfying the selector, the first will be double clicked. See working with selectors for more details.
* @param type DOM event type: {@code "click"}, {@code "dragstart"}, etc.
* @param eventInit event-specific initialization properties.
*/
void dispatchEvent(String selector, String type, Object eventInit, DispatchEventOptions options);
default Object evaluate(String pageFunction) {
return evaluate(pageFunction, null);
}
/**
* If the function passed to the {@code frame.evaluate} returns a Promise, then {@code frame.evaluate} would wait for the promise to resolve and return its value.
* <p>
* If the function passed to the {@code frame.evaluate} returns a non-Serializable value, then {@code frame.evaluate} resolves to {@code undefined}. DevTools Protocol also supports transferring some additional values that are not serializable by {@code JSON}: {@code -0}, {@code NaN}, {@code Infinity}, {@code -Infinity}, and bigint literals.
* <p>
* A string can also be passed in instead of a function.
* <p>
* ElementHandle instances can be passed as an argument to the {@code frame.evaluate}:
* <p>
*
* @param pageFunction Function to be evaluated in browser context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction}
*/
Object evaluate(String pageFunction, Object arg);
default JSHandle evaluateHandle(String pageFunction) {
return evaluateHandle(pageFunction, null);
}
/**
* The only difference between {@code frame.evaluate} and {@code frame.evaluateHandle} is that {@code frame.evaluateHandle} returns in-page object (JSHandle).
* <p>
* If the function, passed to the {@code frame.evaluateHandle}, returns a Promise, then {@code frame.evaluateHandle} would wait for the promise to resolve and return its value.
* <p>
* A string can also be passed in instead of a function.
* <p>
* JSHandle instances can be passed as an argument to the {@code frame.evaluateHandle}:
* <p>
*
* @param pageFunction Function to be evaluated in the page context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction} as in-page object (JSHandle)
*/
JSHandle evaluateHandle(String pageFunction, Object arg);
default void fill(String selector, String value) {
fill(selector, value, null);
}
/**
* This method waits for an element matching {@code selector}, waits for actionability checks, focuses the element, fills it and triggers an {@code input} event after filling.
* <p>
* If the element matching {@code selector} is not an {@code <input>}, {@code <textarea>} or {@code [contenteditable]} element, this method throws an error.
* <p>
* Note that you can pass an empty string to clear the input field.
* <p>
* To send fine-grained keyboard events, use {@code frame.type}.
* @param selector A selector to query page for. See working with selectors for more details.
* @param value Value to fill for the {@code <input>}, {@code <textarea>} or {@code [contenteditable]} element.
*/
void fill(String selector, String value, FillOptions options);
default void focus(String selector) {
focus(selector, null);
}
/**
* This method fetches an element with {@code selector} and focuses it.
* <p>
* If there's no element matching {@code selector}, the method waits until a matching element appears in the DOM.
* @param selector A selector of an element to focus. If there are multiple elements satisfying the selector, the first will be focused. See working with selectors for more details.
* @return Promise which resolves when the element matching {@code selector} is successfully focused. The promise will be rejected if there is no element matching {@code selector}.
*/
void focus(String selector, FocusOptions options);
/**
* This is an inverse of elementHandle.contentFrame(). Note that returned handle actually belongs to the parent frame.
* <p>
* This method throws an error if the frame has been detached before {@code frameElement()} returns.
* <p>
*
* @return Promise that resolves with a {@code frame} or {@code iframe} element handle which corresponds to this frame.
*/
ElementHandle frameElement();
default String getAttribute(String selector, String name) {
return getAttribute(selector, name, null);
}
/**
* Returns element attribute value.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be picked. See working with selectors for more details.
* @param name Attribute name to get the value for.
*/
String getAttribute(String selector, String name, GetAttributeOptions options);
default Response navigate(String url) {
return navigate(url, null);
}
/**
* {@code frame.goto} will throw an error if:
* <p>
* there's an SSL error (e.g. in case of self-signed certificates).
* <p>
* target URL is invalid.
* <p>
* the {@code timeout} is exceeded during navigation.
* <p>
* the remote server does not respond or is unreachable.
* <p>
* the main resource failed to load.
* <p>
* {@code frame.goto} will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling response.status().
* <p>
* <strong>NOTE</strong> {@code frame.goto} either throws an error or returns a main resource response. The only exceptions are navigation to {@code about:blank} or navigation to the same URL with a different hash, which would succeed and return {@code null}.
* <p>
*
* <p>
* <strong>NOTE</strong> Headless mode doesn't support navigation to a PDF document. See the upstream issue.
* @param url URL to navigate frame to. The url should include scheme, e.g. {@code https://}.
* @param options Navigation parameters which might have the following properties:
* @return Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
*/
Response navigate(String url, NavigateOptions options);
default void hover(String selector) {
hover(selector, null);
}
/**
* This method hovers over an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to hover over the center of the element, or the specified {@code position}.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* @param selector A selector to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully hovered.
*/
void hover(String selector, HoverOptions options);
default String innerHTML(String selector) {
return innerHTML(selector, null);
}
/**
* Resolves to the {@code element.innerHTML}.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be picked. See working with selectors for more details.
*/
String innerHTML(String selector, InnerHTMLOptions options);
default String innerText(String selector) {
return innerText(selector, null);
}
/**
* Resolves to the {@code element.innerText}.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be picked. See working with selectors for more details.
*/
String innerText(String selector, InnerTextOptions options);
/**
* Returns {@code true} if the frame has been detached, or {@code false} otherwise.
*/
boolean isDetached();
/**
* Returns frame's name attribute as specified in the tag.
* <p>
* If the name is empty, returns the id attribute instead.
* <p>
* <strong>NOTE</strong> This value is calculated once when the frame is created, and will not update if the attribute is changed later.
*/
String name();
/**
* Returns the page containing this frame.
*/
Page page();
/**
*
* @return Parent frame, if any. Detached frames and main frames return {@code null}.
*/
Frame parentFrame();
default void press(String selector, String key) {
press(selector, key, null);
}
/**
* {@code key} can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the {@code key} values can be found here. Examples of the keys are:
* <p>
* {@code F1} - {@code F12}, {@code Digit0}- {@code Digit9}, {@code KeyA}- {@code KeyZ}, {@code Backquote}, {@code Minus}, {@code Equal}, {@code Backslash}, {@code Backspace}, {@code Tab}, {@code Delete}, {@code Escape}, {@code ArrowDown}, {@code End}, {@code Enter}, {@code Home}, {@code Insert}, {@code PageDown}, {@code PageUp}, {@code ArrowRight}, {@code ArrowUp}, etc.
* <p>
* Following modification shortcuts are also suported: {@code Shift}, {@code Control}, {@code Alt}, {@code Meta}, {@code ShiftLeft}.
* <p>
* Holding down {@code Shift} will type the text that corresponds to the {@code key} in the upper case.
* <p>
* If {@code key} is a single character, it is case-sensitive, so the values {@code a} and {@code A} will generate different respective texts.
* <p>
* Shortcuts such as {@code key: "Control+o"} or {@code key: "Control+Shift+T"} are supported as well. When speficied with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
* @param selector A selector of an element to type into. If there are multiple elements satisfying the selector, the first will be used. See working with selectors for more details.
* @param key Name of the key to press or a character to generate, such as {@code ArrowLeft} or {@code a}.
*/
void press(String selector, String key, PressOptions options);
default List<String> selectOption(String selector, String value) {
return selectOption(selector, value, null);
@ -597,10 +881,25 @@ public interface Frame {
default List<String> selectOption(String selector, ElementHandle[] values) {
return selectOption(selector, values, null);
}
/**
* Triggers a {@code change} and {@code input} event once all the provided options have been selected.
* <p>
* If there's no {@code <select>} element matching {@code selector}, the method throws an error.
* <p>
*
* @param selector A selector to query frame for. See working with selectors for more details.
* @param values Options to select. If the {@code <select>} has the {@code multiple} attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to {@code {value:'string'}}. Option is considered matching if all specified properties match.
* @return An array of option values that have been successfully selected.
*/
List<String> selectOption(String selector, ElementHandle[] values, SelectOptionOptions options);
default void setContent(String html) {
setContent(html, null);
}
/**
*
* @param html HTML markup to assign to the page.
* @param options Parameters which might have the following properties:
*/
void setContent(String html, SetContentOptions options);
default void setInputFiles(String selector, Path file) { setInputFiles(selector, file, null); }
default void setInputFiles(String selector, Path file, SetInputFilesOptions options) { setInputFiles(selector, new Path[]{ file }, options); }
@ -609,24 +908,90 @@ public interface Frame {
default void setInputFiles(String selector, FileChooser.FilePayload file) { setInputFiles(selector, file, null); }
default void setInputFiles(String selector, FileChooser.FilePayload file, SetInputFilesOptions options) { setInputFiles(selector, new FileChooser.FilePayload[]{ file }, options); }
default void setInputFiles(String selector, FileChooser.FilePayload[] files) { setInputFiles(selector, files, null); }
/**
* This method expects {@code selector} to point to an input element.
* <p>
* Sets the value of the file input to these file paths or files. If some of the {@code filePaths} are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.
* @param selector A selector to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked. See working with selectors for more details.
*/
void setInputFiles(String selector, FileChooser.FilePayload[] files, SetInputFilesOptions options);
default void tap(String selector) {
tap(selector, null);
}
/**
* This method taps an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.touchscreen to tap the center of the element, or the specified {@code position}.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* <p>
* <strong>NOTE</strong> {@code frame.tap()} requires that the {@code hasTouch} option of the browser context be set to true.
* @param selector A selector to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully tapped.
*/
void tap(String selector, TapOptions options);
default String textContent(String selector) {
return textContent(selector, null);
}
/**
* Resolves to the {@code element.textContent}.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be picked. See working with selectors for more details.
*/
String textContent(String selector, TextContentOptions options);
/**
*
* @return The page's title.
*/
String title();
default void type(String selector, String text) {
type(selector, text, null);
}
/**
* Sends a {@code keydown}, {@code keypress}/{@code input}, and {@code keyup} event for each character in the text. {@code frame.type} can be used to send fine-grained keyboard events. To fill values in form fields, use {@code frame.fill}.
* <p>
* To press a special key, like {@code Control} or {@code ArrowDown}, use {@code keyboard.press}.
* <p>
*
* @param selector A selector of an element to type into. If there are multiple elements satisfying the selector, the first will be used. See working with selectors for more details.
* @param text A text to type into a focused element.
*/
void type(String selector, String text, TypeOptions options);
default void uncheck(String selector) {
uncheck(selector, null);
}
/**
* This method checks an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to click in the center of the element.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* Ensure that the element is now unchecked. If not, this method rejects.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* @param selector A selector to search for uncheckbox to check. If there are multiple elements satisfying the selector, the first will be checked. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully unchecked.
*/
void uncheck(String selector, UncheckOptions options);
/**
* Returns frame's url.
*/
String url();
default Deferred<JSHandle> waitForFunction(String pageFunction, Object arg) {
return waitForFunction(pageFunction, arg, null);
@ -634,6 +999,17 @@ public interface Frame {
default Deferred<JSHandle> waitForFunction(String pageFunction) {
return waitForFunction(pageFunction, null);
}
/**
* The {@code waitForFunction} can be used to observe viewport size change:
* <p>
* To pass an argument from Node.js to the predicate of {@code frame.waitForFunction} function:
* <p>
*
* @param pageFunction Function to be evaluated in browser context
* @param arg Optional argument to pass to {@code pageFunction}
* @param options Optional waiting parameters
* @return Promise which resolves when the {@code pageFunction} returns a truthy value. It resolves to a JSHandle of the truthy value.
*/
Deferred<JSHandle> waitForFunction(String pageFunction, Object arg, WaitForFunctionOptions options);
default Deferred<Void> waitForLoadState(LoadState state) {
return waitForLoadState(state, null);
@ -641,15 +1017,49 @@ public interface Frame {
default Deferred<Void> waitForLoadState() {
return waitForLoadState(null);
}
/**
* This resolves when the frame reaches a required load state, {@code load} by default. The navigation must have been committed when this method is called. If current document has already reached the required state, resolves immediately.
* <p>
*
* @param state Load state to wait for, defaults to {@code load}. If the state has been already reached while loading current document, the method resolves immediately.
* - {@code 'load'} - wait for the {@code load} event to be fired.
* - {@code 'domcontentloaded'} - wait for the {@code DOMContentLoaded} event to be fired.
* - {@code 'networkidle'} - wait until there are no network connections for at least {@code 500} ms.
* @return Promise which resolves when the required load state has been reached.
*/
Deferred<Void> waitForLoadState(LoadState state, WaitForLoadStateOptions options);
default Deferred<Response> waitForNavigation() {
return waitForNavigation(null);
}
/**
* This resolves when the frame navigates to a new URL. It is useful for when you run code
* <p>
* which will indirectly cause the frame to navigate. Consider this example:
* <p>
* <strong>NOTE</strong> Usage of the History API to change the URL is considered a navigation.
* @param options Navigation parameters which might have the following properties:
* @return Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with {@code null}.
*/
Deferred<Response> waitForNavigation(WaitForNavigationOptions options);
default Deferred<ElementHandle> waitForSelector(String selector) {
return waitForSelector(selector, null);
}
/**
* Wait for the {@code selector} to satisfy {@code state} option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method {@code selector} already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the {@code timeout} milliseconds, the function will throw.
* <p>
* This method works across navigations:
* <p>
*
* @param selector A selector of an element to wait for. See working with selectors for more details.
* @return Promise which resolves when element specified by selector satisfies {@code state} option. Resolves to {@code null} if waiting for {@code hidden} or {@code detached}.
*/
Deferred<ElementHandle> waitForSelector(String selector, WaitForSelectorOptions options);
/**
* Returns a promise that resolves after the timeout.
* <p>
* Note that {@code frame.waitForTimeout()} should only be used for debugging. Tests using the timer in production are going to be flaky. Use signals such as network events, selectors becoming visible and others instead.
* @param timeout A timeout to wait for
*/
Deferred<Void> waitForTimeout(int timeout);
}

55
playwright/src/main/java/com/microsoft/playwright/JSHandle.java
View File

@ -18,19 +18,74 @@ package com.microsoft.playwright;
import java.util.*;
/**
* JSHandle represents an in-page JavaScript object. JSHandles can be created with the page.evaluateHandle method.
* <p>
* JSHandle prevents the referenced JavaScript object being garbage collected unless the handle is disposed. JSHandles are auto-disposed when their origin frame gets navigated or the parent context gets destroyed.
* <p>
* JSHandle instances can be used as an argument in {@code page.$eval()}, {@code page.evaluate()} and {@code page.evaluateHandle()} methods.
*/
public interface JSHandle {
/**
* Returns either {@code null} or the object handle itself, if the object handle is an instance of ElementHandle.
*/
ElementHandle asElement();
/**
* The {@code jsHandle.dispose} method stops referencing the element handle.
* @return Promise which resolves when the object handle is successfully disposed.
*/
void dispose();
default Object evaluate(String pageFunction) {
return evaluate(pageFunction, null);
}
/**
* This method passes this handle as the first argument to {@code pageFunction}.
* <p>
* If {@code pageFunction} returns a Promise, then {@code handle.evaluate} would wait for the promise to resolve and return its value.
* <p>
* Examples:
* <p>
*
* @param pageFunction Function to be evaluated in browser context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction}
*/
Object evaluate(String pageFunction, Object arg);
default JSHandle evaluateHandle(String pageFunction) {
return evaluateHandle(pageFunction, null);
}
/**
* This method passes this handle as the first argument to {@code pageFunction}.
* <p>
* The only difference between {@code jsHandle.evaluate} and {@code jsHandle.evaluateHandle} is that {@code jsHandle.evaluateHandle} returns in-page object (JSHandle).
* <p>
* If the function passed to the {@code jsHandle.evaluateHandle} returns a Promise, then {@code jsHandle.evaluateHandle} would wait for the promise to resolve and return its value.
* <p>
* See page.evaluateHandle() for more details.
* @param pageFunction Function to be evaluated
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction} as in-page object (JSHandle)
*/
JSHandle evaluateHandle(String pageFunction, Object arg);
/**
* The method returns a map with **own property names** as keys and JSHandle instances for the property values.
* <p>
*/
Map<String, JSHandle> getProperties();
/**
* Fetches a single property from the referenced object.
* @param propertyName property to get
*/
JSHandle getProperty(String propertyName);
/**
* Returns a JSON representation of the object. If the object has a
* <p>
* {@code toJSON}
* <p>
* function, it **will not be called**.
* <p>
* <strong>NOTE</strong> The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an error if the object has circular references.
*/
Object jsonValue();
}

66
playwright/src/main/java/com/microsoft/playwright/Keyboard.java
View File

@ -18,19 +18,85 @@ package com.microsoft.playwright;
import java.util.*;
/**
* Keyboard provides an api for managing a virtual keyboard. The high level api is {@code keyboard.type}, which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
* <p>
* For finer control, you can use {@code keyboard.down}, {@code keyboard.up}, and {@code keyboard.insertText} to manually fire events as if they were generated from a real keyboard.
* <p>
* An example to trigger select-all with the keyboard
* <p>
*/
public interface Keyboard {
enum Modifier { ALT, CONTROL, META, SHIFT }
/**
* Dispatches a {@code keydown} event.
* <p>
* {@code key} can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the {@code key} values can be found here. Examples of the keys are:
* <p>
* {@code F1} - {@code F12}, {@code Digit0}- {@code Digit9}, {@code KeyA}- {@code KeyZ}, {@code Backquote}, {@code Minus}, {@code Equal}, {@code Backslash}, {@code Backspace}, {@code Tab}, {@code Delete}, {@code Escape}, {@code ArrowDown}, {@code End}, {@code Enter}, {@code Home}, {@code Insert}, {@code PageDown}, {@code PageUp}, {@code ArrowRight}, {@code ArrowUp}, etc.
* <p>
* Following modification shortcuts are also suported: {@code Shift}, {@code Control}, {@code Alt}, {@code Meta}, {@code ShiftLeft}.
* <p>
* Holding down {@code Shift} will type the text that corresponds to the {@code key} in the upper case.
* <p>
* If {@code key} is a single character, it is case-sensitive, so the values {@code a} and {@code A} will generate different respective texts.
* <p>
* If {@code key} is a modifier key, {@code Shift}, {@code Meta}, {@code Control}, or {@code Alt}, subsequent key presses will be sent with that modifier active. To release the modifier key, use {@code keyboard.up}.
* <p>
* After the key is pressed once, subsequent calls to {@code keyboard.down} will have repeat set to true. To release the key, use {@code keyboard.up}.
* <p>
* <strong>NOTE</strong> Modifier keys DO influence {@code keyboard.down}. Holding down {@code Shift} will type the text in upper case.
* @param key Name of the key to press or a character to generate, such as {@code ArrowLeft} or {@code a}.
*/
void down(String key);
/**
* Dispatches only {@code input} event, does not emit the {@code keydown}, {@code keyup} or {@code keypress} events.
* <p>
*
* <p>
* <strong>NOTE</strong> Modifier keys DO NOT effect {@code keyboard.insertText}. Holding down {@code Shift} will not type the text in upper case.
* @param text Sets input to the specified text value.
*/
void insertText(String text);
default void press(String key) {
press(key, 0);
}
/**
* {@code key} can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the {@code key} values can be found here. Examples of the keys are:
* <p>
* {@code F1} - {@code F12}, {@code Digit0}- {@code Digit9}, {@code KeyA}- {@code KeyZ}, {@code Backquote}, {@code Minus}, {@code Equal}, {@code Backslash}, {@code Backspace}, {@code Tab}, {@code Delete}, {@code Escape}, {@code ArrowDown}, {@code End}, {@code Enter}, {@code Home}, {@code Insert}, {@code PageDown}, {@code PageUp}, {@code ArrowRight}, {@code ArrowUp}, etc.
* <p>
* Following modification shortcuts are also suported: {@code Shift}, {@code Control}, {@code Alt}, {@code Meta}, {@code ShiftLeft}.
* <p>
* Holding down {@code Shift} will type the text that corresponds to the {@code key} in the upper case.
* <p>
* If {@code key} is a single character, it is case-sensitive, so the values {@code a} and {@code A} will generate different respective texts.
* <p>
* Shortcuts such as {@code key: "Control+o"} or {@code key: "Control+Shift+T"} are supported as well. When speficied with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
* <p>
* Shortcut for {@code keyboard.down} and {@code keyboard.up}.
* @param key Name of the key to press or a character to generate, such as {@code ArrowLeft} or {@code a}.
*/
void press(String key, int delay);
default void type(String text) {
type(text, 0);
}
/**
* Sends a {@code keydown}, {@code keypress}/{@code input}, and {@code keyup} event for each character in the text.
* <p>
* To press a special key, like {@code Control} or {@code ArrowDown}, use {@code keyboard.press}.
* <p>
*
* <p>
* <strong>NOTE</strong> Modifier keys DO NOT effect {@code keyboard.type}. Holding down {@code Shift} will not type the text in upper case.
* @param text A text to type into a focused element.
*/
void type(String text, int delay);
/**
* Dispatches a {@code keyup} event.
* @param key Name of the key to press or a character to generate, such as {@code ArrowLeft} or {@code a}.
*/
void up(String key);
}

15
playwright/src/main/java/com/microsoft/playwright/Logger.java
View File

@ -18,6 +18,10 @@ package com.microsoft.playwright;
import java.util.*;
/**
* Playwright generates a lot of logs and they are accessible via the pluggable logger sink.
* <p>
*/
public interface Logger {
enum Severity { ERROR, INFO, VERBOSE, WARNING }
class LogHints {
@ -28,7 +32,18 @@ public interface Logger {
return this;
}
}
/**
* Determines whether sink is interested in the logger with the given name and severity.
* @param name logger name
*/
boolean isEnabled(String name, Severity severity);
/**
*
* @param name logger name
* @param message log message format
* @param args message arguments
* @param hints optional formatting hints
*/
void log(String name, Severity severity, String message, List<Object> args, LogHints hints);
}

21
playwright/src/main/java/com/microsoft/playwright/Mouse.java
View File

@ -18,6 +18,12 @@ package com.microsoft.playwright;
import java.util.*;
/**
* The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
* <p>
* Every {@code page} object has its own Mouse, accessible with {@code page.mouse}.
* <p>
*/
public interface Mouse {
enum Button { LEFT, MIDDLE, RIGHT }
@ -89,22 +95,37 @@ public interface Mouse {
default void click(int x, int y) {
click(x, y, null);
}
/**
* Shortcut for {@code mouse.move}, {@code mouse.down} and {@code mouse.up}.
*/
void click(int x, int y, ClickOptions options);
default void dblclick(int x, int y) {
dblclick(x, y, null);
}
/**
* Shortcut for {@code mouse.move}, {@code mouse.down}, {@code mouse.up}, {@code mouse.down} and {@code mouse.up}.
*/
void dblclick(int x, int y, DblclickOptions options);
default void down() {
down(null);
}
/**
* Dispatches a {@code mousedown} event.
*/
void down(DownOptions options);
default void move(int x, int y) {
move(x, y, null);
}
/**
* Dispatches a {@code mousemove} event.
*/
void move(int x, int y, MoveOptions options);
default void up() {
up(null);
}
/**
* Dispatches a {@code mouseup} event.
*/
void up(UpOptions options);
}

683
playwright/src/main/java/com/microsoft/playwright/Page.java
View File

@ -22,6 +22,14 @@ import java.util.function.Consumer;
import java.util.function.Predicate;
import java.util.regex.Pattern;
/**
* Page provides methods to interact with a single tab in a Browser, or an extension background page in Chromium. One Browser instance might have multiple Page instances.
* <p>
* The Page class emits various events (described below) which can be handled using any of Node's native {@code EventEmitter} methods, such as {@code on}, {@code once} or {@code removeListener}.
* <p>
* To unsubscribe from events use the {@code removeListener} method:
* <p>
*/
public interface Page {
class Viewport {
private final int width;
@ -807,40 +815,186 @@ public interface Page {
return this;
}
}
/**
* The method finds an element matching the specified selector within the page. If no elements match the selector, the return value resolves to {@code null}.
* <p>
* Shortcut for page.mainFrame().$(selector).
* @param selector A selector to query page for. See working with selectors for more details.
*/
ElementHandle querySelector(String selector);
/**
* The method finds all elements matching the specified selector within the page. If no elements match the selector, the return value resolves to {@code []}.
* <p>
* Shortcut for page.mainFrame().$$(selector).
* @param selector A selector to query page for. See working with selectors for more details.
*/
List<ElementHandle> querySelectorAll(String selector);
default Object evalOnSelector(String selector, String pageFunction) {
return evalOnSelector(selector, pageFunction, null);
}
/**
* The method finds an element matching the specified selector within the page and passes it as a first argument to {@code pageFunction}. If no elements match the selector, the method throws an error.
* <p>
* If {@code pageFunction} returns a Promise, then {@code page.$eval} would wait for the promise to resolve and return its value.
* <p>
* Examples:
* <p>
* Shortcut for page.mainFrame().$eval(selector, pageFunction).
* @param selector A selector to query page for. See working with selectors for more details.
* @param pageFunction Function to be evaluated in browser context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction}
*/
Object evalOnSelector(String selector, String pageFunction, Object arg);
default Object evalOnSelectorAll(String selector, String pageFunction) {
return evalOnSelectorAll(selector, pageFunction, null);
}
/**
* The method finds all elements matching the specified selector within the page and passes an array of matched elements as a first argument to {@code pageFunction}.
* <p>
* If {@code pageFunction} returns a Promise, then {@code page.$$eval} would wait for the promise to resolve and return its value.
* <p>
* Examples:
* <p>
*
* @param selector A selector to query page for. See working with selectors for more details.
* @param pageFunction Function to be evaluated in browser context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction}
*/
Object evalOnSelectorAll(String selector, String pageFunction, Object arg);
default void addInitScript(String script) {
addInitScript(script, null);
}
/**
* Adds a script which would be evaluated in one of the following scenarios:
* <p>
* Whenever the page is navigated.
* <p>
* Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame.
* <p>
* 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}.
* <p>
* <strong>NOTE</strong> The order of evaluation of multiple scripts installed via browserContext.addInitScript(script[, arg]) and page.addInitScript(script[, arg]) is not defined.
* @param script Script to be evaluated in the page.
* @param arg Optional argument to pass to {@code script} (only supported when passing a function).
*/
void addInitScript(String script, Object arg);
/**
* Adds a {@code <script>} tag into the page with the desired url or content.
* <p>
* Shortcut for page.mainFrame().addScriptTag(options).
* @return which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
*/
ElementHandle addScriptTag(AddScriptTagOptions options);
/**
* Adds a {@code <link rel="stylesheet">} tag into the page with the desired url or a {@code <style type="text/css">} tag with the content.
* <p>
* Shortcut for page.mainFrame().addStyleTag(options).
* @return which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
*/
ElementHandle addStyleTag(AddStyleTagOptions options);
/**
* Brings page to front (activates tab).
*/
void bringToFront();
default void check(String selector) {
check(selector, null);
}
/**
* This method checks an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to click in the center of the element.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* Ensure that the element is now checked. If not, this method rejects.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* <p>
* Shortcut for page.mainFrame().check(selector[, options]).
* @param selector A selector to search for checkbox or radio button to check. If there are multiple elements satisfying the selector, the first will be checked. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully checked.
*/
void check(String selector, CheckOptions options);
default void click(String selector) {
click(selector, null);
}
/**
* This method clicks an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to click in the center of the element, or the specified {@code position}.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* <p>
* Shortcut for page.mainFrame().click(selector[, options]).
* @param selector A selector to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully clicked.
*/
void click(String selector, ClickOptions options);
default void close() {
close(null);
}
/**
* If {@code runBeforeUnload} is {@code false} the result will resolve only after the page has been closed.
* <p>
* If {@code runBeforeUnload} is {@code true} the method will **not** wait for the page to close.
* <p>
* By default, {@code page.close()} **does not** run beforeunload handlers.
* <p>
* <strong>NOTE</strong> if {@code runBeforeUnload} is passed as true, a {@code beforeunload} dialog might be summoned
* <p>
* and should be handled manually via page's 'dialog' event.
*/
void close(CloseOptions options);
/**
* Gets the full HTML contents of the page, including the doctype.
*/
String content();
/**
* Get the browser context that the page belongs to.
*/
BrowserContext context();
default void dblclick(String selector) {
dblclick(selector, null);
}
/**
* This method double clicks an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to double click in the center of the element, or the specified {@code position}.
* <p>
* 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.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* <p>
* <strong>NOTE</strong> {@code page.dblclick()} dispatches two {@code click} events and a single {@code dblclick} event.
* <p>
* Shortcut for page.mainFrame().dblclick(selector[, options]).
* @param selector A selector to search for element to double click. If there are multiple elements satisfying the selector, the first will be double clicked. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully double clicked.
*/
void dblclick(String selector, DblclickOptions options);
default void dispatchEvent(String selector, String type, Object eventInit) {
dispatchEvent(selector, type, eventInit, null);
@ -848,83 +1002,401 @@ public interface Page {
default void dispatchEvent(String selector, String type) {
dispatchEvent(selector, 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 {@code element.click()}.
* <p>
* 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.
* <p>
* Since {@code eventInit} is event-specific, please refer to the events documentation for the lists of initial properties:
* <p>
* DragEvent
* <p>
* FocusEvent
* <p>
* KeyboardEvent
* <p>
* MouseEvent
* <p>
* PointerEvent
* <p>
* TouchEvent
* <p>
* Event
* <p>
* You can also specify {@code JSHandle} as the property value if you want live objects to be passed into the event:
* <p>
*
* @param selector A selector to search for element to use. If there are multiple elements satisfying the selector, the first will be used. See working with selectors for more details.
* @param type DOM event type: {@code "click"}, {@code "dragstart"}, etc.
* @param eventInit event-specific initialization properties.
*/
void dispatchEvent(String selector, String type, Object eventInit, DispatchEventOptions options);
/**
*
* <p>
*/
void emulateMedia(EmulateMediaOptions options);
default Object evaluate(String pageFunction) {
return evaluate(pageFunction, null);
}
/**
* If the function passed to the {@code page.evaluate} returns a Promise, then {@code page.evaluate} would wait for the promise to resolve and return its value.
* <p>
* If the function passed to the {@code page.evaluate} returns a non-Serializable value, then {@code page.evaluate} resolves to {@code undefined}. DevTools Protocol also supports transferring some additional values that are not serializable by {@code JSON}: {@code -0}, {@code NaN}, {@code Infinity}, {@code -Infinity}, and bigint literals.
* <p>
* Passing argument to {@code pageFunction}:
* <p>
* A string can also be passed in instead of a function:
* <p>
* ElementHandle instances can be passed as an argument to the {@code page.evaluate}:
* <p>
* Shortcut for page.mainFrame().evaluate(pageFunction[, arg]).
* @param pageFunction Function to be evaluated in the page context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction}
*/
Object evaluate(String pageFunction, Object arg);
default JSHandle evaluateHandle(String pageFunction) {
return evaluateHandle(pageFunction, null);
}
/**
* The only difference between {@code page.evaluate} and {@code page.evaluateHandle} is that {@code page.evaluateHandle} returns in-page object (JSHandle).
* <p>
* If the function passed to the {@code page.evaluateHandle} returns a Promise, then {@code page.evaluateHandle} would wait for the promise to resolve and return its value.
* <p>
* A string can also be passed in instead of a function:
* <p>
* JSHandle instances can be passed as an argument to the {@code page.evaluateHandle}:
* <p>
*
* @param pageFunction Function to be evaluated in the page context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction} as in-page object (JSHandle)
*/
JSHandle evaluateHandle(String pageFunction, Object arg);
default void exposeBinding(String name, Binding playwrightBinding) {
exposeBinding(name, playwrightBinding, null);
}
/**
* The method adds a function called {@code name} on the {@code window} object of every frame in this page.
* <p>
* When called, the function executes {@code playwrightBinding} in Node.js and returns a Promise which resolves to the return value of {@code playwrightBinding}.
* <p>
* If the {@code playwrightBinding} returns a Promise, it will be awaited.
* <p>
* The first argument of the {@code playwrightBinding} function contains information about the caller:
* <p>
* {@code { browserContext: BrowserContext, page: Page, frame: Frame }}.
* <p>
* See browserContext.exposeBinding(name, playwrightBinding) for the context-wide version.
* <p>
* <strong>NOTE</strong> Functions installed via {@code page.exposeBinding} survive navigations.
* <p>
*
* @param name Name of the function on the window object.
* @param playwrightBinding Callback function that will be called in the Playwright's context.
*/
void exposeBinding(String name, Binding playwrightBinding, ExposeBindingOptions options);
/**
* The method adds a function called {@code name} on the {@code window} object of every frame in the page.
* <p>
* When called, the function executes {@code playwrightFunction} in Node.js and returns a Promise which resolves to the return value of {@code playwrightFunction}.
* <p>
* If the {@code playwrightFunction} returns a Promise, it will be awaited.
* <p>
* See browserContext.exposeFunction(name, playwrightFunction) for context-wide exposed function.
* <p>
* <strong>NOTE</strong> Functions installed via {@code page.exposeFunction} survive navigations.
* <p>
*
* @param name Name of the function on the window object
* @param playwrightFunction Callback function which will be called in Playwright's context.
*/
void exposeFunction(String name, Function playwrightFunction);
default void fill(String selector, String value) {
fill(selector, value, null);
}
/**
* This method waits for an element matching {@code selector}, waits for actionability checks, focuses the element, fills it and triggers an {@code input} event after filling.
* <p>
* If the element matching {@code selector} is not an {@code <input>}, {@code <textarea>} or {@code [contenteditable]} element, this method throws an error.
* <p>
* Note that you can pass an empty string to clear the input field.
* <p>
* To send fine-grained keyboard events, use {@code page.type}.
* <p>
* Shortcut for page.mainFrame().fill()
* @param selector A selector to query page for. See working with selectors for more details.
* @param value Value to fill for the {@code <input>}, {@code <textarea>} or {@code [contenteditable]} element.
*/
void fill(String selector, String value, FillOptions options);
default void focus(String selector) {
focus(selector, null);
}
/**
* This method fetches an element with {@code selector} and focuses it.
* <p>
* If there's no element matching {@code selector}, the method waits until a matching element appears in the DOM.
* <p>
* Shortcut for page.mainFrame().focus(selector).
* @param selector A selector of an element to focus. If there are multiple elements satisfying the selector, the first will be focused. See working with selectors for more details.
* @return Promise which resolves when the element matching {@code selector} is successfully focused. The promise will be rejected if there is no element matching {@code selector}.
*/
void focus(String selector, FocusOptions options);
Frame frameByName(String name);
Frame frameByUrl(String glob);
Frame frameByUrl(Pattern pattern);
/**
*
* <p>
* Returns frame matching the specified criteria. Either {@code name} or {@code url} must be specified.
* @param options Frame name or other frame lookup options.
* @return frame matching the criteria. Returns {@code null} if no frame matches.
*/
Frame frameByUrl(Predicate<String> predicate);
/**
*
* @return An array of all frames attached to the page.
*/
List<Frame> frames();
default String getAttribute(String selector, String name) {
return getAttribute(selector, name, null);
}
/**
* Returns element attribute value.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be picked. See working with selectors for more details.
* @param name Attribute name to get the value for.
*/
String getAttribute(String selector, String name, GetAttributeOptions options);
default Response goBack() {
return goBack(null);
}
/**
* Navigate to the previous page in history.
* @param options Navigation parameters which might have the following properties:
* @return Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If
* can not go back, resolves to {@code null}.
*/
Response goBack(GoBackOptions options);
default Response goForward() {
return goForward(null);
}
/**
* Navigate to the next page in history.
* @param options Navigation parameters which might have the following properties:
* @return Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If
* can not go forward, resolves to {@code null}.
*/
Response goForward(GoForwardOptions options);
default Response navigate(String url) {
return navigate(url, null);
}
/**
* {@code page.goto} will throw an error if:
* <p>
* there's an SSL error (e.g. in case of self-signed certificates).
* <p>
* target URL is invalid.
* <p>
* the {@code timeout} is exceeded during navigation.
* <p>
* the remote server does not respond or is unreachable.
* <p>
* the main resource failed to load.
* <p>
* {@code page.goto} will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling response.status().
* <p>
* <strong>NOTE</strong> {@code page.goto} either throws an error or returns a main resource response. The only exceptions are navigation to {@code about:blank} or navigation to the same URL with a different hash, which would succeed and return {@code null}.
* <p>
*
* <p>
* <strong>NOTE</strong> Headless mode doesn't support navigation to a PDF document. See the upstream issue.
* <p>
* Shortcut for page.mainFrame().goto(url[, options])
* @param url URL to navigate page to. The url should include scheme, e.g. {@code https://}.
* @param options Navigation parameters which might have the following properties:
* @return Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
*/
Response navigate(String url, NavigateOptions options);
default void hover(String selector) {
hover(selector, null);
}
/**
* This method hovers over an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to hover over the center of the element, or the specified {@code position}.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* <p>
* Shortcut for page.mainFrame().hover(selector[, options]).
* @param selector A selector to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully hovered.
*/
void hover(String selector, HoverOptions options);
default String innerHTML(String selector) {
return innerHTML(selector, null);
}
/**
* Resolves to the {@code element.innerHTML}.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be picked. See working with selectors for more details.
*/
String innerHTML(String selector, InnerHTMLOptions options);
default String innerText(String selector) {
return innerText(selector, null);
}
/**
* Resolves to the {@code element.innerText}.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be picked. See working with selectors for more details.
*/
String innerText(String selector, InnerTextOptions options);
/**
* Indicates that the page has been closed.
*/
boolean isClosed();
/**
* Page is guaranteed to have a main frame which persists during navigations.
* @return The page's main frame.
*/
Frame mainFrame();
/**
*
* @return Promise which resolves to the opener for popup pages and {@code null} for others. If the opener has been closed already the promise may resolve to {@code null}.
*/
Page opener();
default byte[] pdf() {
return pdf(null);
}
/**
* <strong>NOTE</strong> Generating a pdf is currently only supported in Chromium headless.
* <p>
* {@code page.pdf()} generates a pdf of the page with {@code print} css media. To generate a pdf with {@code screen} media, call page.emulateMedia({ media: 'screen' }) before calling {@code page.pdf()}:
* <p>
* <strong>NOTE</strong> By default, {@code page.pdf()} generates a pdf with modified colors for printing. Use the {@code -webkit-print-color-adjust} property to force rendering of exact colors.
* <p>
*
* <p>
* The {@code width}, {@code height}, and {@code margin} options accept values labeled with units. Unlabeled values are treated as pixels.
* <p>
* A few examples:
* <p>
* {@code page.pdf({width: 100})} - prints with width set to 100 pixels
* <p>
* {@code page.pdf({width: '100px'})} - prints with width set to 100 pixels
* <p>
* {@code page.pdf({width: '10cm'})} - prints with width set to 10 centimeters.
* <p>
* All possible units are:
* <p>
* {@code px} - pixel
* <p>
* {@code in} - inch
* <p>
* {@code cm} - centimeter
* <p>
* {@code mm} - millimeter
* <p>
* The {@code format} options are:
* <p>
* {@code Letter}: 8.5in x 11in
* <p>
* {@code Legal}: 8.5in x 14in
* <p>
* {@code Tabloid}: 11in x 17in
* <p>
* {@code Ledger}: 17in x 11in
* <p>
* {@code A0}: 33.1in x 46.8in
* <p>
* {@code A1}: 23.4in x 33.1in
* <p>
* {@code A2}: 16.54in x 23.4in
* <p>
* {@code A3}: 11.7in x 16.54in
* <p>
* {@code A4}: 8.27in x 11.7in
* <p>
* {@code A5}: 5.83in x 8.27in
* <p>
* {@code A6}: 4.13in x 5.83in
* <p>
*
* <p>
* <strong>NOTE</strong> {@code headerTemplate} and {@code footerTemplate} markup have the following limitations:
* <p>
* Script tags inside templates are not evaluated.
* <p>
* Page styles are not visible inside templates.
* @param options Options object which might have the following properties:
* @return Promise which resolves with PDF buffer.
*/
byte[] pdf(PdfOptions options);
default void press(String selector, String key) {
press(selector, key, null);
}
/**
* Focuses the element, and then uses {@code keyboard.down} and {@code keyboard.up}.
* <p>
* {@code key} can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the {@code key} values can be found here. Examples of the keys are:
* <p>
* {@code F1} - {@code F12}, {@code Digit0}- {@code Digit9}, {@code KeyA}- {@code KeyZ}, {@code Backquote}, {@code Minus}, {@code Equal}, {@code Backslash}, {@code Backspace}, {@code Tab}, {@code Delete}, {@code Escape}, {@code ArrowDown}, {@code End}, {@code Enter}, {@code Home}, {@code Insert}, {@code PageDown}, {@code PageUp}, {@code ArrowRight}, {@code ArrowUp}, etc.
* <p>
* Following modification shortcuts are also suported: {@code Shift}, {@code Control}, {@code Alt}, {@code Meta}, {@code ShiftLeft}.
* <p>
* Holding down {@code Shift} will type the text that corresponds to the {@code key} in the upper case.
* <p>
* If {@code key} is a single character, it is case-sensitive, so the values {@code a} and {@code A} will generate different respective texts.
* <p>
* Shortcuts such as {@code key: "Control+o"} or {@code key: "Control+Shift+T"} are supported as well. When speficied with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
* <p>
*
* @param selector A selector of an element to type into. If there are multiple elements satisfying the selector, the first will be used. See working with selectors for more details.
* @param key Name of the key to press or a character to generate, such as {@code ArrowLeft} or {@code a}.
*/
void press(String selector, String key, PressOptions options);
default Response reload() {
return reload(null);
}
/**
*
* @param options Navigation parameters which might have the following properties:
* @return Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
*/
Response reload(ReloadOptions options);
void route(String url, Consumer<Route> handler);
void route(Pattern url, Consumer<Route> handler);
/**
* Routing provides the capability to modify network requests that are made by a page.
* <p>
* Once routing is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
* <p>
* <strong>NOTE</strong> The handler will only be called for the first url if the response is a redirect.
* <p>
* or the same snippet using a regex pattern instead:
* <p>
* Page routes take precedence over browser context routes (set up with browserContext.route(url, handler)) when request matches both handlers.
* <p>
* <strong>NOTE</strong> 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.
* @return .
*/
void route(Predicate<String> url, Consumer<Route> handler);
default byte[] screenshot() {
return screenshot(null);
}
/**
* <strong>NOTE</strong> Screenshots take at least 1/6 second on Chromium OS X and Chromium Windows. See https://crbug.com/741689 for discussion.
* @param options Options object which might have the following properties:
* @return Promise which resolves to buffer with the captured screenshot.
*/
byte[] screenshot(ScreenshotOptions options);
default List<String> selectOption(String selector, String value) {
return selectOption(selector, value, null);
@ -964,13 +1436,60 @@ public interface Page {
default List<String> selectOption(String selector, ElementHandle[] values) {
return selectOption(selector, values, null);
}
/**
* Triggers a {@code change} and {@code input} event once all the provided options have been selected.
* <p>
* If there's no {@code <select>} element matching {@code selector}, the method throws an error.
* <p>
* Shortcut for page.mainFrame().selectOption()
* @param selector A selector to query page for. See working with selectors for more details.
* @param values Options to select. If the {@code <select>} has the {@code multiple} attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to {@code {value:'string'}}. Option is considered matching if all specified properties match.
* @return An array of option values that have been successfully selected.
*/
List<String> selectOption(String selector, ElementHandle[] values, SelectOptionOptions options);
default void setContent(String html) {
setContent(html, null);
}
/**
*
* @param html HTML markup to assign to the page.
* @param options Parameters which might have the following properties:
*/
void setContent(String html, SetContentOptions options);
/**
* This setting will change the default maximum navigation time for the following methods and related shortcuts:
* <p>
* page.goBack([options])
* <p>
* page.goForward([options])
* <p>
* page.goto(url[, options])
* <p>
* page.reload([options])
* <p>
* page.setContent(html[, options])
* <p>
* page.waitForNavigation([options])
* <p>
*
* <p>
* <strong>NOTE</strong> {@code page.setDefaultNavigationTimeout} takes priority over {@code page.setDefaultTimeout}, {@code browserContext.setDefaultTimeout} and {@code 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.
* <p>
* <strong>NOTE</strong> {@code page.setDefaultNavigationTimeout} takes priority over {@code page.setDefaultTimeout}.
* @param timeout Maximum time in milliseconds
*/
void setDefaultTimeout(int timeout);
/**
* The extra HTTP headers will be sent with every request the page initiates.
* <p>
* <strong>NOTE</strong> page.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<String, String> headers);
default void setInputFiles(String selector, Path file) { setInputFiles(selector, file, null); }
default void setInputFiles(String selector, Path file, SetInputFilesOptions options) { setInputFiles(selector, new Path[]{ file }, options); }
@ -979,32 +1498,116 @@ public interface Page {
default void setInputFiles(String selector, FileChooser.FilePayload file) { setInputFiles(selector, file, null); }
default void setInputFiles(String selector, FileChooser.FilePayload file, SetInputFilesOptions options) { setInputFiles(selector, new FileChooser.FilePayload[]{ file }, options); }
default void setInputFiles(String selector, FileChooser.FilePayload[] files) { setInputFiles(selector, files, null); }
/**
* This method expects {@code selector} to point to an input element.
* <p>
* Sets the value of the file input to these file paths or files. If some of the {@code filePaths} are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.
* @param selector A selector to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked. See working with selectors for more details.
*/
void setInputFiles(String selector, FileChooser.FilePayload[] files, SetInputFilesOptions options);
/**
* In the case of multiple pages in a single browser, each page can have its own viewport size. However, browser.newContext([options]) allows to set viewport size (and more) for all pages in the context at once.
* <p>
* {@code page.setViewportSize} will resize the page. A lot of websites don't expect phones to change size, so you should set the viewport size before navigating to the page.
* <p>
*/
void setViewportSize(int width, int height);
default void tap(String selector) {
tap(selector, null);
}
/**
* This method taps an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.touchscreen to tap the center of the element, or the specified {@code position}.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* <p>
* <strong>NOTE</strong> {@code page.tap()} requires that the {@code hasTouch} option of the browser context be set to true.
* <p>
* Shortcut for page.mainFrame().tap().
* @param selector A selector to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully tapped.
*/
void tap(String selector, TapOptions options);
default String textContent(String selector) {
return textContent(selector, null);
}
/**
* Resolves to the {@code element.textContent}.
* @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be picked. See working with selectors for more details.
*/
String textContent(String selector, TextContentOptions options);
/**
* Shortcut for page.mainFrame().title().
* @return The page's title.
*/
String title();
default void type(String selector, String text) {
type(selector, text, null);
}
/**
* Sends a {@code keydown}, {@code keypress}/{@code input}, and {@code keyup} event for each character in the text. {@code page.type} can be used to send fine-grained keyboard events. To fill values in form fields, use {@code page.fill}.
* <p>
* To press a special key, like {@code Control} or {@code ArrowDown}, use {@code keyboard.press}.
* <p>
* Shortcut for page.mainFrame().type(selector, text[, options]).
* @param selector A selector of an element to type into. If there are multiple elements satisfying the selector, the first will be used. See working with selectors for more details.
* @param text A text to type into a focused element.
*/
void type(String selector, String text, TypeOptions options);
default void uncheck(String selector) {
uncheck(selector, null);
}
/**
* This method unchecks an element matching {@code selector} by performing the following steps:
* <p>
* Find an element match matching {@code selector}. If there is none, wait until a matching element is attached to the DOM.
* <p>
* Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately.
* <p>
* Wait for actionability checks on the matched element, unless {@code force} option is set. If the element is detached during the checks, the whole action is retried.
* <p>
* Scroll the element into view if needed.
* <p>
* Use page.mouse to click in the center of the element.
* <p>
* Wait for initiated navigations to either succeed or fail, unless {@code noWaitAfter} option is set.
* <p>
* Ensure that the element is now unchecked. If not, this method rejects.
* <p>
* When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this.
* <p>
* Shortcut for page.mainFrame().uncheck(selector[, options]).
* @param selector A selector to search for uncheckbox to check. If there are multiple elements satisfying the selector, the first will be checked. See working with selectors for more details.
* @return Promise that resolves when the element matching {@code selector} is successfully unchecked.
*/
void uncheck(String selector, UncheckOptions options);
default void unroute(String url) { unroute(url, null); }
default void unroute(Pattern url) { unroute(url, null); }
default void unroute(Predicate<String> url) { unroute(url, null); }
void unroute(String url, Consumer<Route> handler);
void unroute(Pattern url, Consumer<Route> handler);
/**
* Removes a route created with page.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 to match while routing.
* @param handler Handler function to route the request.
*/
void unroute(Predicate<String> url, Consumer<Route> handler);
/**
* This is a shortcut for page.mainFrame().url()
*/
String url();
/**
* Video object associated with this page.
*/
Video video();
Viewport viewportSize();
default Deferred<Event<EventType>> waitForEvent(EventType event) {
@ -1015,6 +1618,14 @@ public interface Page {
options.predicate = predicate;
return waitForEvent(event, options);
}
/**
* Waits for event to fire and passes its value into the predicate function. Resolves when the predicate returns truthy value. Will throw an error if the page is closed before the event
* <p>
* is fired.
* @param event Event name, same one would pass into {@code page.on(event)}.
* @param optionsOrPredicate Either a predicate that receives an event or an options object.
* @return Promise which resolves to the event data value.
*/
Deferred<Event<EventType>> waitForEvent(EventType event, WaitForEventOptions options);
default Deferred<JSHandle> waitForFunction(String pageFunction, Object arg) {
return waitForFunction(pageFunction, arg, null);
@ -1022,6 +1633,17 @@ public interface Page {
default Deferred<JSHandle> waitForFunction(String pageFunction) {
return waitForFunction(pageFunction, null);
}
/**
* The {@code waitForFunction} can be used to observe viewport size change:
* <p>
* To pass an argument from Node.js to the predicate of {@code page.waitForFunction} function:
* <p>
* Shortcut for page.mainFrame().waitForFunction(pageFunction[, arg, options]).
* @param pageFunction Function to be evaluated in browser context
* @param arg Optional argument to pass to {@code pageFunction}
* @param options Optional waiting parameters
* @return Promise which resolves when the {@code pageFunction} returns a truthy value. It resolves to a JSHandle of the truthy value.
*/
Deferred<JSHandle> waitForFunction(String pageFunction, Object arg, WaitForFunctionOptions options);
default Deferred<Void> waitForLoadState(LoadState state) {
return waitForLoadState(state, null);
@ -1029,26 +1651,87 @@ public interface Page {
default Deferred<Void> waitForLoadState() {
return waitForLoadState(null);
}
/**
* This resolves when the page reaches a required load state, {@code load} by default. The navigation must have been committed when this method is called. If current document has already reached the required state, resolves immediately.
* <p>
*
* <p>
* Shortcut for page.mainFrame().waitForLoadState([options]).
* @param state Load state to wait for, defaults to {@code load}. If the state has been already reached while loading current document, the method resolves immediately.
* - {@code 'load'} - wait for the {@code load} event to be fired.
* - {@code 'domcontentloaded'} - wait for the {@code DOMContentLoaded} event to be fired.
* - {@code 'networkidle'} - wait until there are no network connections for at least {@code 500} ms.
* @return Promise which resolves when the required load state has been reached.
*/
Deferred<Void> waitForLoadState(LoadState state, WaitForLoadStateOptions options);
default Deferred<Response> waitForNavigation() {
return waitForNavigation(null);
}
/**
* This resolves when the page navigates to a new URL or reloads. It is useful for when you run code
* <p>
* which will indirectly cause the page to navigate. e.g. The click target has an {@code onclick} handler that triggers navigation from a {@code setTimeout}. Consider this example:
* <p>
* <strong>NOTE</strong> Usage of the History API to change the URL is considered a navigation.
* <p>
* Shortcut for page.mainFrame().waitForNavigation(options).
* @param options Navigation parameters which might have the following properties:
* @return Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with {@code null}.
*/
Deferred<Response> waitForNavigation(WaitForNavigationOptions options);
default Deferred<Request> waitForRequest(String urlOrPredicate) {
return waitForRequest(urlOrPredicate, null);
}
/**
*
* <p>
*
* @param urlOrPredicate Request URL string, regex or predicate receiving Request object.
* @param options Optional waiting parameters
* @return Promise which resolves to the matched request.
*/
Deferred<Request> waitForRequest(String urlOrPredicate, WaitForRequestOptions options);
default Deferred<Response> waitForResponse(String urlOrPredicate) {
return waitForResponse(urlOrPredicate, null);
}
/**
*
* @param urlOrPredicate Request URL string, regex or predicate receiving Response object.
* @param options Optional waiting parameters
* @return Promise which resolves to the matched response.
*/
Deferred<Response> waitForResponse(String urlOrPredicate, WaitForResponseOptions options);
default Deferred<ElementHandle> waitForSelector(String selector) {
return waitForSelector(selector, null);
}
/**
* Wait for the {@code selector} to satisfy {@code state} option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method {@code selector} already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the {@code timeout} milliseconds, the function will throw.
* <p>
* This method works across navigations:
* <p>
* Shortcut for page.mainFrame().waitForSelector(selector[, options]).
* @param selector A selector of an element to wait for. See working with selectors for more details.
* @return Promise which resolves when element specified by selector satisfies {@code state} option. Resolves to {@code null} if waiting for {@code hidden} or {@code detached}.
*/
Deferred<ElementHandle> waitForSelector(String selector, WaitForSelectorOptions options);
/**
* Returns a promise that resolves after the timeout.
* <p>
* Note that {@code page.waitForTimeout()} should only be used for debugging. Tests using the timer in production are going to be flaky. Use signals such as network events, selectors becoming visible and others instead.
* <p>
* Shortcut for page.mainFrame().waitForTimeout(timeout).
* @param timeout A timeout to wait for
*/
Deferred<Void> waitForTimeout(int timeout);
/**
* <strong>NOTE</strong> This does not contain ServiceWorkers
* @return This method returns all of the dedicated WebWorkers associated with the page.
*/
List<Worker> workers();
Accessibility accessibility();
/**
* Browser-specific Coverage implementation, only available for Chromium atm. See ChromiumCoverage for more details.
*/
ChromiumCoverage coverage();
Keyboard keyboard();
Mouse mouse();

81
playwright/src/main/java/com/microsoft/playwright/Request.java
View File

@ -18,6 +18,21 @@ package com.microsoft.playwright;
import java.util.*;
/**
* Whenever the page sends a request for a network resource the following sequence of events are emitted by Page:
* <p>
* {@code 'request'} emitted when the request is issued by the page.
* <p>
* {@code 'response'} emitted when/if the response status and headers are received for the request.
* <p>
* {@code 'requestfinished'} emitted when the response body is downloaded and the request is complete.
* <p>
* If request fails at some point, then instead of {@code 'requestfinished'} event (and possibly instead of 'response' event), the {@code 'requestfailed'} event is emitted.
* <p>
* <strong>NOTE</strong> HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with {@code 'requestfinished'} event.
* <p>
* If request gets a 'redirect' response, the request is successfully finished with the 'requestfinished' event, and a new request is issued to a redirected url.
*/
public interface Request {
class RequestFailure {
private String errorText;
@ -71,18 +86,84 @@ public interface Request {
return this.responseEnd;
}
}
/**
* The method returns {@code null} unless this request has failed, as reported by
* <p>
* {@code requestfailed} event.
* <p>
* Example of logging of all the failed requests:
* <p>
*
* @return Object describing request failure, if any
*/
RequestFailure failure();
/**
*
* @return A Frame that initiated this request.
*/
Frame frame();
/**
*
* @return An object with HTTP headers associated with the request. All header names are lower-case.
*/
Map<String, String> headers();
/**
* Whether this request is driving frame's navigation.
*/
boolean isNavigationRequest();
/**
*
* @return Request's method (GET, POST, etc.)
*/
String method();
/**
*
* @return Request's post body, if any.
*/
String postData();
/**
*
* @return Request's post body in a binary form, if any.
*/
byte[] postDataBuffer();
/**
* When the server responds with a redirect, Playwright creates a new Request object. The two requests are connected by {@code redirectedFrom()} and {@code redirectedTo()} methods. When multiple server redirects has happened, it is possible to construct the whole redirect chain by repeatedly calling {@code redirectedFrom()}.
* <p>
* For example, if the website {@code http://example.com} redirects to {@code https://example.com}:
* <p>
* If the website {@code https://google.com} has no redirects:
* <p>
*
* @return Request that was redirected by the server to this one, if any.
*/
Request redirectedFrom();
/**
* This method is the opposite of request.redirectedFrom():
* <p>
*
* @return New request issued by the browser if the server responded with redirect.
*/
Request redirectedTo();
/**
* Contains the request's resource type as it was perceived by the rendering engine.
* <p>
* ResourceType will be one of the following: {@code document}, {@code stylesheet}, {@code image}, {@code media}, {@code font}, {@code script}, {@code texttrack}, {@code xhr}, {@code fetch}, {@code eventsource}, {@code websocket}, {@code manifest}, {@code other}.
*/
String resourceType();
/**
*
* @return A matching Response object, or {@code null} if the response was not received due to error.
*/
Response response();
/**
* Returns resource timing information for given request. Most of the timing values become available upon the response, {@code responseEnd} becomes available when request finishes. Find more information at Resource Timing API.
* <p>
*/
RequestTiming timing();
/**
*
* @return URL of the request.
*/
String url();
}

39
playwright/src/main/java/com/microsoft/playwright/Response.java
View File

@ -18,16 +18,55 @@ package com.microsoft.playwright;
import java.util.*;
/**
* Response class represents responses which are received by page.
*/
public interface Response {
/**
*
* @return Promise which resolves to a buffer with response body.
*/
byte[] body();
/**
*
* @return Waits for this response to finish, returns failure error if request failed.
*/
String finished();
/**
*
* @return A Frame that initiated this response.
*/
Frame frame();
/**
*
* @return An object with HTTP headers associated with the response. All header names are lower-case.
*/
Map<String, String> headers();
/**
* Contains a boolean stating whether the response was successful (status in the range 200-299) or not.
*/
boolean ok();
/**
*
* @return A matching Request object.
*/
Request request();
/**
* Contains the status code of the response (e.g., 200 for a success).
*/
int status();
/**
* Contains the status text of the response (e.g. usually an "OK" for a success).
*/
String statusText();
/**
*
* @return Promise which resolves to a text representation of response body.
*/
String text();
/**
* Contains the URL of the response.
*/
String url();
}

37
playwright/src/main/java/com/microsoft/playwright/Route.java
View File

@ -20,6 +20,9 @@ import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.util.*;
/**
* Whenever a network route is set up with page.route(url, handler) or browserContext.route(url, handler), the {@code Route} object allows to handle the route.
*/
public interface Route {
class ContinueOverrides {
public String method;
@ -79,12 +82,46 @@ public interface Route {
default void abort() {
abort(null);
}
/**
* Aborts the route's request.
* @param errorCode Optional error code. Defaults to {@code failed}, could be
* one of the following:
* - {@code 'aborted'} - An operation was aborted (due to user action)
* - {@code 'accessdenied'} - Permission to access a resource, other than the network, was denied
* - {@code 'addressunreachable'} - The IP address is unreachable. This usually means
* - that there is no route to the specified host or network.
* - {@code 'blockedbyclient'} - The client chose to block the request.
* - {@code 'blockedbyresponse'} - The request failed because the response was delivered along with requirements which are not met ('X-Frame-Options' and 'Content-Security-Policy' ancestor checks, for instance).
* - {@code 'connectionaborted'} - A connection timed out as a result of not receiving an ACK for data sent.
* - {@code 'connectionclosed'} - A connection was closed (corresponding to a TCP FIN).
* - {@code 'connectionfailed'} - A connection attempt failed.
* - {@code 'connectionrefused'} - A connection attempt was refused.
* - {@code 'connectionreset'} - A connection was reset (corresponding to a TCP RST).
* - {@code 'internetdisconnected'} - The Internet connection has been lost.
* - {@code 'namenotresolved'} - The host name could not be resolved.
* - {@code 'timedout'} - An operation timed out.
* - {@code 'failed'} - A generic failure occurred.
*/
void abort(String errorCode);
default void continue_() {
continue_(null);
}
/**
* Continues route's request with optional overrides.
* <p>
*
* @param overrides Optional request overrides, can override following properties:
*/
void continue_(ContinueOverrides overrides);
/**
* Fulfills route's request with given response.
* @param response Response that will fulfill this route's request.
*/
void fulfill(FulfillResponse response);
/**
*
* @return A request to be routed.
*/
Request request();
}

10
playwright/src/main/java/com/microsoft/playwright/Selectors.java
View File

@ -19,6 +19,9 @@ package com.microsoft.playwright;
import java.nio.file.Path;
import java.util.*;
/**
* Selectors can be used to install custom selector engines. See Working with selectors for more information.
*/
public interface Selectors {
class RegisterOptions {
public Boolean contentScript;
@ -31,6 +34,13 @@ public interface Selectors {
default void register(String name, String script) { register(name, script, null); }
void register(String name, String script, RegisterOptions options);
default void register(String name, Path path) { register(name, path, null); }
/**
* An example of registering selector engine that queries elements based on a tag name:
* <p>
*
* @param name Name that is used in selectors as a prefix, e.g. {@code {name: 'foo'}} enables {@code foo=myselectorbody} selectors. May only contain {@code [a-zA-Z0-9_]} characters.
* @param script Script that evaluates to a selector engine instance.
*/
void register(String name, Path path, RegisterOptions options);
}

3
playwright/src/main/java/com/microsoft/playwright/TimeoutError.java
View File

@ -18,6 +18,9 @@ package com.microsoft.playwright;
import java.util.*;
/**
* TimeoutError is emitted whenever certain operations are terminated due to timeout, e.g. page.waitForSelector(selector[, options]) or browserType.launch([options]).
*/
public interface TimeoutError {
}

8
playwright/src/main/java/com/microsoft/playwright/Touchscreen.java
View File

@ -18,7 +18,15 @@ package com.microsoft.playwright;
import java.util.*;
/**
* The Touchscreen class operates in main-frame CSS pixels relative to the top-left corner of the viewport. Methods on the
* <p>
* touchscreen can only be used in browser contexts that have been intialized with {@code hasTouch} set to true.
*/
public interface Touchscreen {
/**
* Dispatches a {@code touchstart} and {@code touchend} event with a single touch at the position ({@code x},{@code y}).
*/
void tap(int x, int y);
}

7
playwright/src/main/java/com/microsoft/playwright/Video.java
View File

@ -18,7 +18,14 @@ package com.microsoft.playwright;
import java.util.*;
/**
* When browser context is created with the {@code videosPath} option, each page has a video object associated with it.
* <p>
*/
public interface Video {
/**
* Returns the file system path this video will be recorded to. The video is guaranteed to be written to the filesystem upon closing the browser context.
*/
String path();
}

3
playwright/src/main/java/com/microsoft/playwright/WebKitBrowser.java
View File

@ -18,6 +18,9 @@ package com.microsoft.playwright;
import java.util.*;
/**
* WebKit browser instance does not expose WebKit-specific features.
*/
public interface WebKitBrowser extends Browser {
}

17
playwright/src/main/java/com/microsoft/playwright/WebSocket.java
View File

@ -18,6 +18,9 @@ package com.microsoft.playwright;
import java.util.*;
/**
* The WebSocket class represents websocket connections in the page.
*/
public interface WebSocket {
enum EventType {
CLOSE,
@ -44,11 +47,25 @@ public interface WebSocket {
return this;
}
}
/**
* Indicates that the web socket has been closed.
*/
boolean isClosed();
/**
* Contains the URL of the WebSocket.
*/
String url();
default Object waitForEvent(String event) {
return waitForEvent(event, null);
}
/**
* Waits for event to fire and passes its value into the predicate function. Resolves when the predicate returns truthy value. Will throw an error if the webSocket is closed before the event
* <p>
* is fired.
* @param event Event name, same one would pass into {@code webSocket.on(event)}.
* @param optionsOrPredicate Either a predicate that receives an event or an options object.
* @return Promise which resolves to the event data value.
*/
Object waitForEvent(String event, String optionsOrPredicate);
}

24
playwright/src/main/java/com/microsoft/playwright/Worker.java
View File

@ -18,6 +18,14 @@ package com.microsoft.playwright;
import java.util.*;
/**
* The Worker class represents a WebWorker.
* <p>
* {@code worker} event is emitted on the page object to signal a worker creation.
* <p>
* {@code close} event is emitted on the worker object when the worker is gone.
* <p>
*/
public interface Worker {
enum EventType {
CLOSE,
@ -28,10 +36,26 @@ public interface Worker {
default Object evaluate(String pageFunction) {
return evaluate(pageFunction, null);
}
/**
* If the function passed to the {@code worker.evaluate} returns a Promise, then {@code worker.evaluate} would wait for the promise to resolve and return its value.
* <p>
* If the function passed to the {@code worker.evaluate} returns a non-Serializable value, then {@code worker.evaluate} resolves to {@code undefined}. DevTools Protocol also supports transferring some additional values that are not serializable by {@code JSON}: {@code -0}, {@code NaN}, {@code Infinity}, {@code -Infinity}, and bigint literals.
* @param pageFunction Function to be evaluated in the worker context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction}
*/
Object evaluate(String pageFunction, Object arg);
default JSHandle evaluateHandle(String pageFunction) {
return evaluateHandle(pageFunction, null);
}
/**
* The only difference between {@code worker.evaluate} and {@code worker.evaluateHandle} is that {@code worker.evaluateHandle} returns in-page object (JSHandle).
* <p>
* If the function passed to the {@code worker.evaluateHandle} returns a Promise, then {@code worker.evaluateHandle} would wait for the promise to resolve and return its value.
* @param pageFunction Function to be evaluated in the page context
* @param arg Optional argument to pass to {@code pageFunction}
* @return Promise which resolves to the return value of {@code pageFunction} as in-page object (JSHandle)
*/
JSHandle evaluateHandle(String pageFunction, Object arg);
String url();
Deferred<Event<EventType>> waitForEvent(EventType event);

10
pom.xml
View File

@ -62,6 +62,16 @@
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<source>8</source>
<detectJavaApiLink>false</detectJavaApiLink>
<excludes>com.microsoft.playwright.impl</excludes>
<additionalOptions>--allow-script-in-comments</additionalOptions>
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>