Introduce some small improvements here and there

EPadronU · Aug 13, 2024 · 09fff82 · 09fff82
1 parent a40ba76
commit 09fff82
Show file tree

Hide file tree

Showing 59 changed files with 220 additions and 182 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,9 +1,17 @@
+# Ignore Allure Commandline files and directories
 .allure/
+
+# Ignore IntelliJ IDEA project files and directories
 .idea/
+
+# Ignore Eclipse project settings
 .settings/
+
+# Ignore build output directories for Gradle and Maven
 build/
 target/
 
+# Ignore Eclipse project files
 .classpath
 .factorypath
-.project
+.project
diff --git a/README.md b/README.md
@@ -2,16 +2,22 @@
 
 [![license](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)
 
+
+## About the project
+
 Dwalin is a web-automation library for Java. It's a [Selenide](https://selenide.org) /
 [Selenium-WebDriver](https://www.selenium.dev/documentation/webdriver) wrapper inspired by
 [Geb](https://www.gebish.org) and its elder brother
 [Balin](https://github.com/EPadronU/balin).
 
-Contrary to a framework, Dwalin is **lightweight** and **non-opinionated**. Additionally, it
-supports the usage of the [Page Component Object Model](https://gorillalogic.com/blog/test-automation-frameworks-page-object-model-vs-page-component-object-model)
-design pattern, an extension of the well-known [<abbr title="Page Object Model">POM</abbr>](https://www.guru99.com/page-object-model-pom-page-factory-in-selenium-ultimate-guide.html)
+Contrary to a framework, Dwalin is **lightweight** and **non-opinionated**. Additionally, its
+supports the usage of the
+[Page Component Object Model](https://gorillalogic.com/blog/test-automation-frameworks-page-object-model-vs-page-component-object-model)
+design pattern, an extension of the well-known
+[<abbr title="Page Object Model">POM</abbr>](https://www.guru99.com/page-object-model-pom-page-factory-in-selenium-ultimate-guide.html)
 design pattern.
 
+
 ## Rationale
 
 Geb, written in Groovy, is a fantastic library that lets users harness the power of the
@@ -21,6 +27,7 @@ working with both tools. This inspired me to create a smoother experience, leadi
 development of Balin in Kotlin a few years ago. Now, with Dwalin, I'm excited to bring what I've
 learned from Balin into the Java world.
 
+
 ## Usage
 
 [Sample tests](./src/test/java/com/github/epadronu/dwalin/SampleTests.java)
@@ -36,7 +43,7 @@ TODO
 - [Java API](https://epadronu.github.io/dwalin/apidocs/index.html)
 
 
-## Build system & framework integrations
+## Using the library in your project
 
 ### Maven
 
@@ -51,11 +58,11 @@ TODO
 ```
 
 
-## Note
+## Notes
 
 This project has been conceived as a hobby and for personal use. Nonetheless, I don't dismiss the
 possibility of making it a production-ready library if it gets to that point.
 
 ## License
 
-Like Balin, _Dwalin_ is released under version 2.0 of the [Apache License](LICENSE).
+Like Balin, Dwalin is released under version 2.0 of the [Apache License](LICENSE).
diff --git a/docs/apidocs/allclasses-index.html b/docs/apidocs/allclasses-index.html
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML>
 <html lang>
 <head>
-<!-- Generated by javadoc (22) on Tue Aug 13 06:56:25 COT 2024 -->
+<!-- Generated by javadoc (22) on Tue Aug 13 08:42:23 COT 2024 -->
 <title>All Classes and Interfaces (Dwalin 1.0-SNAPSHOT API)</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
@@ -64,18 +64,19 @@ <h1 title="All Classes and Interfaces" class="title">All Classes and Interfaces<
 <div class="col-first odd-row-color all-classes-table all-classes-table-tab2"><a href="com/github/epadronu/dwalin/core/Component.html" title="class in com.github.epadronu.dwalin.core">Component&lt;P&gt;</a></div>
 <div class="col-last odd-row-color all-classes-table all-classes-table-tab2">
 <div class="block">
- Models a reusable interface component that can appear multiple times across one or more pages or components.</div>
+ Describes a reusable interface component that can appear multiple times across one or more pages or components.</div>
 </div>
 <div class="col-first even-row-color all-classes-table all-classes-table-tab2"><a href="com/github/epadronu/dwalin/core/Dwalin.html" title="class in com.github.epadronu.dwalin.core">Dwalin</a></div>
 <div class="col-last even-row-color all-classes-table all-classes-table-tab2">
 <div class="block">
- Provides methods for navigating to pages that extends the <code>NavigablePage</code> interface.</div>
+ Provides a set of utility methods for navigating to pages that implement the <code>NavigablePage</code> interface,
+ along with other useful functionality for test automation.</div>
 </div>
 <div class="col-first odd-row-color all-classes-table all-classes-table-tab2"><a href="com/github/epadronu/dwalin/utils/selenide/DwalinAllureSelenide.html" title="class in com.github.epadronu.dwalin.utils.selenide">DwalinAllureSelenide</a></div>
 <div class="col-last odd-row-color all-classes-table all-classes-table-tab2">
 <div class="block">
  Extends the functionality of <code>AllureSelenide</code> by automatically
- attaching screenshots for very step (if desired).</div>
+ attaching screenshots for every step (if enabled).</div>
 </div>
 <div class="col-first even-row-color all-classes-table all-classes-table-tab2"><a href="com/github/epadronu/dwalin/qa/DwalinTest.html" title="class in com.github.epadronu.dwalin.qa">DwalinTest</a></div>
 <div class="col-last even-row-color all-classes-table all-classes-table-tab2">
@@ -95,7 +96,7 @@ <h1 title="All Classes and Interfaces" class="title">All Classes and Interfaces<
 <div class="col-first odd-row-color all-classes-table all-classes-table-tab2"><a href="com/github/epadronu/dwalin/core/ElementGuard.html" title="class in com.github.epadronu.dwalin.core">ElementGuard</a></div>
 <div class="col-last odd-row-color all-classes-table all-classes-table-tab2">
 <div class="block">
- A <code>SelenideElement</code> wrapper designed for developers who prefer not to expose
+ A <code>SelenideElement</code> facade designed for developers who prefer not to expose
  <code>WebElement</code> instances or <code>WebElement</code>-like behavior in the public API of their pages.</div>
 </div>
 <div class="col-first even-row-color all-classes-table all-classes-table-tab2"><a href="com/github/epadronu/dwalin/core/GuardedComponent.html" title="class in com.github.epadronu.dwalin.core">GuardedComponent&lt;P&gt;</a></div>
@@ -107,13 +108,13 @@ <h1 title="All Classes and Interfaces" class="title">All Classes and Interfaces<
 <div class="col-first odd-row-color all-classes-table all-classes-table-tab1"><a href="com/github/epadronu/dwalin/core/NavigablePage.html" title="interface in com.github.epadronu.dwalin.core">NavigablePage</a></div>
 <div class="col-last odd-row-color all-classes-table all-classes-table-tab1">
 <div class="block">
- Models a web page that can be navigated to within a browser.</div>
+ Describes a web page that can be navigated to within a browser.</div>
 </div>
 <div class="col-first even-row-color all-classes-table all-classes-table-tab1"><a href="com/github/epadronu/dwalin/core/Page.html" title="interface in com.github.epadronu.dwalin.core">Page</a></div>
 <div class="col-last even-row-color all-classes-table all-classes-table-tab1">
 <div class="block">
- Models a web page, serving as an implementation of a page class following the Page Object Model
- pattern.</div>
+ Describes a web page, serving as the base of a page class implementation following the
+ Page Object Model pattern.</div>
 </div>
 <div class="col-first odd-row-color all-classes-table all-classes-table-tab2"><a href="com/github/epadronu/dwalin/utils/junit/PascalCaseDisplayNameGenerator.html" title="class in com.github.epadronu.dwalin.utils.junit">PascalCaseDisplayNameGenerator</a></div>
 <div class="col-last odd-row-color all-classes-table all-classes-table-tab2">

diff --git a/docs/apidocs/allpackages-index.html b/docs/apidocs/allpackages-index.html
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML>
 <html lang>
 <head>
-<!-- Generated by javadoc (22) on Tue Aug 13 06:56:25 COT 2024 -->
+<!-- Generated by javadoc (22) on Tue Aug 13 08:42:23 COT 2024 -->
 <title>All Packages (Dwalin 1.0-SNAPSHOT API)</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

diff --git a/docs/apidocs/com/github/epadronu/dwalin/core/AbstractionLayer.html b/docs/apidocs/com/github/epadronu/dwalin/core/AbstractionLayer.html
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML>
 <html lang>
 <head>
-<!-- Generated by javadoc (22) on Tue Aug 13 06:56:25 COT 2024 -->
+<!-- Generated by javadoc (22) on Tue Aug 13 08:42:23 COT 2024 -->
 <title>AbstractionLayer (Dwalin 1.0-SNAPSHOT API)</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

diff --git a/docs/apidocs/com/github/epadronu/dwalin/core/Component.html b/docs/apidocs/com/github/epadronu/dwalin/core/Component.html
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML>
 <html lang>
 <head>
-<!-- Generated by javadoc (22) on Tue Aug 13 06:56:25 COT 2024 -->
+<!-- Generated by javadoc (22) on Tue Aug 13 08:42:23 COT 2024 -->
 <title>Component (Dwalin 1.0-SNAPSHOT API)</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
@@ -91,7 +91,7 @@ <h1 title="Class Component" class="title">Class Component&lt;P extends <a href="
 <div class="horizontal-scroll">
 <dl class="notes">
 <dt>Type Parameters:</dt>
-<dd><code>P</code> - the type of parent to which this component is associated</dd>
+<dd><code>P</code> - the type of parent to which this component is associated with</dd>
 </dl>
 <dl class="notes">
 <dt>All Implemented Interfaces:</dt>
@@ -107,7 +107,7 @@ <h1 title="Class Component" class="title">Class Component&lt;P extends <a href="
 implements <a href="AbstractionLayer.html" title="interface in com.github.epadronu.dwalin.core">AbstractionLayer</a></span>
 <span class="permits">permits <a href="GuardedComponent.html" title="class in com.github.epadronu.dwalin.core">GuardedComponent</a>&lt;P&gt;, <a href="ElementComponent.html" title="class in com.github.epadronu.dwalin.core">ElementComponent</a>&lt;P&gt;</span></div>
 <div class="block"><p>
- Models a reusable interface component that can appear multiple times across one or more pages or components.
+ Describes a reusable interface component that can appear multiple times across one or more pages or components.
  </p></div>
 </div>
 </section>
@@ -152,7 +152,8 @@ <h2>Constructor Summary</h2>
  com.codeborne.selenide.SelenideElement&nbsp;rootElement)</code></div>
 <div class="col-last even-row-color">
 <div class="block">
- Constructs a new component linked to the specified parent, using the provided element as the root search context.</div>
+ Constructs a new component associated with the specified parent, using the provided element
+ as the root search context.</div>
 </div>
 </div>
 </section>
@@ -172,7 +173,7 @@ <h2>Method Summary</h2>
 <div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4"><code><a href="#ascend()" class="member-name-link">ascend</a>()</code></div>
 <div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4">
 <div class="block">
- Retrieves the parent to which this component is associated.</div>
+ Retrieves the parent to which this component is associated with.</div>
 </div>
 <div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab4"><code>&lt;Self extends <a href="Component.html" title="class in com.github.epadronu.dwalin.core">Component</a>&lt;<a href="Component.html" title="type parameter in Component">P</a>&gt;,<wbr>
 C extends <a href="Component.html" title="class in com.github.epadronu.dwalin.core">Component</a>&lt;Self&gt;&gt;<br>C</code></div>
@@ -273,7 +274,8 @@ <h3 id="&lt;init&gt;(com.github.epadronu.dwalin.core.AbstractionLayer,com.codebo
 <div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="element-name">Component</span><wbr><span class="parameters">(<a href="Component.html" title="type parameter in Component">P</a>&nbsp;parent,
  com.codeborne.selenide.SelenideElement&nbsp;rootElement)</span></div>
 <div class="block"><p>
- Constructs a new component linked to the specified parent, using the provided element as the root search context.
+ Constructs a new component associated with the specified parent, using the provided element
+ as the root search context.
  </p></div>
 <dl class="notes">
 <dt>Parameters:</dt>
@@ -301,7 +303,7 @@ <h3>ascend</h3>
 @Nonnull
 </span><span class="modifiers">public</span>&nbsp;<span class="return-type"><a href="Component.html" title="type parameter in Component">P</a></span>&nbsp;<span class="element-name">ascend</span>()</div>
 <div class="block"><p>
- Retrieves the parent to which this component is associated.
+ Retrieves the parent to which this component is associated with.
  </p>
  <p>
  It's like ascending in the composition tree.

diff --git a/docs/apidocs/com/github/epadronu/dwalin/core/Dwalin.html b/docs/apidocs/com/github/epadronu/dwalin/core/Dwalin.html
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML>
 <html lang>
 <head>
-<!-- Generated by javadoc (22) on Tue Aug 13 06:56:25 COT 2024 -->
+<!-- Generated by javadoc (22) on Tue Aug 13 08:42:23 COT 2024 -->
 <title>Dwalin (Dwalin 1.0-SNAPSHOT API)</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
@@ -93,7 +93,8 @@ <h1 title="Class Dwalin" class="title">Class Dwalin</h1>
 <div class="type-signature"><span class="modifiers">public final class </span><span class="element-name type-name-label">Dwalin</span>
 <span class="extends-implements">extends <a href="https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a></span></div>
 <div class="block"><p>
- Provides methods for navigating to pages that extends the <code>NavigablePage</code> interface.
+ Provides a set of utility methods for navigating to pages that implement the <code>NavigablePage</code> interface,
+ along with other useful functionality for test automation.
  </p></div>
 </div>
 </section>

diff --git a/docs/apidocs/com/github/epadronu/dwalin/core/ElementComponent.html b/docs/apidocs/com/github/epadronu/dwalin/core/ElementComponent.html
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML>
 <html lang>
 <head>
-<!-- Generated by javadoc (22) on Tue Aug 13 06:56:25 COT 2024 -->
+<!-- Generated by javadoc (22) on Tue Aug 13 08:42:23 COT 2024 -->
 <title>ElementComponent (Dwalin 1.0-SNAPSHOT API)</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

diff --git a/docs/apidocs/com/github/epadronu/dwalin/core/ElementGuard.html b/docs/apidocs/com/github/epadronu/dwalin/core/ElementGuard.html
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML>
 <html lang>
 <head>
-<!-- Generated by javadoc (22) on Tue Aug 13 06:56:25 COT 2024 -->
+<!-- Generated by javadoc (22) on Tue Aug 13 08:42:23 COT 2024 -->
 <title>ElementGuard (Dwalin 1.0-SNAPSHOT API)</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
@@ -98,14 +98,15 @@ <h1 title="Class ElementGuard" class="title">Class ElementGuard</h1>
 <span class="extends-implements">extends <a href="https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a>
 implements org.openqa.selenium.TakesScreenshot</span></div>
 <div class="block"><p>
- A <code>SelenideElement</code> wrapper designed for developers who prefer not to expose
+ A <code>SelenideElement</code> facade designed for developers who prefer not to expose
  <code>WebElement</code> instances or <code>WebElement</code>-like behavior in the public API of their pages.
  </p></div>
 <dl class="notes">
 <dt>See Also:</dt>
 <dd>
 <ul class="tag-list">
 <li><code>SelenideElement</code></li>
+<li><a href="GuardedComponent.html" title="class in com.github.epadronu.dwalin.core"><code>GuardedComponent</code></a></li>
 </ul>
 </dd>
 </dl>
@@ -734,6 +735,8 @@ <h3>guard</h3>
 <dd><code>element</code> - the element to be encapsulated</dd>
 <dt>Returns:</dt>
 <dd>a new <code>ElementGuard</code> that wraps the provided element</dd>
+<dt>Throws:</dt>
+<dd><code><a href="https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/NullPointerException.html" title="class or interface in java.lang" class="external-link">NullPointerException</a></code> - if <code>element</code> is <code>null</code></dd>
 </dl>
 </div>
 </section>

diff --git a/docs/apidocs/com/github/epadronu/dwalin/core/GuardedComponent.html b/docs/apidocs/com/github/epadronu/dwalin/core/GuardedComponent.html
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML>
 <html lang>
 <head>
-<!-- Generated by javadoc (22) on Tue Aug 13 06:56:25 COT 2024 -->
+<!-- Generated by javadoc (22) on Tue Aug 13 08:42:23 COT 2024 -->
 <title>GuardedComponent (Dwalin 1.0-SNAPSHOT API)</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

diff --git a/docs/apidocs/com/github/epadronu/dwalin/core/NavigablePage.html b/docs/apidocs/com/github/epadronu/dwalin/core/NavigablePage.html
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML>
 <html lang>
 <head>
-<!-- Generated by javadoc (22) on Tue Aug 13 06:56:25 COT 2024 -->
+<!-- Generated by javadoc (22) on Tue Aug 13 08:42:23 COT 2024 -->
 <title>NavigablePage (Dwalin 1.0-SNAPSHOT API)</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
@@ -94,7 +94,7 @@ <h1 title="Interface NavigablePage" class="title">Interface NavigablePage</h1>
 <div class="type-signature"><span class="modifiers">public interface </span><span class="element-name type-name-label">NavigablePage</span><span class="extends-implements">
 extends <a href="Page.html" title="interface in com.github.epadronu.dwalin.core">Page</a></span></div>
 <div class="block"><p>
- Models a web page that can be navigated to within a browser.
+ Describes a web page that can be navigated to within a browser.
  </p>
  <p>
  Provides methods to supply the URL for navigation and to verify that the correct page has been reached.
@@ -163,7 +163,7 @@ <h3>urlSupplier</h3>
  </p></div>
 <dl class="notes">
 <dt>Returns:</dt>
-<dd>a <code>Supplier&lt;String&gt;</code> that provides the URL.</dd>
+<dd>a <code>Supplier&lt;String&gt;</code> that provides the URL</dd>
 </dl>
 </div>
 </section>
@@ -178,7 +178,7 @@ <h3>atVerificationSupplier</h3>
 <div class="block">Returns a <code>Runnable</code> that performs verification to ensure the browser has navigated to the expected page.</div>
 <dl class="notes">
 <dt>Returns:</dt>
-<dd>a <code>Runnable</code> for verifying that the correct page has been reached.</dd>
+<dd>a <code>Runnable</code> for verifying that the correct page has been reached</dd>
 </dl>
 </div>
 </section>

diff --git a/docs/apidocs/com/github/epadronu/dwalin/core/Page.html b/docs/apidocs/com/github/epadronu/dwalin/core/Page.html
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML>
 <html lang>
 <head>
-<!-- Generated by javadoc (22) on Tue Aug 13 06:56:25 COT 2024 -->
+<!-- Generated by javadoc (22) on Tue Aug 13 08:42:23 COT 2024 -->
 <title>Page (Dwalin 1.0-SNAPSHOT API)</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
@@ -98,8 +98,8 @@ <h1 title="Interface Page" class="title">Interface Page</h1>
 <div class="type-signature"><span class="modifiers">public non-sealed interface </span><span class="element-name type-name-label">Page</span><span class="extends-implements">
 extends <a href="AbstractionLayer.html" title="interface in com.github.epadronu.dwalin.core">AbstractionLayer</a></span></div>
 <div class="block"><p>
- Models a web page, serving as an implementation of a page class following the Page Object Model
- pattern.
+ Describes a web page, serving as the base of a page class implementation following the
+ Page Object Model pattern.
  </p></div>
 </div>
 </section>