E2E autotests for censhare Web UI

This is the Selenium test framework for executing automated UI tests written in Java. This project allows you to run tests and create fancy reports including descriptions of executed steps and screenshots that give you detailed overview of what is going on inside the test and what went wrong.

Prerequisites

Java 8
maven
recommended - IntelliJ IDEA Community Edition

Access

You can access the project through gitlab.censhare.com. You can find our tests with needed branches here: https://gitlab.censhare.com/censhare/censhare-ui-tests or https://gitlab-ext.censhare.com/censhare/censhare-ui-tests (for partners).

Easy (guided) test run

You can easily run tests by using sh scripts. This will set up the needed tools, run tests and generate reports. The script will guide you and answer some of your questions. To run the script, simply type the next command in your terminal from the project directory:

Download censhare ui test framework and open folder

git clone https://git.censhare.com/test-automation/client5-ui-test.git

cd client5-ui-tests

Run guided test run
```
sh ./guided-run.sh
```
Guided test-run lets you run tests without any additional efforts and deep understanding of Java or automation in general. guided-run.sh will show the available actions and will ask what to do next. For people with experience in Java the next block is helpful - Project structure, which contains detailed descriptions of the test framework, configuration, test run and test template.

Project structure

Below here is the structure of the project:

src.test.java.com.censhare.web.ui
- config
- dialogs
- explorer
- forms
- internal
  - exceptions
  - extentions
    - TestConfigurationExtension class
    - TestRunnerExtension class
  - handlers
  - junit
- pages
- panels
- rows
- tabs
- tests
  - BaseTest
- widgets
src/test/resources
- files/uploads
- allure.properties
- junit-platform.properties
- config.properties

Tests

All UI tests are stored in the folder with the following path src/test/java/com/censhare/web/ui/tests. In this folder, you find BaseTest, which contains common config for all tests. So each UI test must extend BaseTest.

BaseTest

BaseTest itself contains the initialization SoftAssertions object which is needed for asserting multiple results without throwing an exception when an assertion fails and continues with the next step after an assert statement. BaseTest is extended by 2 other configuration classes: TestConfigurationExtension and TestRunnerExtension.

TestConfigurationExtension class

TestConfigurationExtension class in its @BeforeEach annotation calls the methods mentioned below:

setUpConfiguration() method which sets the following configuration properties: baseUrl, timeout and different browser settings (For example, which browser to use, wether to run the browser locally or remotely and other browser capabilities). All these properties are taken from the config.properties file that can be found by the following path: src/test/resources/config.properties.
loginToTheSystem(context) method performing the login to the system. By default, the login is done with censhare Defaultuser (this setting is set in config.properties file). If the annotation @LoginAs(user = "SOME_USER") is called right before the test/test suite, then the login will be done with the appropriate user.
createAsset(context). If the annotation @CreateAsset(assetType = "SOME_TYPE", assetName = "SOME_NAME") is called right before the test/test suite, the asset with the appropriate type and name will be created. If the annotation @CreateAsset is called without type and name, then the asset with type MARKER and autogenerated name will be created. If thhe annotation isn't called at all, then no asset is created.

Additionally, the annotation @CreateAssets(numberOfAssets = 2, assetName = "SOME_NAME", assetTypes = "SOME_TYPE") can be called right before the test/test suite that will create the needed number of appropriate assets with the provided name.

TestRunnerExtension class

TestRunnerExtension class contains the configuration for making and saving screenshots and videos of running tests.

Config

The config folder contains 3 classes: Config, DefaultConfig and GlobalConfig which are needed for getting and setting variables from config.properties file.

Dialogs

The dialogs folder contains the folder createAssetConfiguration with 2 classes: BaseDialog and CreateAssetTab that store methods for working with the Create Asset dialog and its configuration.

Explorer

The explorer folder contains classes which allow you to work with Explorer page (for example, filter results by text, by some filter, clear filters, etc.)

Forms

The forms folder stores the tabs folder which contains classes for working with different kind of forms suc as: Asset creation form, Asset relation form, Detailed search form and many others. Also, there is the hierarchy of subfolders tabs/profile/preferences/general containing classes that work with user profile preferences.

