1 package com.atlassian.selenium.visualcomparison.v2;
2
3 import com.atlassian.annotations.ExperimentalApi;
4 import com.atlassian.annotations.PublicSpi;
5 import com.atlassian.selenium.visualcomparison.ScreenElement;
6 import com.atlassian.selenium.visualcomparison.v2.settings.Resolution;
7
8 import javax.annotation.Nonnull;
9 import javax.annotation.Nullable;
10 import java.io.File;
11
12 /**
13 * An SPI to hook in the browser automation framework used to drive the visual comparison.
14 *
15 * @since 2.3
16 */
17 @ExperimentalApi
18 @PublicSpi
19 public interface BrowserEngine
20 {
21 /**
22 * Get an {@link ScreenElement element} that is closest to the point in the document specified by {@code x} and
23 * {@code y}.
24 *
25 * @param x x coordinate of the point of interest
26 * @param y y coordinate of the point of interest
27 * @return element at {@code (x,y)}
28 */
29 @Nonnull
30 ScreenElement getElementAt(int x, int y);
31
32 /**
33 * Resize the browser window to the given {@code resolution}.
34 *
35 * @param resolution resolution to resize to
36 * @return this engine instance for chaining.
37 */
38 @Nonnull
39 BrowserEngine resizeTo(@Nonnull Resolution resolution);
40
41 /**
42 * Capture a screenshot of the current page. This should be an entire document and not just contents of the
43 * viewport.
44 *
45 * @param file file to store the screenshot in
46 * @return this engine instance for chaining.
47 */
48 @Nonnull
49 BrowserEngine captureScreenshotTo(@Nonnull File file);
50
51 /**
52 * Refresh the current page.
53 *
54 * @return this engine instance for chaining.
55 */
56 @Nonnull
57 BrowserEngine reloadPage();
58
59 /**
60 * Execute a Javascript snippet in the context of the current page.
61 *
62 * @param returnType expected return type. At the very least {@code String}, {@code Boolean} and {@link Long}
63 * should be supported.
64 * @param script script to execute
65 * @param args arguments to the script
66 * @param <T> return type parameter
67 * @return result of the script
68 * @throws ClassCastException if the result type was different than expected
69 */
70 @Nullable
71 <T> T executeScript(@Nonnull Class<T> returnType, @Nonnull String script, @Nonnull Object... args);
72 }