Merge branch 'master' into angular_rework_development

.github/workflows/main.yml

@@ -33,12 +33,13 @@ env:
 
 on:
   push:
+    paths-ignore: [ '*.md' ]
     branches:
       - master
   pull_request:
+    paths-ignore: [ '*.md' ]
     branches:
       - master
-  page_build:
   release:
     types: # This configuration does not affect the page_build event above
       - created

Documents/element_design.md

@@ -0,0 +1,83 @@
+Designing a UI element for a test automation framework like JDI-Light involves several steps to ensure the element is reusable, robust, and integrates well with the existing framework:
+
+### 1: Identify the Element
+- **<span style="color:red;">Main question:</span>** Imagine, that you have this element in your project site, what should be testable for it? How would you implement it, what kind of functionality you always looking for?
+- **Research:** Understand the UI component you want to design. For a material UI design, you might be looking at elements like buttons, cards, dialogs, sliders, etc. Use the JDI-Light, Bootstrap or Material Design guidelines as a reference.
+    - [JDI-Light](https://jdi-docs.github.io/jdi-light/?java#theory)
+    - [Bootstrap](https://getbootstrap.com/docs/5.3/components/) 
+    - [Material 2](https://m2.material.io/components?platform=web)
+    - [Material 3](https://m3.material.io/components?platform=web)
+
+- **Requirement Analysis:** Determine the functionalities and states this element can have. For instance, a button may have different states like hover, disabled, or pressed. For this step it is also good to use Material Design guidelines referencesd above.
+
+### 2: Define the Interface
+- **List Properties:** Decide on the properties your element should expose. For a button, properties could include text, color, size, and state.
+- **Define Methods:** Outline the actions you can perform with the element, e.g., click, getText, isEnabled.
+- **Consider Events:** Think about what events the element should respond to, e.g., onClick, onFocus.
+- **Examples:** Good example you can see in [interface IsText](https://github.com/jdi-testing/jdi-light/blob/master/jdi-light-selenium3/src/main/java/com/epam/jdi/light/elements/interfaces/common/IsText.java) More examples you can [see here](https://github.com/jdi-testing/jdi-light/tree/master/jdi-light-selenium3/src/main/java/com/epam/jdi/light/elements/interfaces/base) eg. (Interfaces introduces all abovementioned approches):
+    - HasCheck
+    - HasClick
+    - HasLabel
+    - HasPlaceholder
+    - HasUIList
+    - HasValue
+    - IClickable etc.
+
+
+### 3: Consider Inheritance and Abstraction
+- **Base Classes:** Look for any existing elements in JDI-Light that are similar and can act as base classes. This helps in reusing code and keeping the design DRY (Don't Repeat Yourself).
+Good candidates for base classes - members of [following folder](https://github.com/jdi-testing/jdi-light/tree/master/jdi-light-html/src/main/java/com/epam/jdi/light/ui/html/elements/common) eg.:
+    - Button
+    - Checkbox
+    - Image
+    - Icon etc.
+
+- **Abstract Elements:** If needed, design an abstract class that holds common properties and methods for a category of elements. For example, all form controls might share certain behaviors.
+Examples for abstraction - look at the similarity of different elements and incorporate them in to an abstract class, have a look on a [Progress bar implementation](https://github.com/jdi-testing/jdi-light/blob/master/jdi-light-material-ui/src/main/java/com/epam/jdi/light/material/elements/feedback/progress/Progress.java). Following is more good candidates for abstraction: 
+    - Table 
+    - Bar
+    - List
+
+
+### 4: Incorporate Element Locators
+- **Locators:** Define how the element will be located in the DOM. Choose the most stable locators to ensure reliable tests.
+- **Methods for Locators:** Decide how the element can change its locators if needed, to make the custom element flexible and reusable in different contexts.
+- **NB** ***When using XPath locators***, it's essential to be mindful of their scope within the DOM. By default, an XPath expression is evaluated in the context of the entire document, which can lead to selecting unintended elements if the DOM contains multiple elements that match the given expression. To constrain the search to just the descendants of a specific root element, always start the XPath with a period (.) to indicate the current context. 
+
+### 5: Design for extensibility
+- Consider how the element can be customized or extended. Users of your framework might need to adjust the default behavior or appearance.
+- Mockups and Prototypes (please have a look inside detailes)<details> 
+        **Make visual design:** Draw a visual representation of the element to understand how it should look and behave. Use prototyping platforms like Figma, Sketch, or InVision.
+        **Create prototype:** Define example scenarios where the UI element would be used, what the expected user input and system responses would be. This can include common and edge case scenarios. Write detailed UI specifications that describe the functionality, appearance, and behavior of the element. These should include dimensions, color schemes, typographic details, and states (e.g., hover, disabled).
+    </details>
+
+### 6: Document the Design
+- **Documentation:** Write clear documentation outlining how the element is supposed to work and how it should be used within the JDI-Light framework.
+- **Examples:** Provide examples of usage including variations of the element if applicable.
+- **Javadoc** Write all documentation related to an element in a form of Javadoc inside an element class.
+- **Task for frontend** Express all abowementioned actions (in 6 and 7 steps) in a form of a task for a frontend developer in order to adjust testsite - to get element you designed on it.
+- **@JDIAction** Always use this annotation to explane actions as following:
+    - '{name}' - the name of the element on which the method is called. 
+    - {0}, {1}, ... - method parameters. 
+    - If the parameter type is Matcher, then do not use quotes and do not use is/has: *@JDIAction("Check that '{name}' text {0}")*
+    - Get-method -> *@JDIAction("Get ...")* 
+    - Set-method -> *@JDIAction("Set '{name}' text area as '{0}'") *
+    - Boolean method -> *@JDIAction("Get if '{name}' text area is empty")*
+    - Asserts -> *@JDIAction(value = "Assert that '{name}' text is {0}", isAssert = true)*
+
+
+### 7: Plan for Testing
+- **Testing Strategy:** Determine how you will test the custom element within the JDI-Light framework.
+- **Test Cases:** Outline test cases to cover all functionalities and states of the element. Keep in mind that you need to represent all features of your element.
+
+
+### Notes:
+- Make sure that locators you using in a framework is not implementation-specific. You must use locators which will not change on a different web-site implementation. If you are unable to present your element w/o usage implementation-specific locator - create a custom element inside a test project and use it in test.
+- If you are implementing an element that may contain any kind of elements - just implement it as a container and then in a test project make custom elements - to show how to work with it.
+- Consider naming conventions that match the JDI-Light framework to maintain coherence and reduce the learning curve for users of your custom library. Have a look on already implemented [classes](https://github.com/jdi-testing/jdi-light/blob/add_documentation_element_design/jdi-light-material-ui/src/main/java/com/epam/jdi/light/material/elements/displaydata/Badge.java) and [tests](https://github.com/jdi-testing/jdi-light/blob/add_documentation_element_design/jdi-light-material-ui-tests/src/test/java/io/github/epam/material/tests/displaydata/BadgeTests.java) Project has checkstyle enabled you may have a look on [rules](https://github.com/jdi-testing/jdi-light/blob/add_documentation_element_design/config/checkstyle/checkstyle.xml).<details>
+    - **Do note use UIElement when you can use typed one** (like UIElement button)
+    - **Use meaningful and descriptive names**: The method name should clearly state what the method does. For example, a method that checks if a container is fixed could be named `isFixed()`.
+    - **Start boolean methods with is, has, can, or similar**: If a method returns a boolean, it's often a good idea to start the name with `is`, `has`, `can`, or similar to make it clear that the method returns a boolean. For example, `isFixed()`, `hasTitle()`.
+    - **Use verbs for methods that perform actions**: If a method performs an action, it's often a good idea to start the name with a verb. For example, `scrollDown()`.
+    - **Keep it short**: While descriptive names are good, overly long names can make the code harder to read. Try to keep the method names concise.
+</details>

Documents/start_contribution.md

@@ -0,0 +1,137 @@
+# Contributing to JDI Light
+
+## 1: Setting Up the Repository for Contribution
+If you already have write access to the repository or do not need to create a personal fork for contribution, you can directly clone the repository to your local machine: 
+``` bash
+git clone https://github.com/jdi-testing/jdi-light.git
+```
+If you don't have write access, then first fork the repository to your own GitHub account by clicking the "Fork" button on the repository page. This creates a personal copy of the repository where you can make changes without affecting the original project. Next, clone your forked repository to your local machine using the command:
+
+``` bash
+git clone https://github.com/YOUR_USERNAME/jdi-light.git
+```
+
+Replace YOUR_USERNAME with your GitHub username. This step prepares your local development environment for making contributions.
+
+Insead cloning repo in a terminal you can do that by opening a project from IDE here an examples for different IDEs:
+
+- IntelliJ IDEA:
+    - If you see the Welcome screen, click on "Get from VCS".
+    - If you have already opened a project, select "File" > "New" > "Project from Version Control..." from the main menu.
+- Visual Studio Code:
+    - If you see the Welcome screen, click on "Clone Git repository".
+    - If you have already opened a project, press ctr+shift+G or select Source control in a left menu and push "Clone repository"
+
+
+## 2: Understand the project structure 
+
+Core methods and classes are resides in a jdi-light/jdi-light-core folder
+
+Project contains multiple folders like:
+- **.github/workflows** - in this folder you can find github actions description triggers on merging branches.
+- Core methods and classes are resides in a **jdi-light/jdi-light-core** folder.
+- **jdi-light-XXXX** - Contains the JDI Light specific module targets specific kind of testing or element base. You can see dependencies betveen modules in pom.xml for each module.
+- **jdi-light-XXXX-tests** - Holds tests for the abovementioned specific module. 
+- **jdi-light-XXXX-tests/src/test/resources** - holds variouce property files for example, the chrome.properties file is used to configure the Chrome driver, and the ff.properties file is used to configure the Firefox driver. 
+
+### Browser and test settings
+
+The test.properties file is a general configuration file that contains various settings for the tests, such as the base URL for the tests, the driver to use, and other settings. Make sure to understand and update these files as necessary for your specific setup.
+- test.properties - with this file you can fine tune a framework for your needs eg:
+
+> driver — we can specify the driver used to run our tests. Common options include chrome, firefox, ie; we can also just put ${driver} here and read the driver name from the command line.
+driver.version — by default, JDI Light will download the latest version of a driver for us, but if we need a specific version we can put it here (in which case the framework will find and download exactly this version). <span style="color:darkblue">➡️ **[see to find more about a configuration following](https://jdi-docs.github.io/jdi-light/?java#configuration)**</span> 
+
+- chrome.properties also have some specific parametres to run browser:
+``` bash
+#arguments=--ignore-certificate-errors --start-maximized --incognito
+#enableVNC=true
+```
+
+**NOTE: by default browser shall be set in headless mode - in order to run ptoperly on CI!** However for the local usage you may set it in a non-headless mode, you just need configure both common.properties and test.properties:
+- common.properties just comment:
+``` bash
+ #arguments=--headless
+```
+- test.properties set up:
+``` bash
+headless=false
+``` 
+
+
+## 3: Build the Project 
+
+Check your java version - you need atleast 11 java to run it 
+NOTE: current jdi-light version is not support Java greater than 21 yet, due to AspectJ usage.
+**(check /jdi-light/.github/workflows/main.yml - to find all compatible versions)**
+``` bash
+java --version
+```
+
+The JDI Light project uses Maven to build the project. You can build the project with the following command: 
+``` bash
+mvn -ntp install -DskipTests -Dsource.skip -Dmaven.source.skip -Dmaven.javadoc.skip=true 
+```
+This command tells Maven to build the project, skipping tests, source file generation, and JavaDoc generation.
+
+**If you encountering errors on this step:**
+- make sure that you have access to https://repo.maven.apache.org/maven2/ (for example you may have some 
+other default repo in your .m2/settings.xml)
+- make sure that you using a correct java version supported by Jdi-light by using **java --version** (if not - install a correct one and set it as a default before runnign a project)
+- look closely at console logs - it is always can help to find a solution
+
+## 4: Run Tests via command line
+
+To run tests you can use few following examples:
+- run all tests from jdi-light-angular-tests folder
+``` bash
+ mvn verify -ntp -Ddriver=chrome -pl com.epam.jdi:jdi-light-angular-tests
+```  
+- run all tests from jdi-light-angular-tests folder with some additional options
+``` bash 
+mvn verify -ntp -Ddriver=firefox -Dff.capabilities.path=jdi-light-vuetify-tests/src/test/resources/ff.properties -pl com.epam.jdi:jdi-light-vuetify-tests --fail-at-end
+```
+- run a specific test, you can use the mvn verify command with the -Dtest parameter followed by the name of the test class. For example, if the test class is GridListTests, you can run it like this: 
+``` bash 
+mvn verify -ntp -Ddriver=chrome -Dtest=io.github.epam.vuetify.tests.composite.FormsTests -pl com.epam.jdi:jdi-light-vuetify-tests --fail-at-end
+```
+
+## 5: Run tests in IDE 
+After you have built a project on a step 3 you may accually run tests straight from IDE (vscode or intellij IDEA) by clicking on a green triangle near a test class
+
+
+## 6: Make Your Changes Now you're ready to start contributing! 
+Make your changes to the codebase, making sure to follow any coding standards or guidelines defined by the project.
+
+## 7: Contribution flow
+
+ - Create a new branch using 
+ ``` bash 
+ git checkout -b <branch-name>
+ ```
+ Replace \<branch-name> with a descriptive name for your branch. Use references to a task.
+
+- Make your changes in the new branch. Ensure that your code adheres to the project's coding standards and guidelines.
+
+- Stage your changes using 
+``` bash 
+git add <staging-files>
+``` 
+
+- Commit your changes using 
+``` bash 
+git commit -m "<commit-message>"
+``` 
+ Replace \<commit-message> with a descriptive message about the changes you made. A good commit message is concise, uses the imperative mood, and describes what was done and why.
+
+- Push your changes to the remote repository using 
+``` bash 
+git push origin <branch-name>
+``` 
+
+- Go to the GitHub page of your forked repository and click on "Pull request".
+Choose the branch you just pushed from the "compare" dropdown.
+Review your changes and then click on "Create pull request".
+
+- After creating a pull request, the Github Actions pipeline will automatically run to check your changes.
+You can see the status of the [Actions pipeline](https://github.com/jdi-testing/jdi-light/actions) on the GitHub page of your pull request. If the job fails, click on the job link to see what went wrong and fix the issues. <span style="color:green">**Please make sure that PR pipeline is green**</span>

README.md

@@ -20,9 +20,8 @@ Project templates: https://github.com/jdi-templates - for fast projects start </
 Examples: https://github.com/jdi-examples </br>
 How to use [UI Elements examples](https://github.com/jdi-testing/jdi-light/tree/master/jdi-light-html-tests/src/test/java/io/github/epam/html/tests/elements) </br>
 Increase test [performance examples](https://github.com/jdi-testing/jdi-light/tree/master/jdi-performance) </br>
- </br>
- </br>
-
+How to start contribution [setup environment](https://github.com/jdi-testing/jdi-light/blob/master/Documents/start_contribution.md) <br/>
+How to design element [basic description](https://github.com/jdi-testing/jdi-light/blob/master/Documents/element_design.md)
 ## Introduction
 
 JDI Light – is the test Framework for UI test automation that helps to makes your tests fast and sustainable and provide obvious and predictable test run result
@@ -55,8 +54,6 @@ Example Scenario tests: https://github.com/jdi-testing/jdi-light/tree/master/jdi
 
 Site: http://jdi.epam.com/
 
-VK: https://vk.com/jdi_framework
-
 Facebook: https://www.facebook.com/groups/jdi.framework/
 
 You can ask your questions on StackOverflow with [![htmlelements](https://img.shields.io/badge/stackoverflow-jdiframework-orange.svg?style=flat)](http://stackoverflow.com/questions/tagged/jdiframework) tag

jdi-light-core/pom.xml

@@ -40,7 +40,7 @@
         <dependency>
             <groupId>org.apache.commons</groupId>
             <artifactId>commons-compress</artifactId>
-            <version>1.25.0</version>
+            <version>1.26.0</version>
         </dependency>
         <dependency>
             <groupId>com.jdiai.tools</groupId>
@@ -66,7 +66,7 @@
         <dependency>
             <groupId>io.github.bonigarcia</groupId>
             <artifactId>webdrivermanager</artifactId>
-            <version>5.6.3</version>
+            <version>5.6.4</version>
             <exclusions>
                 <exclusion>
                     <groupId>com.github.docker-java</groupId>

jdi-light-material-ui-tests/src/main/java/io/github/com/StaticSite.java

@@ -31,7 +31,6 @@
 import io.github.com.pages.inputs.SlidersPage;
 import io.github.com.pages.inputs.SwitchPage;
 import io.github.com.pages.inputs.TextFieldPage;
-import io.github.com.pages.layout.BoxPage;
 import io.github.com.pages.layout.ContainerPage;
 import io.github.com.pages.layout.GridListPage;
 import io.github.com.pages.layout.GridPage;
@@ -301,10 +300,6 @@ public class StaticSite {
     public static ContextMenuPage contextMenuPage;
 
     // layouts
-    // box
-    @Url("/box_layout")
-    public static BoxPage boxPage;
-
     // container
     @Url("/container_layout")
     public static ContainerPage containerPage;

jdi-light-material-ui-tests/src/main/java/io/github/com/custom/elements/FloatingAnimatedButtonsSection.java

@@ -8,7 +8,7 @@
 /**
  * Represents animated FAB (Floating Action Button) for multiple lateral screens (such as tabbed screens) component of MUI on GUI.
  *
- * @see <a href="https://mui.com/material-ui/react-floating-action-button/">FAB MUI documentation</a>
+ * @see <a href="https://v4.mui.com/material-ui/react-floating-action-button/">FAB MUI documentation</a>
  * @see <a href="https://jdi-testing.github.io/jdi-light/material">MUI test page</a>
  */
 public class FloatingAnimatedButtonsSection extends Section {

jdi-light-material-ui-tests/src/main/java/io/github/com/custom/elements/table/CollapsingTable.java

@@ -13,7 +13,7 @@
 /**
  * Table with inner tables in expanding rows.
  *
- * @see <a href="https://mui.com/components/tables/#collapsible-table">Mui example</a>
+ * @see <a href="https://v4.mui.com/components/tables/#collapsible-table">Mui example</a>
  * @see <a href="https://jdi-testing.github.io/jdi-light/material/simple_table">Test page</a>
  */
 public class CollapsingTable extends Table {

jdi-light-material-ui-tests/src/main/java/io/github/com/custom/elements/table/TableWithFilters.java

@@ -16,7 +16,7 @@
  *
  * @param <L> inherited from super class {@link DataTable}
  * @param <D> inherited from super class {@link DataTable}
- * @see <a href="https://mui.com/components/tables/#data-table">Mui example</a>
+ * @see <a href="https://v4.mui.com/components/tables/#data-table">Mui example</a>
  * @see <a href="https://jdi-testing.github.io/jdi-light/material/simple_table">Test page</a>
  */
 public class TableWithFilters<L extends PageObject, D> extends DataTable<L, D> {