Internal

The internal folder contains lots of subfoldes and separate classes:

exceptions folder with CheckboxNameNotSpecifiedException class creating a custom exception in case a checkbox name isn't specified.
extentions folder has the annotations subfolder that stores interfaces for creating assets, login, file upload and browser properties. Also, there are 2 enums for AssetTypes and Bowsers collecting all possible asset types and browsers accordingly. Test context class keeps thread-local variables such as id, name, type of the assets created during test execution, userName, userPass, etc. See above for descriptions of the classes TestConfigurationExtension and TestRunnerExtension.
handlers folder with CheckboxHandler and NotificationHandler classes is in charge of handling checkboxes and popping up notifications accordingly.
junit folder is provided for rerunner needs, it finds out failing tests after test runs and reruns them (deprecated).
AssetCollection, ProductCollection and WidgetCollection classes work with collections of assets/products/widgets accordingly, they have methods for getting the list of all assets/products/widgets, find entities by name, select entities from the list by number, etc.
Checkbox class can check a particular checkbox and verify if it is checked or not.
ColorConverter class has methods for converting color names to hex and style and opposite.
GalleryViewSize, ComparisonOperators and View enums collect all the possible values of gallery view sizes and views te existing ones in the project as well as possible comparison operators accordingly.
MassDataHandler class is designed for working with metadata fields of large numbers of assets.
OSInfo class gets the info about the OS installed.
SavedSearchFormData class is responsible for working with Saved searches, it can set the name, domain, and share the search with a particular role, etc.
UserPreferencesValue class can get current value of any user preference and change it.

Pages

The pages folder contains classes describing all the pages of an application including web elements and methods working with these elements.

Panels

The panels folder stores the classes with descriptions of the panels of the application.

Rows

The rows folder is responsible for storing classes working with different rows such as filter row, metadata row, and tab row.

Tabs

The tabs folder has classes that are in charge of different kinds of tabs such as User Preferences tabs and Flatplan Editor tab.

Widgets

The widgets folder keeps classes describing and working with widgets all over the application.

Resources

The Resources folder is used to store all project resources files such as XML files, images, text files, etc. The path for it is the following: src/test/resources. The organization of the resources folder is as follows:

files/uploads folder stores the images and files needed for tests with file upload.
allure.prpperties file is an Allure configuration file which states where the allure-results directory should be placed and sets patterns for @TmsLink and @Issue links.
junit-platform.properties defines how to run the tests (concurrent execution, parallelism).
config.properties file stores the configurable parameters of an application such as against which environment to run the tests and which browser to use.

Configuration file

The configuration file can be found by the following path: src/test/resources/config.properties.

UI user and password block - set user and password for UI authorization.

default-user-name - user for ui auth. Param - String
default-user-pass - password for ui auth. Param - String

URLs block - 3 urls in which you should set or uncomment needed URLs.

browser-base-url - Set UI url for authorization and ui tests. Param - String

UI remote block - enable or disable running browser remotely with selenoid

browser-timeout - set webDriver timeout for element wait. Param - Integer
browser-name - browser name (chrome, opera, firefox). Param - String
browser-remote-url - link where to run browser. Param - String
browser-version browser version (chrome/opera/firefox) Param - Integer
browser-enable-remote - 'false' to run browser locally and 'true' to run on prepared remote pc. Param - Boolean
browser-enable-vnc - turn on/off VNC to view browser http://${ui-webdriver-url}:8080 Param - String
browser-enable-video -Enable video recording for UI tests which will be attached to allure report. Param - Boolean
browser-window-width - set the width of the browser window. Param - Integer
browser-window-height - set the height of the browser window. Param - Integer
driver-headless-mode - run browser in headless mode. Param - Boolean

How-to

1. Run tests

All tests with maven command

Open the project directory or open a terminal in IDEA.
Run all tests with next maven command:

mvn clean test

One or few tests with maven command

Open IDEA and this project in it.
Open the tests class that you want to run.
Right-click on test (method name) and select Copy Reference.
Open a terminal in IDEA.
Write maven command mvn clean test -Dtest= and paste copied reference (⌘ + V)

 mvn clean test -Dtest =com.censhare.web.ui.tests.AssetCreationTest#createNewAssetTest

