diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5f843f0 --- /dev/null +++ b/.gitignore @@ -0,0 +1,29 @@ +# Compiled class file +*.class + +# Log file +*.log + +# BlueJ files +*.ctxt + +# Mobile Tools for Java (J2ME) +.mtj.tmp/ + +# Package Files # +*.jar +*.war +*.nar +*.ear +*.zip +*.tar.gz +*.rar + +# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml +hs_err_pid* + +### IntelliJ IDEA ### +.idea +*.iws +*.iml +*.ipr \ No newline at end of file diff --git a/Documentation.en.md b/Documentation.en.md deleted file mode 100644 index ea446fb..0000000 --- a/Documentation.en.md +++ /dev/null @@ -1,371 +0,0 @@ -# Aquality Selenium - -Aquality Selenium is a library built over Selenium WebDriver tool that allows to automate work with web browsers. Selenium WebDriver requires some skill and experience. So, Aquality Selenium suggests simplified and most importantly the safer and more stable way to work with Selenium WebDriver. - -The main benefits from using Aquality Selenium: - -1. Simple configuration -2. Parallel runs -3. Flexible browser (web driver) construction -4. Stable and predictable interactions with elements -5. Smart conditional waits -6. Pack of JavaScripts for advanced usage - -**CONTENT** - - 1. PLATFORM SUPPORT - - 2. CONFIGURATIONS - - 2.1. SETTINGS - - 2.2. BROWSER - - 2.3. DRIVER SETTINGS - - 2.4. TIMEOUTS - - 2.5. RETRY POLICY - - 2.6. LOGGING - - 2.7. CLOUD USAGE - - 2.8. ACTIONS HIGHLIGHTING - - 2.9. ACCESS FROM THE CODE - - 3. BROWSER - - 3.1. PARALLEL RUNS - - 3.2. AQUALITY SERVICES - - 3.3. BROWSER FACTORY - - 3.4. DRIVER CAPABILITIES - - 3.5. DOWNLOAD DIRECTORY - - 3.6. ALERTS - - 3.7. SCREENSHOTS - - 4. ELEMENTS - - 4.1. ELEMENT FACTORY - - 4.2. CUSTOM ELEMENTS - - 4.3. LIST OF ELEMENTS - - 4.4. STATES OF ELEMENTS - - 5. FORMS - - 6. JAVASCRIPT EXECUTION - - 7. JSON FILE - - 8. CONDITIONAL WAIT - -### 1. PLATFORM SUPPORT -At the moment Aquality Selenium allows to automate web tests for Chrome, Firefox, Safari, IExplorer and Edge. Also you can implement support of new browsers that Selenium supports -(more [here](https://www.seleniumhq.org/about/platforms.jsp)). -Tests can be executed on any operating system with installed JDK of version 8 and higher. - -### 2. CONFIGURATIONS - -Aquality Selenium provides flexible configuration to run tests by editing [settings.json](./src/main/resources/settings.json) -Most of the settings are clear without further explanation but major points are highlighted below. -There is a possibility to implement your own configuration. - -### 2.1. SETTINGS - -Solution provides [settings.json](./src/main/resources/settings.json) or it's changed copies for configuration of test run. -Copy file [settings.json](./src/main/resources/settings.json) into directory `/src/main/resources` if you are going to place your code under `/src/main`. -If you use `/src/test` copy settings into `/src/test/resources`. - -Users can keep several copies of settings file that are different by some parameters. -Copies should be saved in 'main/resources' or 'test/resources' depends on where you will use Aquality library. -Changed copies can be useful if it is necessary to run tests on different operation systems, virtual machines, browsers and etc. -For example, Aquality dev team uses 2 configurations [settings.json](./src/main/resources/settings.json) and [settings.local.json](./src/test/resources/settings.local.json) -to run tests on CI and on personal machines and internal infrastructure. - -To use one of the copies user should set environment variable with name `profile` and value 'local' (local name is an example for file settings.local.json) -To run with Maven execution command can look like: `clean test -Dprofile=local`. -If user have not passed any env variables the settings by default will be used (settings.json from the resource folder). - -Any parameter of [settings.json](./src/main/resources/settings.json) can be overrided by environment variable. -To override user should create environment variable where name is a jsonPath and value - wished value. For example, below `driverSettings.chrome.webDriverVersion` is overrided: -`clean test -DdriverSettings.chrome.webDriverVersion=77.0.3865.10` - -Settings file consists from several sections which described in details below. - -#### 2.2. BROWSER -`browserName` parameter defines browser to run tests. For example, `browser=chrome` allow to run tests on Google Chrome. - -`isRemote` parameter defines whether tests will be excecuted locally or on remote server reached by URL from `remoteConnectionUrl` parameter. - -#### 2.3. DRIVER SETTINGS -`driverSettings` section [settings.json](./src/main/resources/settings.json) provides abilities to set capabilities, options and start arguments for web driver. - -The full list of allowed options can be found on official sites of Selenium and Browser's producers. For example, for chrome: [run-chromium-with-flags](https://www.chromium.org/developers/how-tos/run-chromium-with-flags) - -There are some niceties with using InternetExplorer browser. We tried to describe [here](./README_InternetExplorer.md) most of them to keep all this information in one place. - -#### 2.4. TIMEOUTS - -[settings.json](./src/main/resources/settings.json) contains section `timeouts`. It includes list of timeout parameters that are used in the Aquality. - -All parameters are used to initialise [TimeoutConfiguration](./src/main/java/aquality/selenium/configuration/TimeoutConfiguration.java) class instance. After initialising parameters can be fetched by call `AqualityServices.getConfiguration().getTimeoutConfiguration()`. - -Below is a description of timeouts: - -- `timeoutImplicit` = 0 - implicit wait of web driver - [Selenium Implicit Wait](https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp#implicit-waits). -- `timeoutCondition` = 15 - default timeout to wait conditions: waiting for elements, waiting for element's state. -- `timeoutScript` = 10 - timeout for execution async JavaScripts with WebDriver method **executeAsyncScript** -- `timeoutPageLoad` = 30 - time to wait until page is load -- `timeoutPollingInterval` = 300 - interval between checks if condition meets to expected -- `timeoutCommand` = 120 - timeout for connection to remote server (applied only for remote runs) - -All waits in the Aquality Selenium use Excplicit Wait. -Each time before explicit wait value of implicit wait will be set into 0. And after wait will be restored to the default value. -It is not recommended to use implicit and explicit waits together. - -#### 2.5 RETRY POLICY - -`retry` section of [settings.json](./src/main/resources/settings.json) is responsible to configure number of attempts of manipulations with element (click, type, focus and etc.) -All the operations can be executed several times if they failed at first attempt. - -This logic is implemented in the [ElementActionRetrier](https://github.com/aquality-automation/aquality-selenium-core-java/blob/master/src/main/java/aquality/selenium/core/utilities/ElementActionRetrier.java) class. This class is used for any manipulations with elements. -`number` parameter keeps value of number of attempts. An exception will be thrown if attempts are over. -`pollingInterval` keeps value of interval in **milliseconds** between attempts. -[ElementActionRetrier](https://github.com/aquality-automation/aquality-selenium-core-java/blob/master/src/main/java/aquality/selenium/core/utilities/ElementActionRetrier.java) catches StaleElementReferenceException and InvalidElementStateException by default. - -#### 2.6. LOGGING -Aquality logs operations that executes (interaction with browser, elements of the pages). Example of some log: - -2019-07-18 10:14:08 INFO - Label 'First product' :: Moving mouse to element - -Aquality provides logging on English and Russian languages - -- [en](./src/main/resources/localization/en.json) -- [ru](./src/main/resources/localization/ru.json) - -Logging language should be configured as parameter [logger.language](./src/main/resources/settings.json). - -#### 2.7. CLOUD USAGE - -URL to remote server should be set in parameter `remoteConnectionUrl` and parameter `isRemote` should be **true** to run tests on a remote Selenium Grid server (Selenoid, Zalenium) or cloud platforms like BrowserStack, Saucelabs and etc. -For example, to use BrowserStack `remoteConnectionUrl` can be look like [https://USERNAME:AUTOMATE_KEY@hub-cloud.browserstack.com/wd/hub](https://USERNAME:AUTOMATE_KEY@hub-cloud.browserstack.com/wd/hub). - -#### 2.8. ACTIONS HIGHLIGHTING - -`isElementHighlightEnabled` parameter is responsible for highlighting elements that web driver interact with. -If parameter has value `true` user will be able to see actions more explicit (red border will be added around web element that driver interact with) - -#### 2.9. ACCESS FROM THE CODE - -Sometimes you need access to values from settings file from the code. To get it you can use [Configuration](./src/main/java/aquality/selenium/configuration/IConfiguration.java) class instance. -Example of usage: -``` -AqualityServices.getConfiguration().getBrowserProfile().getBrowserName() -``` -returns value of parameter "browser". - -You can also resolve the needed configuration from the AqualityServices directly: -```java -AqualityServices.get(IRetryConfiguration.class).getNumber(); // returns number of retry attempts for element actions, e.g. clicking. -AqualityServices.getBrowserProfile(); // returns currently used set of browser settings. -``` - -### **3. BROWSER** - -Class Browser is a facade around WebDriver and provides methods to work with Browser window and WebDriver itself (for example: navigate, maximize window and etc.). -Developing of test begins from creating instance of the Browser class. In the next chapters more details about that. - -#### 3.1. PARALLEL RUNS - -Aquality Selenium built around concept 'one browser instance per thread'. -In most cases tests interact with one instance of Browser and this approach looks enough optimal. - -To use several browsers during the same test each browser should be created in independent thread. -Examples of using Aquality Selenium in multi-thread mode are here [BrowserConcurrencyTests.java](./src/test/java/tests/usecases/BrowserConcurrencyTests.java) - -Test runners like TestNG, JUnit and etc. start each test in the separate thread from the box. So users do not need to do additional work if they are using such runners. - -To use parallel streams that provided by Java from 8th version it is necessary to use AqualityServices to pass correct instance of Browser to stream function. Else parallel stream will create new Browser instances for each thread. -The example of usage parallel streams is here [testShouldBePossibleToUseParallelStreams](./src/test/java/tests/usecases/BrowserConcurrencyTests.java). - -#### 3.2. AQUALITY SERVICES -Class [AqualityServices](https://github.com/aquality-automation/aquality-selenium-java/blob/Feature/Reference-aquality.selenium.core/src/main/java/aquality/selenium/browser/AqualityServices.java) provides static methods to access Browser and other utilities included in the library. - -Usage of AqualityServices is thread-safe. Inside AqualityServices uses DI container Guice. - -You can override any service implementation in the class extended from [BrowserModule](https://github.com/aquality-automation/aquality-selenium-java/blob/Feature/Reference-aquality.selenium.core/src/main/java/aquality/selenium/browser/BrowserModule.java), and then re-initialize AqualityServices in your code using the method ```AqualityServices.initInjector(customModule)```. -Take a look at example of custom module implementation here: [BrowserFactoryTests](https://github.com/aquality-automation/aquality-selenium-java/blob/Feature/Reference-aquality.selenium.core/src/test/java/tests/usecases/BrowserFactoryTests.java) - -#### 3.3. BROWSER FACTORY - -There are several ways to create instance of class Browser. -The main approach based on the usage of `AqualityServices` class and it's static methods. Below are options of `AqualityServices` usage. - -For most cases users need to get Browser instance based on data from the settings file. To get Browser in this case use following: - -``` -Browser browser = AqualityServices.getBrowser() -``` - -The first call of `getBrowser()` method will create instance of Browser with WebDriver inside (browser window will be opened). -The next calls of `getBrowser()` in the same thread will return the same instance. - -Implicitly for users `AqualityServices` provides `Browser` through calls to browser factories. -Aquality Selenium implements following factories: - -- [LocalBrowserFactory](./src/main/java/aquality/selenium/browser/LocalBrowserFactory.java) - to creating Browser on local machine (parameter `isRemote=false`) -- [RemoteBrowserFactory](./src/main/java/aquality/selenium/browser/RemoteBrowserFactory.java) - to creating Browser on remote server (parameter `isRemote=true`) - -Each factory implementation implements interface `IBrowserFactory` with the single method `Browser` `getBrowser()`. -Users are allowed to create their on implementations if necessary. - -To use custom factory implementation users should set it into `AqualityServices` before first call of `getBrowser()` method: -``` -AqualityServices.setFactory(IBrowserFactory browserFactory) -``` -The examples of usages custom factories can be found here [BrowserFactoryTests](./src/test/java/tests/usecases/BrowserFactoryTests.java) - -If there are reasons to not to use factories user is able to create Browser instance using constructor and then put it into AqualityServices: -``` -AqualityServices.setBrowser(Browser browser) -``` - -Browser class has public constructor with the signature: `Browser(RemoteWebDriver remoteWebDriver)`. Other needed services are resolved from the DI container. For example, user could implement his own implementation of `IConfiguration` - but existing IConfiguration implementation can be used, inherited, used partially(`IDriverSettings`, `ITimeoutConfiguration` and etc.) - -#### 3.4. DRIVER CAPABILITIES - -During the testing sometimes is needed to set additional options and capabilities to web driver. -During Browser instantiating and especially WebDriver the implementations of `IDriverSettings` interface are used. -List of capabilities and options is defined in the [settings.json](./src/main/resources/settings.json) file if user uses `BrowserFactory` by default. - -To use custom capabilities user can follow the examples here [testShouldBePossibleToSetFactory](./src/test/java/tests/usecases/BrowserFactoryTests.java). - - - -#### 3.5. DOWNLOAD DIRECTORY - -Often users are needed to download files and then process them. -To get current download directory use `getDownloadDirectory()` of `Browser` instance. - -Behind this call directory will be fetched from the [settings.json](./src/main/resources/settings.json). -For example: - -``` -{ - "download.default_directory": ".//target//downloads//" -} -``` - - Note: key `download.default_directory` is different for different browsers. To learn which keys should be used for browsers take a look at implementations of `IDriverSettings`: - -[ChromeSettings.java](./src/main/java/aquality/selenium/configuration/driversettings/ChromeSettings.java) - -[FirefoxSettings.java](./src/main/java/aquality/selenium/configuration/driversettings/FirefoxSettings.java) - -At this moment Aquality Selenium supports downloading files only for browsers Chrome, Firefox, Safari. -But there are no restrictions to add your own implementation. - -#### 3.6. ALERTS - -`Browser` class provides methods to work with alerts and prompts dialogs: - -``` -AqualityServices.getBrowser().handleAlert(AlertActions.ACCEPT); -``` - -More examples here: [AlertTests.java](./src/test/java/tests/integration/AlertTests.java). - -#### 3.7. SCREENSHOTS - -To take a screenshot of the page there is the method: -``` -AqualityServices.getBrowser().getScreenshot() -``` - -Example of taking screenshots here: [testShouldBePossibleToMakeScreenshot](./src/test/java/tests/integration/BrowserTests.java) - -### **4. ELEMENTS** - -When Browser instantiated and navigation to necessary page is done user can begin to interact with elements of the page. - -#### 4.1. ELEMENT FACTORY - -[ElementFactory](./src/main/java/aquality/selenium/elements/ElementFactory.java) is responsible to provide elements of necessary types. -Below is an example of getting ITextBox element: - -``` -IElementFactory elementFactory = AqualityServices.getElementFactory(); -ITextBox txbUsername = elementFactory.getTextBox(By.id("username"), "Username"); -``` -`ElementFactory` is able to build elements of any types that implements `IElement` interface. -`ElementFactory` has list of methods that returns default(most useful) implementations of `IElement` (`IButton`, `ITextBox`, `ICheckbox` and etc.). - -#### 4.2. CUSTOM ELEMENTS - -User has abilities to create his own type of element by implementing interface or using inheritance. -For this goal `ElementFactory` provides method ` T getCustomElement`. -Example of creating custom element here [CustomElementTests](./src/test/java/tests/usecases/CustomElementTests.java). - -#### 4.3. LIST OF ELEMENTS - -To get list of elements `ElementFactory` provides method `findElements`: - -``` -List checkBoxes = elementFactory.findElements(By.xpath(checkboxLocator), ElementType.CHECKBOX); -``` - -More examples here: [ElementTests.java](./src/test/java/tests/integration/ElementTests.java). - - -#### 4.4. STATES OF ELEMENTS - -For most cases before manipulating with web element user should wait util element is displayed on the page. -And `ElementFactory` provides you displayed elements by default. -But for cases if user wants to manipulate with hidden elements (that there are in the HTML DOM, but are not displayed) there are overrided methods. - -``` -elementFactory.getLink(By.id("redirect"), "Link", ElementState.EXISTS_IN_ANY_STATE); -``` - -Often users have to wait for some state of elements or just getting current state to next check. -This functionality is implemented in the class [ElementStateProvider](./src/main/java/aquality/selenium/elements/ElementStateProvider.java) -Access to the state of element user can get through the `state()` method: -``` -getTxbInput().state().waitForEnabled(); -getTxbInput().state().isDisplayed(); -``` -More examples here: [ElementStateTests](./src/test/java/tests/integration/ElementStateTests.java). - -### **5. FORMS** - -The main purpose of the Aquality Selenium is to help in test automation of web applications. -Page Object pattern that is widely used in test automation [Page Objects](https://github.com/SeleniumHQ/selenium/wiki/PageObjects). -To support this popular approach Aquality Selenium provides [Form](./src/main/java/aquality/selenium/forms/Form.java) class that can be used as the base class for page objects of testing solution. -The example of usage below: -``` -public class SliderForm extends Form { - public SliderForm() { - super(By.id("slider_row"), "Slider"); - } -} -``` -Here id = "slider\_row" sets the locator that will be used for verification whether the page displayed or not (method `isFormDisplayed()`). - -The simple example of the test with page object here: [ShoppingCartTest.java](./src/test/java/tests/usecases/ShoppingCartTest.java). - - -### **6. JAVASCRIPT EXECUTION** - -To execute an JavaScript on the page users can use methods like: -``` -browser.executeScript(final String script, Object... arguments). -``` - -Also Aquality Selenium provides list of most usefull JavaScripts from the box. -Such scripts are placed here `/src/main/resources/js`. -The examples of usage here: [BrowserTests](./src/test/java/tests/integration/BrowserTests.java). -There are several overrided methods that takes scripts as String, File or JavaScript internal type. - -### **7. JSON FILE** - -Aquality Selenium uses [JsonSettingsFile](https://github.com/aquality-automation/aquality-selenium-core-java/blob/master/src/main/java/aquality/selenium/core/utilities/JsonSettingsFile.java) class to process the JSON files. -Users can use this class to process JSON files from their own project. -For example, if user wants to keep URL to web site that is automating he can put this URL in some JSON file and read value with mentioned class: -``` -ISettingsFile environment = new JsonSettingsFile("settings.json") -String url = environment.getValue("/url").toString(); -``` -### **8. CONDITIONAL WAIT** - -If you need to wait for any condition to be met, you can use the [ConditionalWait](https://github.com/aquality-automation/aquality-selenium-core-java/blob/master/src/main/java/aquality/selenium/core/waitings/ConditionalWait.java) class provided by Aquality Selenium. -```java -File fileDownloaded = new File(downloadDirInitialized + fileName); -AqualityServices.getConditionalWait().waitForTrue(() -> fileDownloaded.exists(), - Duration.ofSeconds(120), Duration.ofMillis(300), "File should be downloaded"); -``` -All class methods wait for the condition to be met, but return values and handle exceptions ​​differently: -1. ```waitForTrue``` - throws an exception if the condition is not met, returns nothing. -2. ```boolean waitFor``` - returns true if the condition is fulfilled or false otherwise. Method does not throw any exception. -3. ``` T waitFor``` - uses the WebDriver's wait, returns a T object or an exception if the condition is not met. diff --git a/Documentation.ru.md b/Documentation.ru.md deleted file mode 100644 index b7b2357..0000000 --- a/Documentation.ru.md +++ /dev/null @@ -1,344 +0,0 @@ -# Aquality Selenium - -Aquality Selenium является надстройкой над инструментом работы с браузером посредством Selenium WebDriver. Работа с Selenium WebDriver требует определенных навыков и опыта. Aquality Selenium предлагает упрощенный, а главное более безопасный и стабильный способ работы с Selenium WebDriver. - -Основные преимущества использования Aquality Selenium: - -1. Простая конфигурация -2. Поддержка запусков в параллели -3. Гибкая настройка браузера -4. Стабильная и предсказуемая работа с элементами -5. Явные ожидания -6. Набор скриптов JavaScripts для работы в исключительных ситуациях - -**СОДЕРЖАНИЕ** - - - 1. PLATFORM SUPPORT - - 2. CONFIGURATIONS - - 2.1. SETTINGS - - 2.2. BROWSER - - 2.3. DRIVER SETTINGS - - 2.4. TIMEOUTS - - 2.5. RETRY POLICY - - 2.6. LOGGING - - 2.7. CLOUD USAGE - - 2.8. ACTIONS HIGHLIGHTING - - 2.9. ACCESS FROM THE CODE - - 3. BROWSER - - 3.1. PARALLEL RUNS - - 3.2. AQUALITY SERVICES - - 3.3. BROWSER FACTORY - - 3.4. DRIVER CAPABILITIES - - 3.5. DOWNLOAD DIRECTORY - - 3.6. ALERTS - - 3.7. SCREENSHOTS - - 4. ELEMENTS - - 4.1. ELEMENT FACTORY - - 4.2. CUSTOM ELEMENTS - - 4.3. LIST OF ELEMENTS - - 4.4. STATES OF ELEMENTS - - 5. FORMS - - 6. JAVASCRIPT EXECUTION - - 7. JSON FILE - - 8. CONDITIONAL WAIT - -### 1. PLATFORM SUPPORT -В настоящее время Aquality Selenium позволяет автоматизировать веб тесты для Chrome, Firefox, Safari, IExplorer, Edge. Также присутствуют возможности самостоятельно реализовать поддержку новых браузеров, которые поддерживаются Selenium (подробнее [здесь](https://www.seleniumhq.org/about/platforms.jsp)). -При этом запуск тестов может выполняться на любой операционной системе с установленным на ней JDK версии 8 и выше. - -### 2. CONFIGURATIONS - -Aquality Selenium предоставляет пользователю гибкие возможности по конфигурации запусков путём предоставления к редактированию конфигурационного файла [settings.json](./src/main/resources/settings.json) -Большинство настроек понятны без дополнительных объяснений, но основные моменты обозначены ниже в данном разделе. -Также существует возможность использования Aquality Selenium реализовав собственные классы конфигурации. - -### 2.1. SETTINGS - -Работа с решением подразумевает использование [settings.json](./src/main/resources/settings.json) или его измененных копий для запуска тестов. -Если вы работаете в директории /src/`test`, то для начала работы скопируйте файл [settings.json](./src/main/resources/settings.json) в директорию `/src/test/resources`. - -По умолчанию у вас есть возможность вносить любые желаемые изменения в settings файл. -Но также можно создать несколько копий settings файла для единовременного хранения нескольких конфигураций, отличающихся какими-либо параметрами. -При этом создавать данные файлы необходимо в директории 'main/resources' или 'test/resources' в зависимости от того, где вы планируете работать с библиотекой (в main или test). -Как правило это удобно, когда есть необходимость выполнять запуск тестов на различных операционных системах, машинах, браузерах и т.п. -Например, в настоящее время команда разработчиков Aquality Selenium использует две конфигурации [settings.json](./src/main/resources/settings.json) и [settings.local.json](./src/test/resources/settings.local.json) для выполнения запусков в локальном docker Circle CI и на персональной инфраструктуре. -Для того, чтобы удобно управлять тем, какой конфигурационный файл необходимо использовать можно установить переменную окружения с именем profile и присвоить ей желаемое значение (например, local). -В случае запуска при помощи Maven команда запуска может выглядеть так: `clean test -Dprofile=local`. -По умолчанию во время запусков используется [settings.json](./src/main/resources/settings.json). - -Любой параметр [settings.json](./src/main/resources/settings.json) может быть также переопределен через переменную окружения. -Для этого необходимо указать jsonPath к параметру в json и его значение. Например: -`clean test -DdriverSettings.chrome.webDriverVersion=77.0.3865.10` - -Settings файл содержит в себе несколько секций, назначение которых описывается ниже. - -#### 2.2. BROWSER -`browserName` параметр определяет на каком браузере будет выполняться запуск. Например browser=chrome - означает, что запуск осуществиться в Google Chrome. - -`isRemote` параметр определят будет ли запуск выполняться на той же машине, где выполняется java процесс или использовать удалённый сервер, указанный в параметре `remoteConnectionUrl`. - -#### 2.3. DRIVER SETTINGS -`driverSettings` секция файла [settings.json](./src/main/resources/settings.json) предоставляет возможность устанавливать необходимые capabilities, options или start arguments для web driver. - -Для получения допустимых аргументов и опций обратитесь к официальным источникам от разработчиков браузеров. Например, для chrome: [run-chromium-with-flags](https://www.chromium.org/developers/how-tos/run-chromium-with-flags) - -Мы постарались [здесь](./README_InternetExplorer.md) описать особенности работы с IExplorer самостоятельно ввиду разрознености информации на этот счёт в интернете. - -#### 2.4. TIMEOUTS - -[settings.json](./src/main/resources/settings.json) содержит секцию `timeouts`, которая включает в себя набор параметров, связанных с различного рода таймаутами, используемыми в решении. - -Все параметры данной конфигурации используются для инициализации объекта класса [TimeoutConfiguration](./src/main/java/aquality/selenium/configuration/TimeoutConfiguration.java), доступного впоследствии путем обращения `AqualityServices.getConfiguration().getTimeoutConfiguration()`. - -Ниже приводится описание параметров из секции `timeouts` c их назначением: - -- `timeoutImplicit` = 0 - значение неявного ожидания web driver [Selenium Implicit Wait](https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp#implicit-waits). -- `timeoutCondition` = 15 - время ожидания событий в решении. К событиям относятся ожидание элементов или их состояния. -- `timeoutScript` = 10 - данное значение служит лимитом выполнения скриптов с использованием метода WebDriver **executeAsyncScript** -- `timeoutPageLoad` = 30 - время ожидания загрузки страницы -- `timeoutPollingInterval` = 300 - интервал опроса в при явных ожиданиях - -В рамках решения все ожидания элементов выполняются при помощи Excplicit Wait. -Перед ожиданием элемента значение implicit wait будет установлено принудительно, независимо от того, что находится в конфигурации. -Использование двух типов ожиданий не рекомендовано, так как может приводить к некорректному поведению. - -#### 2.5 RETRY POLICY - -Секция `retry` файла [settings.json](./src/main/resources/settings.json) отвечает за конфигурацию количества попыток выполнения операций над элементом. -Все операции над элементами (нажатия, ввод текста и т.п.) могут быть выполнены повторно в случае неудачи. -Данная логика заложена в классе [ElementActionRetrier](https://github.com/aquality-automation/aquality-selenium-core-java/blob/master/src/main/java/aquality/selenium/core/utilities/ElementActionRetrier.java) посредством которого выполняются любые операции. -Параметр `number` означает количество предпринимаемых попыток выполнить операцию прежде чем выбросить исключение. -Параметр `pollingInterval` означает интервал между попытками в миллисекудах. -[ElementActionRetrier](https://github.com/aquality-automation/aquality-selenium-core-java/blob/master/src/main/java/aquality/selenium/core/utilities/ElementActionRetrier.java) автоматически отлавливает исключения StaleElementReferenceException и ElementNotInteractableException) и повторяет попытку снова. - -#### 2.6. LOGGING -Решение поддерживает логирование выполняемых операций (взаимодействие с браузером, элементами страницы). Пример логирования: - -2019-07-18 10:14:08 INFO - Label 'First product' :: Moving mouse to element - -Логирование поддерживается на языках - -- [en](./src/main/resources/localization/en.json) - английский -- [ru](./src/main/resources/localization/ru.json) - русский - -Значение языка логирования устанавливается в параметре [logger.language](./src/main/resources/settings.json). - -#### 2.7. CLOUD USAGE - -Для того, чтобы настроить запуск на удалённом сервере Selenium Grid (Selenoid, Zalenium) или на платформах вроде BrowserStack, Saucelabs и т.д., необходимо в конфигурационном файле [settings.json](./src/main/resources/settings.json) установить корректное значение URL для подключения к сервису в параметр `remoteConnectionUrl`, а также убедиться, что параметр `isRemote` равен **true**. -Например, для BrowserStack параметр может иметь вид [https://USERNAME:AUTOMATE_KEY@hub-cloud.browserstack.com/wd/hub](https://USERNAME:AUTOMATE_KEY@hub-cloud.browserstack.com/wd/hub). - -#### 2.8. ACTIONS HIGHLIGHTING - -`isElementHighlightEnabled` параметр отвечает за необходимость подсветки элементов веб страницы с которыми производится работа. Включение опции позволяет более явно наблюдать за действиями теста. - -#### 2.9. ACCESS FROM THE CODE - -Доступ к данным из конфигурационного файла обеспечивается посредством обращения к методам экземпляра класса [Configuration](./src/main/java/aquality/selenium/configuration/IConfiguration.java) -Например: -``` -AqualityServices.getConfiguration().getBrowserProfile().getBrowserName() -``` -вернёт значение параметра "browser" из settings файла. - -Также, вы можете получить нужный вам класс конфигурации через AqualityServices напрямую: -```java -AqualityServices.get(IRetryConfiguration.class).getNumber(); // вернёт количество попыток для действий над элементом, напр. нажатия -AqualityServices.getBrowserProfile(); // вернёт текущий набор настроек браузера. -``` - -### **3. BROWSER** - -Класс Browser, являющийся своего рода фасадом для WebDriver и содержит методы работы с окном браузера и непосредственно с WebDriver (например, navigate, maximize window и т.д.). Написание скрипта начинается с создания экземпляра `Browser` - подробнее об этом ниже. - -#### 3.1. PARALLEL RUNS - -Решение предполагает наличие единственного экземпляра класса `Browser` (содержит поле типа RemoteWebDriver) в рамках одного потока исполнения. Как правило тесты работают с одним экземпляром браузера и данный подход оптимален. - -Если вы решаете задачу использования в рамках одного теста несколько браузеров, каждый браузер необходимо создавать в отдельном потоке. С примерами работы в многопоточном режиме можно ознакомиться здесь [BrowserConcurrencyTests.java](./src/test/java/tests/usecases/BrowserConcurrencyTests.java) - -Если вы используете стандартные средства параллелизации, предоставляемые такими инструментами как TestNG, JUnit и т.п., для каждого потока будет автоматически создан свой экземпляр Browser. - -Если вы хотите использовать parallel streams доступных в Java начиная с 8ой версии, необходимо использовать AqualityServices для установки текущей версии Browser, иначе parallel stream создаст по одному новому браузеру на каждый параллельный поток. -Пример использования parallel streams приводится в [testShouldBePossibleToUseParallelStreams](./src/test/java/tests/usecases/BrowserConcurrencyTests.java). - -#### 3.2. AQUALITY SERVICES -Класс [AqualityServices](https://github.com/aquality-automation/aquality-selenium-java/blob/Feature/Reference-aquality.selenium.core/src/main/java/aquality/selenium/browser/AqualityServices.java) предоставляет статические методы для доступа к классу Browser и другим утилитам, включённым в данную библиотеку. - -Использование AqualityServices потокобезопасно. Внутри AqualityServices используют DI контейнер Guice. - -Вы можете переопределить реализацию любого из сервисов в классе, отнаследованом от [BrowserModule](https://github.com/aquality-automation/aquality-selenium-java/blob/Feature/Reference-aquality.selenium.core/src/main/java/aquality/selenium/browser/BrowserModule.java), и затем проинициализировать AqualityServices в коде, используя метод ```AqualityServices.initInjector(customModule)```. -Пример использования своей реализации модуля тут: [BrowserFactoryTests](https://github.com/aquality-automation/aquality-selenium-java/blob/Feature/Reference-aquality.selenium.core/src/test/java/tests/usecases/BrowserFactoryTests.java) - -#### 3.3. BROWSER FACTORY - -Существует несколько вариантов инициализации Browser. Основной способ базируется на использовании класса `AqualityServices` c набором статических методов для получения `Browser`. Ниже рассматриваются варианты работы с `AqualityServices`. - -Если нам необходимо получить браузер с данными из конфигурационого settings файла то достаточно просто произвести вызов: - -``` -Browser browser = AqualityServices.getBrowser() -``` - -Первый вызов `getBrowser()` создаст необходимый экземпляр с WebDriver (откроется окно браузера, если только не задан headless режим). Все последующие обращения в рамках одного потока будут работать с созданным экземпляром. - -Неявно для пользователя `AqualityServices` предоставляет `Browser` посредством обращения к фабрике браузеров. В решение существуют следующие реализации фабрик: - -- [LocalBrowserFactory](./src/main/java/aquality/selenium/browser/LocalBrowserFactory.java) - для создания браузера в случае использования параметра `isRemote=false` -- [RemoteBrowserFactory](./src/main/java/aquality/selenium/browser/RemoteBrowserFactory.java) - для создания браузера в случае использования параметра `isRemote=true` - -Каждая реализация фабрики реализует интерфейс `IBrowserFactory` с единственным методом `Browser` `getBrowser()`. Это предоставляет возможность реализовать свою фабрику. -Чтобы `getBrowser()` возвращал `Browser`, созданный вашей реализацией фабрики, необходимо до первого вызова `getBrowser()` установить в `AqualityServices` свою реализацию фабрики, -используя метод `setFactory(IBrowserFactory browserFactory)`. -Примеры использования собственной фабрики можно рассмотреть здесь [BrowserFactoryTests](./src/test/java/tests/usecases/BrowserFactoryTests.java) - -Если по каким либо причинам вы решите отказаться от использования фабрик, у вас остается возможность создать экземпляр `Browser` самостоятельно и в дальнейшем установить его в `AqualityServices.setBrowser(Browser browser)`. -Класс Browser содержит публичный конструктор со следующей сигнатурой `Browser(RemoteWebDriver remoteWebDriver)`. Остальные необходимые сервисы получаются из DI контейнера. К примеру, вы можете создать свою реализацию `IConfiguration` - но при этом вам по прежнему доступно использовать уже имеющуюся реализацию Configuration, наследоваться от неё, использовать имеющиеся реализации `IDriverSettings`, `ITimeoutConfiguration` и т.д. - -#### 3.4. DRIVER CAPABILITIES - -В процессе создания Browser и в частности WebDriver используются реализации интерфейса `IDriverSettings`. Реализация включает метод getCapabilities, которые впоследствии устанавливаются в WebDriver при его инициализации. -Если вы пользуетесь `BrowserFactory` по умолчанию, список capabilities будет сформирован на основании информации в [settings.json](./src/main/resources/settings.json) файле. - -Пример с использованием пользовательских capabilities представлен зедсь [testShouldBePossibleToSetFactory](./src/test/java/tests/usecases/BrowserFactoryTests.java). - - - -#### 3.5. DOWNLOAD DIRECTORY - -Не редким случаем является необходимость скачивать файлы в браузере и впоследствии производить с ними работу. Чтобы получить текущую директорию для загрузки можно воспользоваться методом `getDownloadDirectory()` экземпляра `Browser`. - -Для поддержания этой функциональности интерфейс `IDriverSettings` обязывает реализовать метод String getDownloadDir(). Если вы используете одну из уже реализованных BrowserFactory, то директорию для загрузки файлов необходимо указать в файле [settings.json](./src/main/resources/settings.json). -Например: - -``` -{ - "download.default_directory": ".//target//downloads//" -} -``` - -Обратите внимание, что ключ download.default\_directory отличается для разных браузеров. Изучить какие ключи актуальны для каких браузеров можно в соответствующих классах - -[ChromeSettings.java](./src/main/java/aquality/selenium/configuration/driversettings/ChromeSettings.java) - -[FirefoxSettings.java](./src/main/java/aquality/selenium/configuration/driversettings/FirefoxSettings.java) - -В настоящее время решение поддерживает загрузку файлов только в браузерах Chrome, Firefox, Safari. - -#### 3.6. ALERTS - -Класс `Browser` предоставляет методы работы с Alerts: - -``` -AqualityServices.getBrowser().handleAlert(AlertActions.ACCEPT); -``` - -Больше примеров использования можно найти здесь [AlertTests.java](./src/test/java/tests/integration/AlertTests.java). - -#### 3.7. SCREENSHOTS - -Для получения снимков экрана класс Browser предоставляет метод -``` -AqualityServices.getBrowser().getScreenshot() -``` - -Более подробный пример использования смотрите в тесте [testShouldBePossibleToMakeScreenshot](./src/test/java/tests/integration/BrowserTests.java) - -### **4. ELEMENTS** - -Когда Browser инициализирован и осуществлен переход на требуемую страницу можно начинать работу с элементами этой страницы. - -#### 4.1. ELEMENT FACTORY - -Решение включает класс [ElementFactory](./src/main/java/aquality/selenium/elements/ElementFactory.java), который отвечает за создание элемента необходимого типа. Ниже приводится пример получения ITextBox: - -``` -IElementFactory elementFactory = AqualityServices.getElementFactory(); -ITextBox txbUsername = elementFactory.getTextBox(By.id("username"), "Username"); -``` -`ElementFactory` способна создавать объекты любых классов, реализующих интерфейс `IElement`. -`ElementFactory` содержит ряд методов, которые возвращают реализации `IElement`, имеющиеся по умолчанию в решении (`IButton`, `ITextBox`, `ICheckbox` и т.д.). Обратите внимание, что работа с элементами ведется через интерфейсы, чтобы пользователь обращал внимание только на функциональность, но не на реализацию. - -#### 4.2. CUSTOM ELEMENTS - -Пользователь имеет возможность создать свой элемент или расширить имеющийся по умолчанию. Для этих целей `ElementFactory` предоставляет метод ` T getCustomElement`. Достаточно или реализовать `IElement` интерфейс или расширить имеющийся класс элемента. С примером расширения и последующего использования можно ознакомиться в классе [CustomElementTests](./src/test/java/tests/usecases/CustomElementTests.java). - -#### 4.3. LIST OF ELEMENTS - -Для получения списка элементов `ElementFactory` предоставляет метод `findElements`, использование которого демонстрируется ниже - -``` -List checkBoxes = elementFactory.findElements(By.xpath(checkboxLocator), ElementType.CHECKBOX); -``` - -С другими примерами работы с `ElementFactory` и элементами можно здесь [ElementTests.java](./src/test/java/tests/integration/ElementTests.java). - - -#### 4.4. STATES OF ELEMENTS - -При работе с элементами страницы в зависимости от задачи как правило ожидается либо только нахождение элемента который виден на странице (displayed), либо который хотя бы присутствует в верстке (exists in any state). - -Для получения и последующей работы с данными двумя типами элементов `ElementFactory` предоставляет перегруженные методы получения элементов. Например, - -``` -elementFactory.getLink(By.id("redirect"), "Link", ElementState.DISPLAYED); -``` - -При работе с элементами частой является ситуация проверки состояния элемента или ожидание желаемого состояния. -Данная функциональность реализуется посредством класса [ElementStateProvider](./src/main/java/aquality/selenium/elements/ElementStateProvider.java) -Доступ к экземпляру этого класса можно получить посредством вызова метода `state()` у элемента: -``` -getTxbInput().state().waitForEnabled(); -getTxbInput().state().isDisplayed(); -``` -Больше примеров можно увидеть в классе [ElementStateTests](./src/test/java/tests/integration/ElementStateTests.java). - -### **5. FORMS** - -Основное назначение решения - помощь в автоматизации тестирования Web приложений. Существует практика автоматизации с использованием подхода [Page Objects](https://github.com/SeleniumHQ/selenium/wiki/PageObjects). Для поддержания и расширения данного подхода решение предлагает к использованию класс [Form](./src/main/java/aquality/selenium/forms/Form.java), который может служить родительским классом для всех описываемых страниц и форм приложения. Пример использования: -``` -public class SliderForm extends Form { - public SliderForm() { - super(By.id("slider_row"), "Slider"); - } -} -``` -Здесь id = "slider\_row" устанавливает локатор, который будет использован при проверке открытия страницы/формы, используя метод `isFormDisplayed()` класса [Form](./src/main/java/aquality/selenium/forms/Form.java). - -Пример теста с использованием Page Objects здесь [ShoppingCartTest.java](./src/test/java/tests/usecases/ShoppingCartTest.java). - - -### **6. JAVASCRIPT EXECUTION** - -При необходимости выполнить какой либо JavaScript на открытой странице можно воспользоваться методом -``` -browser.executeScript(final String script, Object... arguments). -``` - -Решение содержит достаточное количество наиболее используемых скриптов при выполнении автоматизации тестирования. Список скриптов представлен перечислением JavaScript. Сами скрипты расположены в директории ресурсов /src/main/resources/js. -Примеры использования метода имеются в классе [BrowserTests](./src/test/java/tests/integration/BrowserTests.java). - -Также существует перегрузка для передачи файла с JavaScript. - -### **7. JSON FILE** - -Aquality Selenium использует для своей работы и предоставляет доступ к классу [JsonSettingsFile](https://github.com/aquality-automation/aquality-selenium-core-java/blob/master/src/main/java/aquality/selenium/core/utilities/JsonSettingsFile.java). -Данный класс предоставляет удобные методы для работы с JSON файлами вашего проекта. -Например, если вы захотите хранить URL сайта с которым вы работаете как параметр конфигурации вы сможете считывать значения из JSON при помощи указанного класса: -``` -ISettingsFile environment = new JsonSettingsFile("settings.json") -String url = environment.getValue("/url").toString(); -``` - -### **8. CONDITIONAL WAIT** - -В случае необходимости ожидания выполнения какого-либо условия можно воспользоваться предоставляемым в Aquality Selenium классом [ConditionalWait](https://github.com/aquality-automation/aquality-selenium-core-java/blob/master/src/main/java/aquality/selenium/core/waitings/ConditionalWait.java). -```java -File fileDownloaded = new File(downloadDirInitialized + fileName); -AqualityServices.getConditionalWait().waitForTrue(() -> fileDownloaded.exists(), - Duration.ofSeconds(120), Duration.ofMillis(300), "File should be downloaded"); -``` -Все методы класса ждут выполнения условия, но по разному возвращают значения и обрабатывают ошибки: -1. waitForTrue - выкидывает ошибку в случае, если условие не выполнилось, ничего не возвращает. -2. boolean waitFor - возвращает true если условие выполнилось или false если не выполнилось, ошибок не выбрасывает. -3. T waitFor - использует ожидание WebDriver'a, возвращает объект T или ошибку, в случае если условие не выполнилось. diff --git a/README.md b/README.md index 776e320..2f13860 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ [![Build Status](https://dev.azure.com/aquality-automation/aquality-automation/_apis/build/status/aquality-automation.aquality-selenium-java?branchName=master)](https://dev.azure.com/aquality-automation/aquality-automation/_build/latest?definitionId=2&branchName=master) [![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=aquality-automation_aquality-selenium-java&metric=alert_status)](https://sonarcloud.io/dashboard?id=aquality-automation_aquality-selenium-java) +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.aquality-automation/aquality-selenium/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.aquality-automation/aquality-selenium) ### Overview @@ -18,7 +19,7 @@ We use interfaces where is possible, so you can implement your own version of ta com.github.aquality-automation aquality-selenium - 2.0.2 + LATEST ``` @@ -55,5 +56,5 @@ See full example [here](./src/test/java/tests/usecases/QuickStartExample.java) ### Documentation To get more details please look at documentation: -- [In English](./Documentation.en.md) -- [In Russian](./Documentation.ru.md) +- [In English](https://github.com/aquality-automation/aquality-selenium-java/wiki/Overview-(English)) +- [In Russian](https://github.com/aquality-automation/aquality-selenium-java/wiki/Overview-(Russian)) diff --git a/README_InternetExplorer.md b/README_InternetExplorer.md deleted file mode 100644 index 28f7672..0000000 --- a/README_InternetExplorer.md +++ /dev/null @@ -1,22 +0,0 @@ -IE requirements to start and use browser via selenium webdriver: - -1. In IE Internet options -> Security, all Zones (Internet - Local - Trusted) must have the same protection level. -Also Enable Protected Mode must be set to the same value (enabled or disabled) for all zones. - -2. For IE 11 only, you will need to set a registry entry on the target computer so that -the driver can maintain a connection to the instance of Internet Explorer it creates. -For 32-bit Windows installations, the key you must examine in the registry editor is -HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_BFCACHE. -For 64-bit Windows installations, the key is HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Internet -Explorer\Main\FeatureControl\FEATURE_BFCACHE. Please note that the FEATURE_BFCACHE -subkey may or may not be present, and should be created if it is not present. Important: -Inside this key, create a DWORD value named iexplore.exe with the value of 0. - -Here you need to specify DWORD value named iexplore.exe with the value of 0 has to -be set both for 64bit and 32 bit Windows. - -3. If you see the warning message like this: "WARNING: Could not open/create prefs root node Software\JavaSoft\Prefs at root 0x80000002. Windows RegCreateKeyEx(...) returned error code 5." -You may have to create a key named "Prefs" at registry path HKEY_LOCAL_MACHINE\Software\JavaSoft and/or HKEY_LOCAL_MACHINE\Software\WOW6432Node\JavaSoft - -4. In some cases popup for saving password can disturb test execution. We recommended to disable it. -You can do this via Internet options -> Content -> Settings (in the AutoComplete section) -> uncheck the "Ask me before saving passwords" and "User names and passwords on forms" \ No newline at end of file