From d0d56efec1ed60ada382772af1e30005fdfd1a05 Mon Sep 17 00:00:00 2001 From: Guillermo Alvarez Date: Wed, 17 Aug 2022 13:16:25 +0300 Subject: [PATCH] chore: Fix javadoc warnings --- .../java/com/vaadin/testbench/ElementQuery.java | 6 +++++- .../com/vaadin/testbench/HasElementQuery.java | 2 ++ .../testbench/HasPropertySettersGetters.java | 7 +++++++ .../testbench/HasTestBenchCommandExecutor.java | 2 +- .../java/com/vaadin/testbench/Parameters.java | 12 +++++++++--- .../main/java/com/vaadin/testbench/TestBench.java | 2 ++ .../vaadin/testbench/TestBenchDriverProxy.java | 2 ++ .../com/vaadin/testbench/TestBenchElement.java | 6 ++++++ .../com/vaadin/testbench/TestBenchTestCase.java | 8 ++++++++ .../testbench/commands/ScreenshotComparator.java | 3 ++- .../testbench/commands/TestBenchCommands.java | 1 + .../vaadin/testbench/parallel/BrowserUtil.java | 2 ++ .../vaadin/testbench/parallel/ParallelTest.java | 10 ++++++---- .../testbench/parallel/setup/LocalDriver.java | 6 ++++++ .../testbench/parallel/setup/RemoteDriver.java | 5 ++++- .../testbench/parallel/setup/SetupDriver.java | 1 + .../testbench/screenshot/ImageComparison.java | 4 +++- .../testbench/screenshot/ImageFileUtil.java | 15 +++++++++++---- .../vaadin/testbench/screenshot/ImageUtil.java | 11 ++++++++--- 19 files changed, 86 insertions(+), 19 deletions(-) diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/ElementQuery.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/ElementQuery.java index 23a34648a..8c9fb0370 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/ElementQuery.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/ElementQuery.java @@ -226,7 +226,9 @@ public ElementQuery onPage() { } /** - * Return the context (element or driver) to search inside. + * Returns the context (element or driver) to search inside. + * + * @return a {@link SearchContext} instance */ protected SearchContext getContext() { return searchContext; @@ -311,6 +313,8 @@ public T last() { /** * Executes the search and returns the requested element. * + * @param index + * the index of the element to return * @return The element of the type specified in the constructor * @throws NoSuchElementException * if no element is found diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasElementQuery.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasElementQuery.java index ea941587e..9b2351779 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasElementQuery.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasElementQuery.java @@ -18,6 +18,8 @@ public interface HasElementQuery extends HasSearchContext { * it uses the element as its search context. Otherwise the search context * is the driver. * + * @param + * the type of the queried {@link TestBenchElement} * @param clazz * the type of element to find, with the tag name defined using * @Element on the class diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasPropertySettersGetters.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasPropertySettersGetters.java index de03f1b76..7f31c59e2 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasPropertySettersGetters.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasPropertySettersGetters.java @@ -60,6 +60,7 @@ public interface HasPropertySettersGetters extends WebElement { * @param propertyNames * the name of on or more properties, forming a property chain of * type property1.property2.property3 + * @return the value of the property */ public String getPropertyString(String... propertyNames); @@ -69,6 +70,7 @@ public interface HasPropertySettersGetters extends WebElement { * @param propertyNames * the name of on or more properties, forming a property chain of * type property1.property2.property3 + * @return the value of the property */ public Boolean getPropertyBoolean(String... propertyNames); @@ -78,6 +80,7 @@ public interface HasPropertySettersGetters extends WebElement { * @param propertyNames * the name of on or more properties, forming a property chain of * type property1.property2.property3 + * @return the value of the property */ public TestBenchElement getPropertyElement(String... propertyNames); @@ -88,6 +91,7 @@ public interface HasPropertySettersGetters extends WebElement { * @param propertyNames * the name of on or more properties, forming a property chain of * type property1.property2.property3 + * @return the value of the property */ public List getPropertyElements(String... propertyNames); @@ -97,6 +101,7 @@ public interface HasPropertySettersGetters extends WebElement { * @param propertyNames * the name of on or more properties, forming a property chain of * type property1.property2.property3 + * @return the value of the property */ public Double getPropertyDouble(String... propertyNames); @@ -106,6 +111,7 @@ public interface HasPropertySettersGetters extends WebElement { * @param propertyNames * the name of on or more properties, forming a property chain of * type property1.property2.property3 + * @return the value of the property */ public Integer getPropertyInteger(String... propertyNames); @@ -117,6 +123,7 @@ public interface HasPropertySettersGetters extends WebElement { * @param propertyNames * the name of on or more properties, forming a property chain of * type property1.property2.property3 + * @return the value of the property */ public Object getProperty(String... propertyNames); diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasTestBenchCommandExecutor.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasTestBenchCommandExecutor.java index c10bbf175..64e573cb5 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasTestBenchCommandExecutor.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasTestBenchCommandExecutor.java @@ -23,7 +23,7 @@ public interface HasTestBenchCommandExecutor { * Return a reference to the related {@link TestBenchCommandExecutor} * instance. * - * @return + * @return the {@link TestBenchCommandExecutor} instance */ public TestBenchCommandExecutor getCommandExecutor(); diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/Parameters.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/Parameters.java index 6e99105f0..cd5c65bd3 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/Parameters.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/Parameters.java @@ -71,6 +71,8 @@ public class Parameters { * Turns debugging info on/off * * @param isDebug + * {@code true} if debugging info should be turned on, + * {@code false} otherwise */ public static void setDebug(boolean isDebug) { Parameters.isDebug = isDebug; @@ -146,7 +148,8 @@ private static String getQualifiedParameter(String unqualifiedName) { } /** - * @return true if debugging info is to be shown + * @return {@code true} if debugging info should be shown, {@code false} + * otherwise */ public static boolean isDebug() { return isDebug; @@ -158,7 +161,7 @@ public static boolean isDebug() { * cursor. * * @param isScreenshotComparisonCursorDetection - * + * {@code true} to enable cursor detection */ public static void setScreenshotComparisonCursorDetection( boolean isScreenshotComparisonCursorDetection) { @@ -169,7 +172,7 @@ public static void setScreenshotComparisonCursorDetection( * Tells whether to treat screen shots with the only difference being a text * input cursor as equal or not. If true, they will be treated as equal. * - * @return true if cursor detection is used + * @return {@code true} if cursor detection is used, {@code false} otherwise */ public static boolean isScreenshotComparisonCursorDetection() { return isScreenshotComparisonCursorDetection; @@ -179,6 +182,7 @@ public static boolean isScreenshotComparisonCursorDetection() { * Sets the directory to search for reference images. * * @param screenshotReferenceDirectory + * the directory to search for reference images */ public static void setScreenshotReferenceDirectory( String screenshotReferenceDirectory) { @@ -196,6 +200,7 @@ public static String getScreenshotReferenceDirectory() { * Sets the directory where error screen shots are stored. * * @param screenshotErrorDirectory + * the directory path */ public static void setScreenshotErrorDirectory( String screenshotErrorDirectory) { @@ -235,6 +240,7 @@ public static double getScreenshotComparisonTolerance() { * the elements to settle into place. * * @param maxRetries + * the maximum number of retries for screenshot comparisons */ public static void setMaxScreenshotRetries(int maxRetries) { maxScreenshotRetries = maxRetries; diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBench.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBench.java index ae2164937..355174dd3 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBench.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBench.java @@ -141,6 +141,8 @@ public static TestBenchElement createElement(WebElement webElement, * TestBenchCommandExecutor. This feature is advanced and potentially * dangerous. * + * @param + * the type of the {@link TestBenchElement} to return * @param clazz * Class of wanted Element * @param webElement diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchDriverProxy.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchDriverProxy.java index b23266ada..30272256a 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchDriverProxy.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchDriverProxy.java @@ -147,6 +147,8 @@ public WebDriver getWrappedDriver() { * @param tbCommandExecutor * the {@link TestBenchCommandExecutor} related to the driver * instance + * @return a new object containing the wrapped elements and other possible + * values */ protected static Object wrapElementOrElements( Object elementElementsOrValues, diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchElement.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchElement.java index dc154d449..e192462cd 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchElement.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchElement.java @@ -497,6 +497,9 @@ private void autoScrollIntoView() { * Use e.g. as * waitUntil(ExpectedConditions.presenceOfElementLocated(by), 10); * + * @param + * The return type of the {@link ExpectedCondition} and this + * method * @param condition * Models a condition that might reasonably be expected to * eventually evaluate to something that is neither null nor @@ -525,6 +528,9 @@ protected T waitUntil(ExpectedCondition condition, * Use e.g. as * waitUntil(ExpectedConditions.presenceOfElementLocated(by)); * + * @param + * The return type of the {@link ExpectedCondition} and this + * method * @param condition * Models a condition that might reasonably be expected to * eventually evaluate to something that is neither null nor diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchTestCase.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchTestCase.java index 51be7a704..066dfd676 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchTestCase.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchTestCase.java @@ -158,6 +158,8 @@ public List findElements(org.openqa.selenium.By by) { * to use component-specific API on elements found using standard Selenium * API. * + * @param + * the type of the {@link TestBenchElement} to return * @param elementType * The type (class) containing the API to decorate with * @param element @@ -202,6 +204,9 @@ protected Object executeScript(String script, Object... args) { * Use e.g. as * waitUntil(ExpectedConditions.presenceOfElementLocated(by), 10); * + * @param + * The return type of the {@link ExpectedCondition} and this + * method * @param condition * Models a condition that might reasonably be expected to * eventually evaluate to something that is neither null nor @@ -230,6 +235,9 @@ protected T waitUntil(ExpectedCondition condition, * Use e.g. as * waitUntil(ExpectedConditions.presenceOfElementLocated(by)); * + * @param + * The return type of the {@link ExpectedCondition} and this + * method * @param condition * Models a condition that might reasonably be expected to * eventually evaluate to something that is neither null nor diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/ScreenshotComparator.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/ScreenshotComparator.java index 5778f3b9d..0264db962 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/ScreenshotComparator.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/ScreenshotComparator.java @@ -126,8 +126,9 @@ private static BufferedImage getScreenshot(TakesScreenshot driver, * the element to retain in the screenshot * @param fullScreen * the full screen image - * @return + * @return the cropped image * @throws IOException + * if element outside of the screenshot */ public static BufferedImage cropToElement(WebElement element, BufferedImage fullScreen) throws IOException { diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/TestBenchCommands.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/TestBenchCommands.java index c16cc3f66..ee7a239ac 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/TestBenchCommands.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/TestBenchCommands.java @@ -121,6 +121,7 @@ public interface TestBenchCommands extends CanCompareScreenshots { * browser window before interacting with them * * @param autoScrollIntoView + * {@code true} if elements should be scrolled */ void setAutoScrollIntoView(boolean autoScrollIntoView); diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/BrowserUtil.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/BrowserUtil.java index 5c4a03183..fbdceb446 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/BrowserUtil.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/BrowserUtil.java @@ -123,6 +123,7 @@ public static boolean isFirefox(Capabilities capabilities) { * naming and screenshots * * @param capabilities + * to obtain the browser identifier from * @return a human readable string describing the capabilities */ public static String getBrowserIdentifier(Capabilities capabilities) { @@ -146,6 +147,7 @@ public static String getBrowserIdentifier(Capabilities capabilities) { * given capabilities. Used mainly for screenshots * * @param capabilities + * to obtain the platform from * @return a human readable string describing the platform */ public static String getPlatform(Capabilities capabilities) { diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/ParallelTest.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/ParallelTest.java index 4562f30e5..5254166fd 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/ParallelTest.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/ParallelTest.java @@ -157,8 +157,10 @@ public void setup() throws Exception { } /** - * @return Value of the {@link RunOnHub} annotation of current Class, or - * null if annotation is not present. + * @param klass + * the test class to get the {@link RunOnHub} annotation from + * @return Value of the {@link RunOnHub} annotation of passed Class, or null + * if annotation is not present. */ protected RunOnHub getRunOnHub(Class klass) { if (klass == null) { @@ -185,7 +187,6 @@ protected String getRunLocallyBrowserVersion() { } /** - * * @return default capabilities, used if no {@link BrowserConfiguration} * method was found */ @@ -198,6 +199,7 @@ public static List getDefaultCapabilities() { * version) * * @param desiredCapabilities + * to be set */ public void setDesiredCapabilities( DesiredCapabilities desiredCapabilities) { @@ -219,7 +221,7 @@ List getBrowserConfigurationFromParameterOrDefault() { /** * Gets the {@link DesiredCapabilities} (usually browser name and version) * - * @return + * @return the {@link DesiredCapabilities} */ protected DesiredCapabilities getDesiredCapabilities() { return driverConfiguration.getDesiredCapabilities(); diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/LocalDriver.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/LocalDriver.java index d09ac9281..f76d3a4a7 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/LocalDriver.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/LocalDriver.java @@ -36,6 +36,8 @@ public class LocalDriver { /** * Creates a {@link WebDriver} instance used for running the test locally * for debug purposes. Uses firefoxDriver as WebDriver. + * + * @return a driver instance */ static public WebDriver createDriver() { return createDriver(ParallelTest.getDefaultCapabilities().get(0)); @@ -44,6 +46,10 @@ static public WebDriver createDriver() { /** * Creates a {@link WebDriver} instance used for running the test locally * for debug purposes. + * + * @param desiredCapabilities + * the capabilities to use for the driver + * @return a driver instance */ static public WebDriver createDriver( DesiredCapabilities desiredCapabilities) { diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/RemoteDriver.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/RemoteDriver.java index 9f36b5ddd..9da5b01b1 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/RemoteDriver.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/RemoteDriver.java @@ -31,10 +31,13 @@ public class RemoteDriver { /** * Creates a {@link WebDriver} instance used for running the test remotely. * - * @since + * @param hubURL + * the URL of the hub * @param capabilities * the type of browser needed + * @return a driver instance * @throws Exception + * if the driver could not be created */ public WebDriver createDriver(String hubURL, DesiredCapabilities capabilities) throws Exception { diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/SetupDriver.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/SetupDriver.java index 955930c67..1d04080d3 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/SetupDriver.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/SetupDriver.java @@ -144,6 +144,7 @@ public DesiredCapabilities getDesiredCapabilities() { * version) * * @param desiredCapabilities + * to be set */ public void setDesiredCapabilities( DesiredCapabilities desiredCapabilities) { diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageComparison.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageComparison.java index a45301629..4c031f4e4 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageComparison.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageComparison.java @@ -90,8 +90,10 @@ private static class ComparisonParameters { * 0.025 == 2.5%) * @param capabilities * browser capabilities - * @return true if images are the same + * @return {@code true} if images are the same * @throws IOException + * if the reference image cannot be read or error screenshot + * cannot be written */ public boolean imageEqualToReference(BufferedImage screenshotImage, String referenceFileId, double errorTolerance, diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageFileUtil.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageFileUtil.java index 840e8e529..e403836b6 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageFileUtil.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageFileUtil.java @@ -29,7 +29,6 @@ public class ImageFileUtil { * Returns the directory used for screenshot references. * * @return The screenshot reference directory, ending in a slash. - * @return */ public static String getScreenshotReferenceDirectory() { return impl.getScreenshotReferenceDirectory(); @@ -57,8 +56,10 @@ public static void createScreenshotDirectoriesIfNeeded() { * Reads the given reference image into a BufferedImage * * @param referenceImageFileName - * @return + * The name of the reference image file. + * @return a BufferedImage containing the reference image. * @throws IOException + * if an error occurs during reading. */ public static BufferedImage readReferenceImage( String referenceImageFileName) throws IOException { @@ -80,7 +81,9 @@ public static File getReferenceScreenshotFile( * {@link #getReferenceScreenshotFile(String)}. * * @param referenceImageFileName + * id part of the reference image file name * @param capabilities + * used to compute the full name of the alternative references * @return file names of reference images */ public static List getReferenceImageFileNames( @@ -94,7 +97,6 @@ public static class ImageFileUtilImpl { * Returns the directory used for screenshot references. * * @return The screenshot reference directory, ending in a slash. - * @return */ public String getScreenshotReferenceDirectory() { return Parameters.getScreenshotReferenceDirectory(); @@ -145,8 +147,10 @@ public void createScreenshotDirectoriesIfNeeded() { * Reads the given reference image into a BufferedImage * * @param referenceImageFileName - * @return + * The name of the reference image file. + * @return a BufferedImage containing the reference image. * @throws IOException + * if an error occurs during reading. */ public BufferedImage readReferenceImage(String referenceImageFileName) throws IOException { @@ -169,7 +173,10 @@ public File getReferenceScreenshotFile(String referenceImageFileName) { * {@link #getReferenceScreenshotFile(String)}. * * @param referenceImageFileName + * id part of the reference image file name * @param capabilities + * used to compute the full name of the alternative + * references * @return file names of reference images */ public List getReferenceImageFileNames( diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageUtil.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageUtil.java index 73120f0c3..1a70ff1a2 100644 --- a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageUtil.java +++ b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageUtil.java @@ -69,7 +69,8 @@ public static String encodeImageToBase64(BufferedImage image) { * Get luminance value for the given rgb value. * * @param rgb - * @return + * value + * @return luminance of the rgb value */ public static double getLuminance(int rgb) { int r = ((rgb >> 16) & 0xFF); @@ -86,7 +87,11 @@ private static double getLuminance(int r, int g, int b) { /** * Check canvas sizes and resize images to same size * - * @return true/false + * @param image1 + * an image + * @param image2 + * an image + * @return {@code true} if images have same size, {@code false} otherwise */ public static boolean imagesSameSize(BufferedImage image1, BufferedImage image2) { @@ -139,7 +144,7 @@ private static BufferedImage cropImage(BufferedImage image, int width, /** * Create a 16x16 sample buffer with space for 4 color bands * - * @return + * @return sample buffer int array */ public static final int[] createSampleBuffer() { return new int[16 * 16 * 4];