In case you want to run 2 or more tests, put the references with comma separator. Example:

mvn clean test -Dtest=com.censhare.web.ui.tests.AssetCreationTest#createNewAssetTest,com.censhare.web.ui.tests.TrashTest

Run from IDEA

Open the test that you want to run.
Click the Play button on the left side-panel on the same line as the test method name.
Select Run.

To run few tests, select the needed classes, right-click and select Run.

Debug tests in IDEA

Open the method that you want to debug.
Click on the status bar with numbers in line where we need to stop
Go to test and click the Play button on the left side-panel on same line as the test method name.
Select Debug.

2. Write tests

Directly in a folder with all tests, there is TestTemplate.java class (the path to it is the following src/test/java/com/censhare/web/ui/tests/TestTemplate.java). This class is the example of how your test should look like and you can use it as a template (copy and paste it, set a new class name and delete unused links):

@Feature("")
@Story("")
@Tag("")
@DisplayName("")
//IMPORTANT - class (test) name should end on "Test" word, e.g. "AssetTest"
public class TestTemplate extends BaseTest {

    @Test
    @DisplayName("")
    @Description("")
    @TmsLink("")
    @Issue("")
    @Severity(NORMAL)
    @Tag("")
    @CreateAsset(assetType = TEXT)
    @LoginAs(user = "customUser", password = "password")
    public void test() {
        /**
        * Body of the test
        */

        // add assertions
        softly.assertThat("First variable")
                .as("Assertion description")
                .isEqualTo("Second variable");
    }

}

Test structure

The test suite(executable java class) must contain the following:

A title that ends with "Test", e.g. "AssetTest".
Each test class must extend BaseTest because all the configs how and where to run tests are stored here.
@DisplayName("") annotation which is used to declare a custom display name for the annotated test class or test method. Display names are used for test reporting and may contain spaces, special characters, and even emoji.

The test suite(executable java class) can contain the following:

@Feature("") and Story("") annotations that help to classify test classes by Features and Stories.
@Tag("") annotation. This is a repeatable annotation that is used to declare a tag for the annotated test class or test method. Tags are used to filter which tests are executed for a given test plan.

The test(test method) must contain the following:

@Test annotation which is a JUnit annotation that indicates a test function. Add this annotation before each of your test cases.
Test name with public access modifier and return void type. The name should start with lower case and reflect exactly what the test method tests.
Assertion. In our Test framework we use softly object of SoftAssertion class which takes 3 arguments:
- Expected value
- Feedback message to be shown if values are not equal
- Actual value
@DisplayName("") annotation which is used to declare a custom display name for the annotated test class or test method. Display names are used for test reporting and may contain spaces, special characters, and even emoji.
@Description annotation that allows you to add detailed description for each test method.

The test(test method) can contain the following:

@TmsLink("") and @Issue("") annotations giving you the possibility to link your tests to some resources such as TMS (test management system).
@Severity(NORMAL) annotation that is used in order to prioritize test methods by severity.
@Tag("") annotation. This is a repeatable annotation that is used to declare a tag for the annotated test class or test method. Tags are used to filter which tests are executed for a given test plan.
@CreateAsset(assetType = TEXT) annotation. If annotation @CreateAsset(assetType = "SOME_TYPE", assetName = "SOME_NAME") is called right before the test/test suite the asset with the appropriate type and name will be created. If annotation @CreateAsset is called without type and name then the asset with type MARKER and autogenerated name will be created. If annotation isn't called at all then no asset will be created.
Additionally, the annotation @CreateAssets(numberOfAssets = 2, assetName = "SOME_NAME", assetTypes = "SOME_TYPE") can be called right before the test/test suite that will create the needed number of appropriate assets with provided name.

@LoginAs(user = "customUser", password = "password") annotation. This is a custom annotation performing the login to the system. By default, the login is done with censhare Defaultuser (this setting is set in config.properties file). If annotation @LoginAs(user = "SOME_USER", password = "SOME_PASSWORD") is called right before the test/test suite, then the login will be done with the appropriate user.

Page tree