diff --git a/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java b/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java index 2dfe03fd..a6bee2f8 100644 --- a/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java +++ b/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java @@ -60,6 +60,41 @@ abstract class Element { static String toTitle(String name) { return Character.toUpperCase(name.charAt(0)) + name.substring(1); } + + void writeJavadoc(List 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**", "NOTE") + .replaceAll("`([^`]+)`", "{@code $1}")); + } + output.add(offset + " */"); + } + + String formattedComment() { + return comment() + // Remove any code snippets between ``` and ```. + .replaceAll("```((?\n"); +// .replaceAll("\\n\\n", "\n

\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 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 output, String offset) { + List 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 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); diff --git a/playwright/src/main/java/com/microsoft/playwright/Accessibility.java b/playwright/src/main/java/com/microsoft/playwright/Accessibility.java index b8e43064..01037eac 100644 --- a/playwright/src/main/java/com/microsoft/playwright/Accessibility.java +++ b/playwright/src/main/java/com/microsoft/playwright/Accessibility.java @@ -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. + *

+ * Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output. + *

+ * Blink - Chromium's rendering engine - has a concept of "accessibility tree", which is then translated into different platform-specific APIs. Accessibility namespace gives users + *

+ * access to the Blink Accessibility Tree. + *

+ * Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or by assistive technologies themselves. By default, Playwright tries to approximate this filtering, exposing only the "interesting" nodes of the tree. + */ public interface Accessibility { class SnapshotOptions { 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. + *

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

+ * most screen readers. Playwright will discard them as well for an easier to process tree, + *

+ * unless {@code interestingOnly} is set to {@code false}. + *

+ * + * @return An AXNode object with the following properties: + */ AccessibilityNode snapshot(SnapshotOptions options); } diff --git a/playwright/src/main/java/com/microsoft/playwright/Browser.java b/playwright/src/main/java/com/microsoft/playwright/Browser.java index 402ae5cd..bc4d8601 100644 --- a/playwright/src/main/java/com/microsoft/playwright/Browser.java +++ b/playwright/src/main/java/com/microsoft/playwright/Browser.java @@ -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}. + *

+ */ 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). + *

+ * In case this browser is obtained using browserType.connect, clears all created contexts belonging to this browser and disconnects from the browser server. + *

+ * 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 + *

+ * browser contexts. + *

+ */ List 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. + *

+ */ 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. + *

+ * 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(); } diff --git a/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java b/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java index c845a6c7..ed7e7eab 100644 --- a/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java +++ b/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java @@ -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. + *

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

+ * context. + *

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

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

+ */ public interface BrowserContext { 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: + *

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

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

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

+ * + *

+ * NOTE The order of evaluation of multiple scripts installed via 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. + *

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

+ * will be closed. + *

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

+ * If URLs are specified, only cookies that affect those URLs are returned. + */ List cookies(List 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. + *

+ * When called, the function executes {@code playwrightBinding} in Node.js and returns a Promise which resolves to the return value of {@code playwrightBinding}. + *

+ * If the {@code playwrightBinding} returns a Promise, it will be awaited. + *

+ * The first argument of the {@code playwrightBinding} function contains information about the caller: + *

+ * {@code { browserContext: BrowserContext, page: Page, frame: Frame }}. + *

+ * 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. + *

+ * When called, the function executes {@code playwrightFunction} in Node.js and returns a Promise which resolves to the return value of {@code playwrightFunction}. + *

+ * If the {@code playwrightFunction} returns a Promise, it will be awaited. + *

+ * 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 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 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 pages(); void route(String url, Consumer handler); void route(Pattern url, Consumer handler); + /** + * Routing provides the capability to modify network requests that are made by any page in the browser context. + *

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

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

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

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

+ * page.goBack([options]) + *

+ * page.goForward([options]) + *

+ * page.goto(url[, options]) + *

+ * page.reload([options]) + *

+ * page.setContent(html[, options]) + *

+ * page.waitForNavigation([options]) + *

+ * + *

+ * NOTE {@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. + *

+ * NOTE {@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. + *

+ * NOTE {@code browserContext.setExtraHTTPHeaders} does not guarantee the order of headers in the outgoing requests. + * @param headers An object containing additional HTTP headers to be sent with every request. All header values must be strings. + */ void setExtraHTTPHeaders(Map headers); + /** + * Sets the context's geolocation. Passing {@code null} or {@code undefined} emulates position unavailable. + *

+ * + *

+ * NOTE 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 url) { unroute(url, null); } void unroute(String url, Consumer handler); void unroute(Pattern url, Consumer 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 url, Consumer handler); default Deferred> 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 + *

+ * is fired. + *

+ * + * @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> waitForEvent(EventType event, WaitForEventOptions options); } diff --git a/playwright/src/main/java/com/microsoft/playwright/BrowserType.java b/playwright/src/main/java/com/microsoft/playwright/BrowserType.java index 7d9cabc0..219245ea 100644 --- a/playwright/src/main/java/com/microsoft/playwright/BrowserType.java +++ b/playwright/src/main/java/com/microsoft/playwright/BrowserType.java @@ -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. + *

+ * The following is a typical example of using Playwright to drive automation: + *

+ */ 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: + *

+ * + *

+ * **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. + *

+ * If Google Chrome (rather than Chromium) is preferred, a Chrome Canary or Dev Channel build is suggested. + *

+ * In browserType.launch([options]) above, any mention of Chromium also applies to Chrome. + *

+ * 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(); } diff --git a/playwright/src/main/java/com/microsoft/playwright/CDPSession.java b/playwright/src/main/java/com/microsoft/playwright/CDPSession.java index 6e4a508e..b792591a 100644 --- a/playwright/src/main/java/com/microsoft/playwright/CDPSession.java +++ b/playwright/src/main/java/com/microsoft/playwright/CDPSession.java @@ -18,11 +18,35 @@ package com.microsoft.playwright; import java.util.*; +/** + * The {@code CDPSession} instances are used to talk raw Chrome Devtools Protocol: + *

+ * protocol methods can be called with {@code session.send} method. + *

+ * protocol events can be subscribed to with {@code session.on} method. + *

+ * Useful links: + *

+ * Documentation on DevTools Protocol can be found here: DevTools Protocol Viewer. + *

+ * Getting Started with DevTools Protocol: https://github.com/aslushnikov/getting-started-with-cdp/blob/master/README.md + *

+ */ public interface CDPSession { + /** + * Detaches the CDPSession from the target. Once detached, the CDPSession object won't emit any events and can't be used + *

+ * 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); } diff --git a/playwright/src/main/java/com/microsoft/playwright/ChromiumBrowser.java b/playwright/src/main/java/com/microsoft/playwright/ChromiumBrowser.java index a5688e5f..f62afebd 100644 --- a/playwright/src/main/java/com/microsoft/playwright/ChromiumBrowser.java +++ b/playwright/src/main/java/com/microsoft/playwright/ChromiumBrowser.java @@ -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. + *

+ * 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. + *

+ */ 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(); } diff --git a/playwright/src/main/java/com/microsoft/playwright/ChromiumBrowserContext.java b/playwright/src/main/java/com/microsoft/playwright/ChromiumBrowserContext.java index 57c78b6b..b3bb70c5 100644 --- a/playwright/src/main/java/com/microsoft/playwright/ChromiumBrowserContext.java +++ b/playwright/src/main/java/com/microsoft/playwright/ChromiumBrowserContext.java @@ -18,6 +18,10 @@ package com.microsoft.playwright; import java.util.*; +/** + * Chromium-specific features including background pages, service worker support, etc. + *

+ */ public interface ChromiumBrowserContext extends BrowserContext { enum EventType { BACKGROUNDPAGE, @@ -26,8 +30,21 @@ public interface ChromiumBrowserContext extends BrowserContext { void addListener(EventType type, Listener listener); void removeListener(EventType type, Listener listener); + /** + * + * @return All existing background pages in the context. + */ List 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 serviceWorkers(); } diff --git a/playwright/src/main/java/com/microsoft/playwright/ChromiumCoverage.java b/playwright/src/main/java/com/microsoft/playwright/ChromiumCoverage.java index bc6b070e..1d594bba 100644 --- a/playwright/src/main/java/com/microsoft/playwright/ChromiumCoverage.java +++ b/playwright/src/main/java/com/microsoft/playwright/ChromiumCoverage.java @@ -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); } + /** + * NOTE 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); + /** + * NOTE 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(); + /** + * NOTE JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are + *

+ * reported. + * @return Promise that resolves to the array of coverage reports for all scripts + */ ChromiumCoverageStopJSCoverage stopJSCoverage(); } diff --git a/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java b/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java index 5d310eea..84064a04 100644 --- a/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java +++ b/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java @@ -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 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(); } diff --git a/playwright/src/main/java/com/microsoft/playwright/Dialog.java b/playwright/src/main/java/com/microsoft/playwright/Dialog.java index 14f33042..dce1644b 100644 --- a/playwright/src/main/java/com/microsoft/playwright/Dialog.java +++ b/playwright/src/main/java/com/microsoft/playwright/Dialog.java @@ -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(); } diff --git a/playwright/src/main/java/com/microsoft/playwright/Download.java b/playwright/src/main/java/com/microsoft/playwright/Download.java index f64f2b7e..e8e962d4 100644 --- a/playwright/src/main/java/com/microsoft/playwright/Download.java +++ b/playwright/src/main/java/com/microsoft/playwright/Download.java @@ -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. + *

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

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

+ * once download completes: + *

+ * + *

+ * NOTE Browser context **must** be created with the {@code acceptDownloads} set to {@code true} when user needs access to the downloaded content. If {@code acceptDownloads} is not set or set to {@code false}, download events are emitted, but the actual download is not performed and user has no access to the downloaded files. + */ 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(); } diff --git a/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java b/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java index a05f5807..66fa598a 100644 --- a/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java +++ b/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java @@ -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. + *

+ * ElementHandle prevents DOM element from garbage collection unless the handle is disposed. ElementHandles are auto-disposed when their origin frame gets navigated. + *

+ * 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 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. + *

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

+ * Examples: + *

+ * + * @param selector A selector to query 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. + *

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

+ * Examples: + *

+ * + * @param selector A selector to query 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: + *

+ * 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. + *

+ * Wait for actionability checks on the element, unless {@code force} option is set. + *

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

+ * Use page.mouse to click in the center of the element. + *

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

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

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

+ * When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this. + * @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: + *

+ * Wait for actionability checks on the element, unless {@code force} option is set. + *

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

+ * Use page.mouse to click in the center of the element, or the specified {@code position}. + *

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

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

+ * When all steps combined have not finished during the specified {@code timeout}, this method rejects with a TimeoutError. Passing zero timeout disables this. + * @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: + *

+ * Wait for actionability checks on the element, unless {@code force} option is set. + *

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

+ * Use page.mouse to double click in the center of the element, or the specified {@code position}. + *

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

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

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

+ * NOTE {@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()}. + *

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

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

+ * DragEvent + *

+ * FocusEvent + *

+ * KeyboardEvent + *

+ * MouseEvent + *

+ * PointerEvent + *

+ * TouchEvent + *

+ * Event + *

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

+ * + * @param type DOM event type: {@code "click"}, {@code "dragstart"}, etc. + * @param eventInit 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. + *

+ * If the element is not an {@code }, {@code