testcentricity_web 4.1.2.1 → 4.1.5

data/README.md

@@ -3,14 +3,12 @@
 [![Gem Version](https://badge.fury.io/rb/testcentricity_web.svg)](https://badge.fury.io/rb/testcentricity_web)  [![License (3-Clause BSD)](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg?style=flat-square)](http://opensource.org/licenses/BSD-3-Clause)
 
 
-The TestCentricity™ Web core generic framework for desktop and mobile web browser-based app testing implements a Page Object and Data
-Object Model DSL for use with Cucumber, Capybara (version 3.x), and Selenium-Webdriver (version 4.x).
-
-**An example project that demonstrates the implementation of a page object model framework using Cucumber and TestCentricity™ can be found [here](https://github.com/TestCentricity/tc_web_sample).**
+The TestCentricity™ Web core generic framework for desktop and mobile web browser-based app testing implements a Page Object Model DSL
+for use with Cucumber, Capybara (version 3.x), and Selenium-Webdriver (version 4.x). It also facilitates the configuration of the appropriate
+Selenium-Webdriver capabilities required to establish a connection with a local or cloud hosted desktop or mobile web browser.
 
 The TestCentricity™ Web gem supports running automated tests against the following web test targets:
-* locally hosted desktop browsers (Firefox, Chrome, Edge, Safari, or IE)
-* locally hosted emulated iOS Mobile Safari, Android, Windows Phone, or Blackberry mobile browsers (running within a local instance of Chrome)
+* locally hosted desktop browsers (Chrome, Edge, Firefox, Safari, or IE)
 * locally hosted "headless" Chrome, Firefox, or Edge browsers
 * remote desktop and emulated mobile web browsers hosted on Selenium Grid 4 and Dockerized Selenium Grid 4 environments
 * mobile Safari browsers on iOS device simulators or physical iOS devices (using Appium and XCode on OS X)
@@ -22,16 +20,20 @@ The TestCentricity™ Web gem supports running automated tests against the follo
   * [LambdaTest](https://www.lambdatest.com/selenium-automation)
 * web portals utilizing JavaScript front end application frameworks like Ember, React, Angular, and GWT
 * web pages containing HTML5 Video and Audio objects
+* locally hosted emulated iOS Mobile Safari, Android, Windows Phone, or Blackberry mobile browsers (running within a local instance of Chrome)
 
 
 ## What's New
 
 A complete history of bug fixes and new features can be found in the {file:CHANGELOG.md CHANGELOG} file.
 
+An example project that demonstrates the implementation of a page object model framework using Cucumber and TestCentricity™
+can be found [here](https://github.com/TestCentricity/tc_web_sample).
+
 
 ## Installation
 
-TestCentricity requires Ruby 2.7 or later. To install the TestCentricity gem, add this line to your automation project's Gemfile:
+TestCentricity version 4.1 and above requires Ruby 2.7 or later. To install the TestCentricity gem, add this line to your automation project's Gemfile:
 
     gem 'testcentricity_web'
 
@@ -47,7 +49,7 @@ Or install it yourself as:
 ## Setup
 ### Using Cucumber
 
-If you are using Cucumber, you need to require the following in your *env.rb* file:
+If you are using Cucumber, you need to require the following in your `env.rb` file:
 
     require 'capybara/cucumber'
     require 'testcentricity_web'
@@ -55,7 +57,7 @@ If you are using Cucumber, you need to require the following in your *env.rb* fi
 
 ### Using RSpec
 
-If you are using RSpec instead, you need to require the following in your *env.rb* file:
+If you are using RSpec instead, you need to require the following in your `env.rb` file:
 
     require 'capybara'
     require 'capybara/rspec'
@@ -65,7 +67,7 @@ If you are using RSpec instead, you need to require the following in your *env.r
 ### Using Appium
 
 If you will be running your tests on mobile Safari browsers on simulated iOS devices using Appium and XCode Simulators, you need to require
-the following in your *env.rb* file:
+the following in your `env.rb` file:
 
     require 'appium_capybara'
 
@@ -78,7 +80,7 @@ And then execute:
     $ bundle
 
 
-## Page Objects
+## PageObjects
 
 The **Page Object Model** is a test automation pattern that aims to create an abstraction of your web app's User Interface that can be used
 in tests. A **Page Object** is an object that represents a single page in your AUT (Application Under Test). **Page Objects** encapsulate the
@@ -87,14 +89,14 @@ implementation details of a web page and expose an API that supports interaction
 **Page Objects** makes it easier to maintain automated tests because changes to page UI elements are updated in only one location - in the
 **Page Object** class definition. By adopting a **Page Object Model**, Cucumber Feature files and step definitions are no longer required to
 hold specific information about a page's UI objects, thus minimizing maintenance requirements. If any element on, or property of a page changes
-(URL path, text field attributes, button captions, etc.), maintenance is performed in the **Page Object** class definition only, typically with
+(URL path, text field attributes, button captions, etc.), maintenance is performed in the `PageObject` class definition only, typically with
 no need to update the affected feature file, scenarios, or step definitions.
 
 
-### Defining a Page Object
+### Defining a PageObject
 
-Your **Page Object** class definitions should be contained within individual `.rb` files in the `features/support/pages` folder of your
-test automation project. You define new **Page Objects** as shown below:
+Your `PageObject` class definitions should be contained within individual `.rb` files in the `features/support/pages` folder of your
+test automation project. You define new `PageObjects` as shown below:
 
     class LoginPage < TestCentricity::PageObject
     end
@@ -108,14 +110,14 @@ test automation project. You define new **Page Objects** as shown below:
     end
 
 
-### Adding Traits to your Page Object
+### Adding Traits to your PageObject
 
 Web pages typically have names and URLs associated with them. Web pages also typically have a unique object or attribute that, when present,
 indicates that the page's contents have fully loaded.
 
-The `page_name` trait is registered with the **PageManager** object, which includes a `find_page` method that takes a page name as a
-parameter and returns an instance of the associated **Page Object**. If you intend to use the **PageManager**, you must define a `page_name`
-trait for each of the **Page Objects** to be registered.
+The `page_name` trait is registered with the `PageManager` object, which includes a `find_page` method that takes a page name as a
+parameter and returns an instance of the associated `Page Object`. If you intend to use the `PageManager`, you must define a `page_name`
+trait for each `PageObject` to be registered.
 
 The `page_name` trait is usually a `String` value that represents the name of the page that will be matched by the `PageManager.findpage` method.
 `page_name` traits are case and white-space sensitive. For pages that may be referenced with multiple names, the `page_name` trait may also be
@@ -133,36 +135,36 @@ for the `page_locator` trait to exist.
 You define your page's **Traits** as shown below:
 
     class LoginPage < TestCentricity::PageObject
-      trait(:page_name)       { 'Login' }
-      trait(:page_url)        { '/sign_in' }
-      trait(:page_locator)    { 'body.login-body' }
+      trait(:page_name)    { 'Login' }
+      trait(:page_url)     { '/sign_in' }
+      trait(:page_locator) { 'body.login-body' }
     end
 
 
     class HomePage < TestCentricity::PageObject
       # this page may be referred to as 'Home' or 'Dashboard' page so page_name trait is an Array of Strings
-      trait(:page_name)       { ['Home', 'Dashboard'] }
-      trait(:page_url)        { '/dashboard' }
-      trait(:page_locator)    { 'body.dashboard' }
+      trait(:page_name)    { ['Home', 'Dashboard'] }
+      trait(:page_url)     { '/dashboard' }
+      trait(:page_locator) { 'body.dashboard' }
     end
 
 
     class RegistrationPage < TestCentricity::PageObject
-      trait(:page_name)       { 'Registration' }
-      trait(:page_url)        { '/register' }
-      trait(:page_locator)    { 'body.registration' }
+      trait(:page_name)    { 'Registration' }
+      trait(:page_url)     { '/register' }
+      trait(:page_locator) { 'body.registration' }
     end
 
 
-### Adding UI Elements to your Page Object
+### Adding UI Elements to your PageObject
 
 Web pages are made up of UI elements like text fields, check boxes, combo boxes, radio buttons, tables, lists, buttons, etc.
-**UI Elements** are added to your **Page Object** class definition as shown below:
+**UI Elements** are added to your `PageObject` class definition as shown below:
 
     class LoginPage < TestCentricity::PageObject
-      trait(:page_name)       { 'Login' }
-      trait(:page_url)        { '/sign_in' }
-      trait(:page_locator)    { 'body.login-body' }
+      trait(:page_name)    { 'Login' }
+      trait(:page_url)     { '/sign_in' }
+      trait(:page_locator) { 'body.login-body' }
     
       # Login page UI elements
       textfield :user_id_field,       'input#userName'
@@ -174,9 +176,9 @@ Web pages are made up of UI elements like text fields, check boxes, combo boxes,
     
 
     class RegistrationPage < TestCentricity::PageObject
-      trait(:page_name)       { 'Registration' }
-      trait(:page_url)        { '/register' }
-      trait(:page_locator)    { 'body.registration' }
+      trait(:page_name)    { 'Registration' }
+      trait(:page_url)     { '/register' }
+      trait(:page_locator) { 'body.registration' }
      
       # Registration page UI elements
       textfields  first_name_field:    'input#firstName',
@@ -196,16 +198,16 @@ Web pages are made up of UI elements like text fields, check boxes, combo boxes,
     end
 
 
-### Adding Methods to your Page Object
+### Adding Methods to your PageObject
 
-It is good practice for your Cucumber step definitions to call high level methods in your your **Page Object** instead of directly accessing
-and interacting with a page object's UI elements. You can add high level methods to your **Page Object** class definition for interacting with
+It is good practice for your Cucumber step definitions to call high level methods in your your `PageObject` instead of directly accessing
+and interacting with a page object's UI elements. You can add high level methods to your `PageObject` class definition for interacting with
 the UI to hide implementation details, as shown below:
 
     class LoginPage < TestCentricity::PageObject
-      trait(:page_name)       { 'Login' }
-      trait(:page_url)        { '/sign_in' }
-      trait(:page_locator)    { 'body.login-body' }
+      trait(:page_name)    { 'Login' }
+      trait(:page_url)     { '/sign_in' }
+      trait(:page_locator) { 'body.login-body' }
     
       # Login page UI elements
       textfield :user_id_field,        'input#userName'
@@ -232,9 +234,9 @@ the UI to hide implementation details, as shown below:
         ui = {
             self                 => { title: 'Login' },
             login_button         => { visible: true, caption: 'LOGIN' },
-            user_id_field        => { visible: true, enabled: true },
+            user_id_field        => { visible: true, enabled: true, value: '', placeholder: 'User name' },
             password_field       => { visible: true, enabled: true, value: '', placeholder: 'Password' },
-            remember_checkbox    => { :exists  => true, enabled: true, checked: false },
+            remember_checkbox    => { exists: true, enabled: true, checked: false },
             forgot_password_link => { visible: true, caption: 'Forgot your password?' },
             error_message_label  => { visible: false }
             }
@@ -244,9 +246,9 @@ the UI to hide implementation details, as shown below:
         
 
     class RegistrationPage < TestCentricity::PageObject
-      trait(:page_name)       { 'Registration' }
-      trait(:page_url)        { '/register' }
-      trait(:page_locator)    { 'body.registration' }
+      trait(:page_name)    { 'Registration' }
+      trait(:page_url)     { '/register' }
+      trait(:page_locator) { 'body.registration' }
      
       # Registration page UI elements
       textfields  first_name_field:    'input#firstName',
@@ -278,7 +280,8 @@ the UI to hide implementation details, as shown below:
                    state_select        => profile.state,
                    post_code_field     => profile.postal_code,
                    password_field      => profile.password,
-                   pword_confirm_field => profile.confirm_password
+                   pword_confirm_field => profile.confirm_password,
+                   email_opt_in_check  => profile.email_opt_in
           }
         populate_data_fields(fields)
         sign_up_button.click
@@ -287,18 +290,18 @@ the UI to hide implementation details, as shown below:
 
 
 
-Once your **Page Objects** have been instantiated, you can call your methods as shown below:
+Once your `PageObjects` have been instantiated, you can call your methods as shown below:
 
     login_page.remember_me(true)
     login_page.login('snicklefritz', 'Pa55w0rd')
     
 
 
-## PageSection Objects
+## PageSections
 
-A **PageSection Object** is a collection of **UI Elements** that may appear in multiple locations on a page, or on multiple pages in a web
+A `PageSection` is a collection of **UI Elements** that may appear in multiple locations on a page, or on multiple pages in a web
 app. It is a collection of **UI Elements** that represent a conceptual area of functionality, like a navigation bar, a search capability,
-or a menu. **UI Elements** and functional behavior are confined to the scope of a **PageSection Object**.
+or a menu. **UI Elements** and functional behavior are confined to the scope of a `PageSection` object.
 
 <img src="https://i.imgur.com/BTgi59R.jpg" alt="Navigation Header" title="Navigation Header">
 
@@ -307,39 +310,39 @@ or a menu. **UI Elements** and functional behavior are confined to the scope of
 <img src="https://i.imgur.com/Yqgw4sP.jpg" alt="User Profile Popup" title="User Profile Popup">
 
 
-A **PageSection Object** may contain other **PageSection Objects**.
+A `PageSection` may contain other `PageSection` objects.
 
 
-### Defining a PageSection Object
+### Defining a PageSection
 
-Your **PageSection** class definitions should be contained within individual `.rb` files in the `features/support/sections` folder of
-your test automation project. You define new **PageSection Objects** as shown below:
+Your `PageSection` class definitions should be contained within individual `.rb` files in the `features/support/sections` folder of
+your test automation project. You define new `PageSection` as shown below:
 
     class SearchForm < TestCentricity::PageSection
     end
 
 
-### Adding Traits to a PageSection Object
+### Adding Traits to a PageSection
 
-A **PageSection Object** typically has a root node object that encapsulates a collection of **UI Elements**. The `section_locator` trait
+A `PageSection` typically has a root node object that encapsulates a collection of `UIElements`. The `section_locator` trait
 specifies the CSS or Xpath expression that uniquely identifies that root node object.
 
-You define your page section's **Traits** as shown below:
+You define your section's **Traits** as shown below:
 
     class SearchForm < TestCentricity::PageSection
-      trait(:section_locator)   { 'form#gnav-search' }
-      trait(:section_name)      { 'Search widget' }
+      trait(:section_locator) { 'form#gnav-search' }
+      trait(:section_name)    { 'Search widget' }
     end
 
 
-### Adding UI Elements to your PageSection Object
+### Adding UI Elements to your PageSection
 
-Page sections are typically made up of UI elements like text fields, check boxes, combo boxes, radio buttons, tables, lists, buttons, etc.
-**UI Elements** are added to your **PageSection** class definition as shown below:
+`PageSections` are typically made up of UI elements like text fields, check boxes, combo boxes, radio buttons, tables, lists, buttons, etc.
+**UI Elements** are added to your `PageSection` class definition as shown below:
 
     class SearchForm < TestCentricity::PageSection
-      trait(:section_locator)   { 'form#gnav-search' }
-      trait(:section_name)      { 'Search widget' }
+      trait(:section_locator) { 'form#gnav-search' }
+      trait(:section_name)    { 'Search widget' }
         
       # Search Form UI elements
       textfield :search_field,  'input#search-query'
@@ -347,13 +350,13 @@ Page sections are typically made up of UI elements like text fields, check boxes
     end
 
 
-### Adding Methods to your PageSection Object
+### Adding Methods to your PageSection
 
-You can add high level methods to your **PageSection** class definition, as shown below:
+You can add high level methods to your `PageSection` class definition, as shown below:
 
     class SearchForm < TestCentricity::PageSection
-      trait(:section_locator)   { 'form#gnav-search' }
-      trait(:section_name)      { 'Search widget' }
+      trait(:section_locator) { 'form#gnav-search' }
+      trait(:section_name)    { 'Search widget' }
         
       # Search Form UI elements
       textfield :search_field,  'input#search-query'
@@ -366,48 +369,48 @@ You can add high level methods to your **PageSection** class definition, as show
     end
 
 
-### Adding PageSection Objects to your Page Object
+### Adding PageSections to your PageObject
 
-You add a **PageSection Object** to its associated **Page Object** as shown below:
+You add a `PageSection` to its associated `PageObject` as shown below:
 
     class HomePage < TestCentricity::PageObject
-      trait(:page_name)       { 'Home' }
-      trait(:page_url)        { '/dashboard' }
-      trait(:page_locator)    { 'body.dashboard' }
+      trait(:page_name)     { 'Home' }
+      trait(:page_url)      { '/dashboard' }
+      trait(:page_locator)  { 'body.dashboard' }
       
       # Home page Section Objects
       section :search_form, SearchForm
     end
 
-Once your **Page Object** has been instantiated, you can call its **PageSection** methods as shown below:
+Once your `PageObject` has been instantiated, you can call its `PageSection` methods as shown below:
 
     home_page.search_form.search_for('ocarina')
     
     
 
-## UI Elements
+## UIElements
 
-**Page Objects** and **PageSection Objects** are typically made up of **UI Element** like text fields, check boxes, combo boxes, radio buttons,
-tables, lists, buttons, images, HTML5 video objects, HTML5 audio objects, etc. **UI Elements** are declared and instantiated within the class
-definition of the **Page Object** or **PageSection Object** in which they are contained. With TestCentricity Web, all UI elements are based on
-the **UIElement** class.
+`PageObjects` and `PageSections` are typically made up of **UI Element** like text fields, check boxes, select lists (combo boxes),
+radio buttons, tables, ordered and unordered lists, buttons, images, HTML5 video objects, HTML5 audio objects, etc. **UI Elements** are declared
+and instantiated within the class definition of the `PageObject` or `PageSection` in which they are contained. With TestCentricity Web,
+all UI elements are based on the `UIElement` class.
 
 
-### Declaring and Instantiating UI Element
+### Declaring and Instantiating UIElements
 
-Single **UIElement** declarations have the following format:
+Single `UIElement` declarations have the following format:
                                      
     elementType :element Name, locator
 
-* The `element name` is the unique name that you will use to refer to the UI element and is specified as a symbol.
-* The `locator` is the CSS or XPath attribute that uniquely and unambiguously identifies the UI element.
+* The `element name` is the unique name that you will use to refer to the UI element and is specified as a `Symbol`.
+* The `locator` is the CSS or XPath attribute that uniquely and unambiguously identifies the `UIElement`.
 
-Multiple **UIElement** declarations for a collection of elements of the same type can be performed by passing a hash table containing the
+Multiple `UIElement` declarations for a collection of elements of the same type can be performed by passing a hash table containing the
 names and locators of each individual element.
 
-### Example UI Element Declarations
+### Example UIElement Declarations
 
-Supported **UI Element** elementTypes and their declarations have the following format:
+Supported `UIElement` elementTypes and their declarations have the following format:
 
 *Single element declarations:*
 
@@ -469,14 +472,14 @@ Supported **UI Element** elementTypes and their declarations have the following
     end
 
 
-Refer to the Class List documentation for the **PageObject** and **PageSection** classes for details on the class methods used for declaring
-and instantiating **UI Elements**. Examples of UI element declarations can be found in the ***Adding UI Elements to your Page Object*** and
+Refer to the Class List documentation for the `PageObject` and `PageSection` classes for details on the class methods used for declaring
+and instantiating `UIElements`. Examples of UI element declarations can be found in the ***Adding UI Elements to your Page Object*** and
 ***Adding UI Elements to your PageSection Object*** sections above.
 
 
 ### UIElement Inherited Methods
 
-With TestCentricity, all UI elements are based on the **UIElement** class, and inherit the following methods:
+With TestCentricity, all UI elements are based on the `UIElement` class, and inherit the following methods:
 
 **Action methods:**
 
@@ -600,7 +603,7 @@ for each `UIElement` that requires verification. Depending on the complexity and
 verify the presence of `UIElements` and their correct states can become cumbersome.
 
 The `PageObject.verify_ui_states` and `PageSection.verify_ui_states` methods support the verification of multiple properties of multiple
-UI elements on a **Page Object** or **PageSection Object**. The `verify_ui_states` method accepts a hash containing key/hash pairs of UI
+UI elements on a `PageObject` or `PageSection`. The `verify_ui_states` method accepts a hash containing key/hash pairs of UI
 elements and their properties or attributes to be verified.
 
      ui = {
@@ -631,6 +634,8 @@ The `verify_ui_states` method supports the following property/state pairs:
     :class             String
     :value or :caption String
     :attribute         Hash
+    :style             String
+    :tabindex          Integer
 
 **Text Fields:**
 
@@ -643,12 +648,17 @@ The `verify_ui_states` method supports the following property/state pairs:
 
 **Checkboxes:**
 
-    :checked Boolean
+    :checked       Boolean
+    :indeterminate Boolean
 
 **Radio Buttons:**
 
     :selected Boolean
 
+**Links:**
+
+    :href String
+
 **Images**
 
     :loaded Boolean
@@ -668,6 +678,8 @@ The `verify_ui_states` method supports the following property/state pairs:
     :items or :options         Array of Strings
     :itemcount or :optioncount Integer
     :selected                  String
+    :groupcount                Integer
+    :group_headings            Array of Strings
 
 **Tables**
 
@@ -699,9 +711,9 @@ The `verify_ui_states` method supports the following property/state pairs:
     :preload               String
     :poster                String
 
-The `verify_ui_states` method supports the following ARIA accessibility property/state pairs:
+#### ARIA accessibility property/state pairs
 
-**All Objects:**
+The `verify_ui_states` method supports the following ARIA accessibility property/state pairs:
 
     :aria_label           String
     :aria_disabled        Boolean
@@ -733,12 +745,15 @@ The `verify_ui_states` method supports the following ARIA accessibility property
     :aria_multiline       Boolean
     :aria_multiselectable Boolean
     :content_editable     Boolean
+    :role                 String
+
+#### Comparison States
 
 The `verify_ui_states` method supports comparison states using property/comparison state pairs:
 
     object => { property: { comparison_state: value } }
 
-**Comparison States:**
+Comparison States:
 
     :lt or :less_than                  Integer or String
     :lt_eq or :less_than_or_equal      Integer or String
@@ -773,19 +788,19 @@ values appear in the associated text fields after entering data and performing a
     end
 
 
-**I18n Translation Validation**
+#### I18n Translation Validation
 
 The `verify_ui_states` method also supports I18n string translations using property/I18n key name pairs:
 
-    object => { property: { translate_key: I18n key name } }
+    object => { property: { translate_key: 'name of key in I18n compatible .yml file' } }
 
 **I18n Translation Keys:**
 
-    :translate            String (name of key in I18n compatible .yml file)
-    :translate_upcase     String (name of key in I18n compatible .yml file)
-    :translate_downcase   String (name of key in I18n compatible .yml file)
-    :translate_capitalize String (name of key in I18n compatible .yml file)
-    translate_titlecase:  String (name of key in I18n compatible .yml file)
+    :translate            String
+    :translate_upcase     String
+    :translate_downcase   String
+    :translate_capitalize String
+    :translate_titlecase  String
 
 The example below depicts the usage of the `verify_ui_states` method to verify that the captions for menu items are correctly
 translated.
@@ -804,27 +819,166 @@ translated.
       verify_ui_states(ui)
     end
 
-Baseline translation strings are stored in `.yml` files in the `config/locales/` folder. Each supported language/locale combination
-has a corresponding `.yml` file. I18n `.yml` file naming convention uses [ISO-639 language codes and ISO-3166 country codes](https://docs.oracle.com/cd/E13214_01/wli/docs92/xref/xqisocodes.html). For example:
+Each supported language/locale combination has a corresponding `.yml` file. I18n `.yml` file naming convention uses
+[ISO-639 language codes and ISO-3166 country codes](https://docs.oracle.com/cd/E13214_01/wli/docs92/xref/xqisocodes.html). For example:
 
-    English               en.yml
-    English (Canada)      en-CA.yml
-    French (Canada)       fr-CA.yml
-    French                fr.yml
-    Spanish               es.yml
-    German                de.yml
-    Portuguese (Brazil)   pt-BR.yml
-    Portuguese (Portugal) pt-PT.yml
+| Language (Country)    | File name |
+|-----------------------|-----------|
+| English               | en.yml    |
+| English (Canada)      | en-CA.yml |
+| French (Canada)       | fr-CA.yml |
+| French                | fr.yml    |
+| Spanish               | es.yml    |
+| German                | de.yml    |
+| Portuguese (Brazil)   | pt-BR.yml |
+| Portuguese (Portugal) | pt-PT.yml |
 
 I18n `.yml` files contain key/value pairs representing the name of a translated string (key) and the string value.
 
+Baseline translation strings are stored in `.yml` files in the `config/locales/` folder.
+
+    my_automation_project
+        ├── config
+        │   ├── locales
+        │   │   ├── en.yml
+        │   │   ├── es.yml
+        │   │   ├── fr.yml
+        │   │   ├── fr-CA.yml
+        │   │   └── en-AU.yml
+        │   ├── test_data
+        │   └── cucumber.yml
+        ├── downloads
+        ├── features
+        ├── Gemfile
+        └── README.md
+
+
+### Working with custom UIElements
+
+Many responsive and touch-enabled web based user interfaces are implemented using front-end JavaScript libraries for building user
+interfaces based on UI components. Popular JS libraries include React, Angular, and Ember.js. These stylized and adorned controls can
+present a challenge when attempting to interact with them using Capybara and Selenium based automated tests.
+
+#### Radio and Checkbox UIElements
+
+Sometimes, radio buttons and checkboxes implemented using JS component libraries cannot be interacted with due to other UI elements
+being overlaid on top of them and the base `input(type='radio')` or `input(type='checkbox')` element not being visible.
+
+In the screenshots below of an airline flight search and booking page, the **Roundtrip** and **One-way** radio buttons are adorned with
+`label` elements that also acts as proxies for their associated `input(type='radio')` elements, and they intercept the `click` actions
+that would normally be handled by the `input(type='radio')` elements.
 
+<img src="https://i.imgur.com/7bW5u4c.jpg" alt="Roundtrip Radio button Input" title="Roundtrip Radio button Input">
 
-## Instantiating your Page Objects
 
-Before you can call the methods in your **Page Objects** and **PageSection Objects**, you must instantiate the **Page Objects** of your
-web application, as well as create instance variables which can be used when calling a **Page Objects** methods from your step definitions.
-There are several ways to instantiate your **Page Objects**.
+This screenshot shows the `label` element that is overlaid above the **Roundtrip** `input(type='radio')` element.
+
+<img src="https://i.imgur.com/2stWiyR.jpg" alt="Roundtrip Radio button Label" title="Roundtrip Radio button Label">
+
+
+The checkbox controls in this web UI are also adorned with `label` elements that act as proxies for their associated `input(type='checkbox')`
+elements.
+
+<img src="https://i.imgur.com/JcOANqZ.jpg" alt="One-way Radio button Label" title="One-way Radio button Label">
+
+
+The `Radio.define_custom_elements` and `CheckBox.define_custom_elements` methods provide a way to specify the `proxy` and/or `label`
+elements associated with the `input(type='radio')` or `input(type='checkbox')` elements. The `define_custom_elements` method
+should be called from an `initialize` method for the `PageObject` or `PageSection` where the `radio` or `checkbox` element is instantiated.
+The code snippet below demonstrates the use of the `Radio.define_custom_elements` and `CheckBox.define_custom_elements` methods to
+resolve the testability issues posed by the adorned **Roundtrip** and **One-way** radio buttons and the **Flexible dates** checkbox.
+
+    class FlightBookingPage < TestCentricity::PageObject
+      trait(:page_name)    { 'Flight Booking Home' }
+      trait(:page_locator) { "div[class*='bookerContainer']" }
+      
+      # Flight Booking page UI elements
+      radios   roundtrip_radio: 'input#roundtrip',
+               one_way_radio:   'input#oneway'
+      checkbox :flexible_check, 'input#flexibleDates'
+      
+      def initialize
+        # define the custom element components for the Round Trip radio button
+        radio_spec = { proxy: "label[for='roundtrip']" }
+        roundtrip_radio.define_custom_elements(radio_spec)
+        # define the custom element components for the One Way radio button
+        radio_spec = { proxy: "label[for='oneway']" }
+        one_way_radio.define_custom_elements(radio_spec)
+        # define the custom element components for the Flexible Date checkbox
+        check_spec = { proxy: 'label#flexDatesLabel' }
+        flexible_check.define_custom_elements(check_spec)
+      end
+    end
+
+
+#### SelectList UIElements
+
+The basic HTML `select` element is typically composed of the parent `select` object, and one or more `option` elements representing
+the selectable items in the drop-down list. However, `select` type controls implemented using JS component libraries can be composed
+of multiple elements representing the various components of a drop-down style `selectlist` implementation.
+
+In the screenshots below of an airline flight search and booking page, there are no `select` or `option` elements associated with the
+**Month**, **Day**, and **Cabin Type** drop-down style selectors. An inspection of the **Month** selector reveals that it is a `div`
+element that contains a `button` element (outlined in red) for triggering the drop-down list, a `ul` element (outlined in green) that
+contains the drop-down list, and multiple `li` elements (outlined in blue) that represent the list items or options that can be
+selected. The currently selected item or option can be identified by either the `listBoxOptionSelected` snippet in its `class` name or
+the `aria-selected` attribute (outlined in orange).
+
+Further examination of the **Day** and **Cabin Type** drop-down style selectors reveal that their composition is identical to the
+**Month** selector.
+
+<img src="https://i.imgur.com/LYAC2lh.jpg" alt="Custom SelectList" title="Custom SelectList">
+
+
+The `SelectList.define_list_elements` method provides a means of specifying the various elements that make up the key components of
+a `selectlist` control. The method accepts a hash of element designators (key) and a CSS or Xpath expression (value) that expression
+that uniquely identifies the element. Valid element designators are `list_item:`, `options_list:`, `list_trigger:`, `selected_item:`,
+`text_field:`, `group_heading:`, and `group_item:`.
+
+The code snippet below demonstrates the use of the `SelectList.define_list_elements` method to define the common components that make
+up the **Month**, **Day**, and **Cabin Type** drop-down style selectors. Note the use of the ARIA `role` and `aria-selected` attributes
+as element locators.
+
+    class FlightBookingPage < TestCentricity::PageObject
+      trait(:page_name)    { 'Flight Booking Home' }
+      trait(:page_locator) { "div[class*='bookerContainer']" }
+      
+      # Flight Booking page UI elements
+      selectlists month_select:      "div[class*='expandFlexMonth']",
+                  duration_select:   "div[class*='expandFlexDay']",
+                  cabin_type_select: "div[class*='bookFlightForm__optionField'] > div[class*='app-components-ListBox']"
+
+      def initialize
+        # define the custom list element components for the Month, Duration, and Cabin Type selectlist objects
+        list_spec = {
+          selected_item: "li[aria-selected=true]",
+          options_list:  "ul[role='listbox']",
+          list_item:     "li[role='option']",
+          list_trigger:  "button[role='combobox']"
+        }
+        month_select.define_list_elements(list_spec)
+        duration_select.define_list_elements(list_spec)
+        cabin_type_select.define_list_elements(list_spec)
+      end
+    end
+
+
+#### List UIElements
+
+The basic HTML list is typically composed of the parent `ul` object, and one or more `li` elements representing the items
+in the list. However, list controls implemented using JS component libraries can be composed of multiple elements representing the
+components of a list implementation.
+
+The `List.define_list_elements` method provides a means of specifying the elements that make up the key components of a `list` control.
+The method accepts a hash of element designators (key) and a CSS or Xpath expression (value) that expression that uniquely identifies
+the element. Valid element designators are `list_item:`and `selected_item:`.
+
+
+## Instantiating your PageObjects
+
+Before you can call the methods in your `PageObjects` and `PageSections`, you must instantiate the `PageObjects` of your web
+application, as well as create instance variables which can be used when calling a `PageObject`'s methods from your step definitions.
+There are several ways to instantiate your `PageObjects`.
 
 One common implementation is shown below:
 
@@ -851,14 +1005,14 @@ One common implementation is shown below:
 The `WorldPages` module above can be defined in your `env.rb` file, or you can define it in a separate `world_pages.rb` file in the
 `features/support` folder.
 
-While this approach is effective for small web applications with only a few pages (and hence few **Page Objects**), it quickly becomes
-cumbersome to manage if your web application has dozens of **Page Objects** that need to be instantiated and managed.
+While this approach is effective for small web applications with only a few pages (and hence few `PageObjects`), it quickly becomes
+cumbersome to manage if your web application has dozens of `PageObjects` that need to be instantiated and managed.
 
 ### Using the PageManager
 
-The **PageManager** class provides methods for supporting the instantiation and management of **Page Objects**. In the code example below,
-the `page_objects` method contains a hash table of your **Page Object** instances and their associated **Page Object** class names
-to be instantiated by **PageManager**:
+The `PageManager` class provides methods for supporting the instantiation and management of `PageObjects`. In the code example below,
+the `page_objects` method contains a hash table of your `PageObject` instances and their associated `PageObject` class names to be 
+instantiated by `PageManager`:
     
     module WorldPages
       def page_objects
@@ -888,13 +1042,13 @@ to be instantiated by **PageManager**:
     
 The `WorldPages` module above should be defined in the `world_pages.rb` file in the `features/support` folder.
 
-Include the code below in your `env.rb` file to ensure that your **Page Objects** are instantiated before your Cucumber scenarios are
+Include the code below in your `env.rb` file to ensure that your `PageObjects` are instantiated before your Cucumber scenarios are
 executed:
     
     include WorldPages
     WorldPages.instantiate_page_objects
     
-**NOTE:** If you intend to use the **PageManager**, you must define a `page_name` trait for each of the **Page Objects** to be registered.
+**NOTE:** If you intend to use the `PageManager`, you must define a `page_name` trait for each of the `PageObjects` to be registered.
 
 
 ### Leveraging the PageManager in your Cucumber tests
@@ -956,14 +1110,13 @@ In the above example, the step definitions associated with the 3 steps might be
       end
 
 
+While this approach may be effective for small web applications with only a few pages (and hence few `PageObjects`), it quickly becomes
+cumbersome to manage if your web application has dozens of `PageObjects` that need to be managed.
 
-While this approach may be effective for small web applications with only a few pages (and hence few **Page Objects**), it quickly becomes
-cumbersome to manage if your web application has dozens of **Page Objects** that need to be managed.
-
-The **PageManager** class provides a `find_page` method that replaces the cumbersome and difficult to maintain `case` statement used in the
-above example. The **PageManager** `current_page` method allows you to set or get an instance of the currently active Page Object.
+The `PageManager` class provides a `find_page` method that replaces the cumbersome and difficult to maintain `case` statement used in the
+above example. The `PageManager.current_page` method allows you to set or get an instance of the currently active Page Object.
 
-To use these **PageManager** methods, include the step definitions and code below in a `page_steps.rb` or `generic_steps.rb` file in the
+To use these `PageManager` methods, include the step definitions and code below in a `page_steps.rb` or `generic_steps.rb` file in the
 `features/step_definitions` folder:
 
     include TestCentricity
@@ -1017,7 +1170,7 @@ values from the table below:
 | `safari`           | OS X only                                      |
 | `ie`               | Windows only (IE version 10.x or greater only) |
 
-Refer to **section 8.7 (Using Browser specific Profiles in cucumber.yml)** below.
+Refer to **section 8.6 (Using Browser specific Profiles in cucumber.yml)** below.
 
 
 #### Setting desktop browser window size
@@ -1033,16 +1186,13 @@ To maximize a desktop browser window, you set the `BROWSER_SIZE` Environment Var
 
 #### Testing file downloads with desktop browsers
 
-File download functionality can be tested with locally hosted instances of Chrome or Firefox desktop browsers. Your automation project must include
+File download functionality can be tested with locally hosted instances of Chrome, Edge, or Firefox desktop browsers. Your automation project must include
 a `/downloads` folder at the same level as the `/config` and `/features` folders, as depicted below:
 
     my_automation_project
         ├── config
-        │   └── test_data
         ├── downloads
         ├── features
-        │   ├── step_definitions
-        │   └── support
         ├── Gemfile
         └── README.md
 
@@ -1053,15 +1203,12 @@ test thread. This is to ensure that files downloaded in each test thread are iso
 
     my_automation_project
         ├── config
-        │   └── test_data
         ├── downloads
         │   ├── 1
         │   ├── 2
         │   ├── 3
         │   └── 4
         ├── features
-        │   ├── step_definitions
-        │   └── support
         ├── Gemfile
         └── README.md
 
@@ -1138,7 +1285,7 @@ To change the emulated device's screen orientation from the default setting, set
 To use a local instance of the Chrome desktop browser to host the emulated mobile web browser, you must set the `HOST_BROWSER` Environment Variable
 to `chrome`.
 
-Refer to **section 8.7 (Using Browser specific Profiles in cucumber.yml)** below.
+Refer to **section 8.6 (Using Browser specific Profiles in cucumber.yml)** below.
 
 
 #### User defined mobile device profiles
@@ -1156,8 +1303,6 @@ of the Chrome desktop browser. The user specified device profiles must be locate
         │   └── cucumber.yml
         ├── downloads
         ├── features
-        │   ├── step_definitions
-        │   └── support
         ├── Gemfile
         └── README.md
 
@@ -1183,10 +1328,12 @@ For remote desktop and emulated mobile web browsers running on Selenium Grid 4 o
 | `SELENIUM`               | Must be set to `remote`                                                                                                                                                       |
 | `REMOTE_ENDPOINT`        | Must be set to the URL of the Grid hub, which is usually `http://localhost:4444/wd/hub`                                                                                       |
 
-Refer to **section 8.7 (Using Browser specific Profiles in cucumber.yml)** below.
+Refer to **section 8.6 (Using Browser specific Profiles in cucumber.yml)** below.
 
 
-### Mobile Safari browser on iOS Simulators or iOS Physical Devices
+### Mobile browsers on Simulators or Physical Devices
+
+#### Mobile Safari browser on iOS Simulators or iOS Physical Devices
 
 You can run your mobile web tests against the mobile Safari browser on simulated iOS devices or physically connected iOS devices using Appium and XCode on
 OS X. You must install Appium, XCode, and the iOS version-specific device simulators for XCode. You must also ensure that the `appium_capybara` gem is
@@ -1197,34 +1344,38 @@ The Appium server must be running prior to invoking Cucumber to run your feature
 
 Once your test environment is properly configured, the following **Environment Variables** must be set as described in the table below.
 
-| **Environment Variable**   | **Description**                                                                                                                                                 |
-|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `WEB_BROWSER`              | Must be set to `appium`                                                                                                                                         |
-| `APP_PLATFORM_NAME`        | Must be set to `iOS`                                                                                                                                            |
-| `APP_BROWSER`              | Must be set to `Safari`                                                                                                                                         |
-| `APP_VERSION`              | Must be set to `12.2`, `11.4`, `10.3.1`, or which ever iOS version you wish to run within the XCode Simulator                                                   |
-| `APP_DEVICE`               | Set to iOS device name supported by the iOS Simulator (`iPhone 6s Plus`, `iPad Pro (10.5-inch)`, `iPad Air 2`, etc.) or name of physically connected iOS device |
-| `DEVICE_TYPE`              | Must be set to `phone` or `tablet`                                                                                                                              |
-| `APP_UDID`                 | UDID of physically connected iOS device (not used for simulators)                                                                                               |
-| `TEAM_ID`                  | unique 10-character Apple developer team identifier string (not used for simulators)                                                                            |
-| `TEAM_NAME`                | String representing a signing certificate (not used for simulators)                                                                                             |
-| `APP_ALLOW_POPUPS`         | [Optional] Allow javascript to open new windows in Safari. Set to `true` or `false`                                                                             |
-| `APP_IGNORE_FRAUD_WARNING` | [Optional] Prevent Safari from showing a fraudulent website warning. Set to `true` or `false`                                                                   |
-| `APP_NO_RESET`             | [Optional] Don't reset app state after each test. Set to `true` or `false`                                                                                      |
-| `APP_FULL_RESET`           | [Optional] Perform a complete reset. Set to `true` or `false`                                                                                                   |
-| `APP_INITIAL_URL`          | [Optional] Initial URL, default is a local welcome page.  e.g.  `http://www.apple.com`                                                                          |
-| `WDA_LOCAL_PORT`           | [Optional] Used to forward traffic from Mac host to real iOS devices over USB. Default value is same as port number used by WDA on device.                      |
-| `LOCALE`                   | [Optional] Locale to set for the simulator.  e.g.  `fr_CA`                                                                                                      |
-| `LANGUAGE`                 | [Optional] Language to set for the simulator.  e.g.  `fr`                                                                                                       |
-| `ORIENTATION`              | [Optional] Set to `portrait` or `landscape` (only for iOS simulators)                                                                                           |
-| `NEW_COMMAND_TIMEOUT`      | [Optional] Time (in Seconds) that Appium will wait for a new command from the client                                                                            |
-| `SHOW_SIM_KEYBOARD`        | [Optional] Show the simulator keyboard during text entry. Set to `true` or `false`                                                                              |
-| `SHUTDOWN_OTHER_SIMS`      | [Optional] Close any other running simulators. Set to `true` or `false`                                                                                         |
-
-Refer to **section 8.7 (Using Browser specific Profiles in cucumber.yml)** below.
-
-
-### Mobile Chrome or Android browsers on Android Studio Virtual Device emulators
+| **Environment Variable**   | **Description**                                                                                                                                                       |
+|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `WEB_BROWSER`              | Must be set to `appium`                                                                                                                                               |
+| `APP_PLATFORM_NAME`        | Must be set to `iOS`                                                                                                                                                  |
+| `APP_BROWSER`              | Must be set to `Safari`                                                                                                                                               |
+| `APP_VERSION`              | Must be set to `15.4`, `14.5`, or which ever iOS version you wish to run within the XCode Simulator                                                                   |
+| `APP_DEVICE`               | Set to iOS device name supported by the iOS Simulator (`iPhone 13 Pro Max`, `iPad Pro (12.9-inch) (5th generation)`, etc.) or name of physically connected iOS device |
+| `DEVICE_TYPE`              | Must be set to `phone` or `tablet`                                                                                                                                    |
+| `APP_UDID`                 | UDID of physically connected iOS device (not used for simulators)                                                                                                     |
+| `TEAM_ID`                  | unique 10-character Apple developer team identifier string (not used for simulators)                                                                                  |
+| `TEAM_NAME`                | String representing a signing certificate (not used for simulators)                                                                                                   |
+| `APP_ALLOW_POPUPS`         | [Optional] Allow javascript to open new windows in Safari. Set to `true` or `false`                                                                                   |
+| `APP_IGNORE_FRAUD_WARNING` | [Optional] Prevent Safari from showing a fraudulent website warning. Set to `true` or `false`                                                                         |
+| `APP_NO_RESET`             | [Optional] Don't reset app state after each test. Set to `true` or `false`                                                                                            |
+| `APP_FULL_RESET`           | [Optional] Perform a complete reset. Set to `true` or `false`                                                                                                         |
+| `APP_INITIAL_URL`          | [Optional] Initial URL, default is a local welcome page.  e.g.  `http://www.apple.com`                                                                                |
+| `WDA_LOCAL_PORT`           | [Optional] Used to forward traffic from Mac host to real iOS devices over USB. Default value is same as port number used by WDA on device.                            |
+| `LOCALE`                   | [Optional] Locale to set for the simulator.  e.g.  `fr_CA`                                                                                                            |
+| `LANGUAGE`                 | [Optional] Language to set for the simulator.  e.g.  `fr`                                                                                                             |
+| `ORIENTATION`              | [Optional] Set to `portrait` or `landscape` (only for iOS simulators)                                                                                                 |
+| `NEW_COMMAND_TIMEOUT`      | [Optional] Time (in Seconds) that Appium will wait for a new command from the client                                                                                  |
+| `SHOW_SIM_KEYBOARD`        | [Optional] Show the simulator keyboard during text entry. Set to `true` or `false`                                                                                    |
+| `SHUTDOWN_OTHER_SIMS`      | [Optional] Close any other running simulators. Set to `true` or `false`. See note below.                                                                              |
+
+The `SHUTDOWN_OTHER_SIMS` environment variable can only be set if you are running Appium Server with the `--relaxed-security` or
+`--allow-insecure=shutdown_other_sims` arguments passed when starting it from the command line, or when running the server from the
+Appium Server GUI app. A security violation error will occur without relaxed security enabled. 
+
+Refer to **section 8.6 (Using Browser specific Profiles in cucumber.yml)** below.
+
+
+#### Mobile Chrome or Android browsers on Android Studio Virtual Device emulators
 
 You can run your mobile web tests against the mobile Chrome or Android browser on emulated Android devices using Appium and Android Studio on OS X. You
 must install Android Studio, the desired Android version-specific virtual device emulators, and Appium. Refer to [this page](http://appium.io/docs/en/drivers/android-uiautomator2/index.html)
@@ -1241,7 +1392,7 @@ Once your test environment is properly configured, the following **Environment V
 | `WEB_BROWSER`             | Must be set to `appium`                                                                                                        |
 | `APP_PLATFORM_NAME`       | Must be set to `Android`                                                                                                       |
 | `APP_BROWSER`             | Must be set to `Chrome` or `Browser`                                                                                           |
-| `APP_VERSION`             | Must be set to `8.0`, `7.0`, or which ever Android OS version you wish to run with the Android Virtual Device                  |
+| `APP_VERSION`             | Must be set to `12.0`, or which ever Android OS version you wish to run with the Android Virtual Device                        |
 | `APP_DEVICE`              | Set to Android Virtual Device ID (`Pixel_2_XL_API_26`, `Nexus_6_API_23`, etc.) found in Advanced Settings of AVD Configuration |
 | `DEVICE_TYPE`             | Must be set to `phone` or `tablet`                                                                                             |
 | `ORIENTATION`             | [Optional] Set to `portrait` or `landscape`                                                                                    |
@@ -1253,16 +1404,54 @@ Once your test environment is properly configured, the following **Environment V
 | `NEW_COMMAND_TIMEOUT`     | [Optional] Time (in Seconds) that Appium will wait for a new command from the client                                           |
 | `CHROMEDRIVER_EXECUTABLE` | [Optional] Absolute local path to webdriver executable                                                                         |
 
-Refer to **section 8.7 (Using Browser specific Profiles in cucumber.yml)** below.
+Refer to **section 8.6 (Using Browser specific Profiles in cucumber.yml)** below.
+
+
+#### Starting and stopping Appium Server
+
+The Appium server must be running prior to invoking Cucumber to run your features/scenarios on mobile simulators or physical
+device. To programmatically control the starting and stopping of Appium server with the execution of your automated tests, place
+the code shown below in your `hooks.rb` file.
+
+    BeforeAll do
+      # start Appium Server if APPIUM_SERVER = 'run' and target browser is a mobile simulator or device
+      if ENV['APPIUM_SERVER'] == 'run' && Environ.driver == :appium
+        $server = TestCentricity::AppiumServer.new
+        $server.start
+      end
+    end
+
+    AfterAll do
+      # terminate Appium Server if APPIUM_SERVER = 'run' and target browser is a mobile simulator or device
+      $server.stop if ENV['APPIUM_SERVER'] == 'run' && Environ.driver == :appium && $server.running?
+      # close driver
+      Capybara.page.driver.quit
+      Capybara.reset_sessions!
+      Environ.session_state = :quit
+    end
+
+
+The `APPIUM_SERVER` environment variable must be set to `run` in order to programmatically start and stop Appium server. This can be
+set by adding the following to your `cucumber.yml` file and including `-p run_appium` in your command line when starting your Cucumber
+test suite(s):
+
+    run_appium: APPIUM_SERVER=run
+
 
+Refer to **section 8.6 (Using Browser specific Profiles in cucumber.yml)** below.
 
-### Remotely hosted desktop and mobile web browsers
 
-You can run your automated tests against remotely hosted desktop and mobile web browsers using the BrowserStack, SauceLabs, TestingBot, or
+### Remote cloud hosted desktop and mobile web browsers
+
+You can run your automated tests against remote cloud hosted desktop and mobile web browsers using the BrowserStack, SauceLabs, TestingBot, or
 LambdaTest services. If your tests are running against a web site hosted on your local computer (`localhost`), or on a staging server inside
 your LAN, you must set the `TUNNELING` Environment Variable to `true`.
 
-Refer to **section 8.7 (Using Browser specific Profiles in cucumber.yml)** below.
+Due to lack of support for Selenium 4.x and the W3C browser capabilities protocol, support for CrossBrowserTesting and Gridlastic cloud hosted
+Selenium grid services was removed as of version 4.1 of this gem. If your testing requires access to either of those services, or support for
+Selenium version 3.x, you should use earlier versions of this gem.
+
+Refer to **section 8.6 (Using Browser specific Profiles in cucumber.yml)** below.
 
 
 #### Remote desktop browsers on the BrowserStack service
@@ -1271,24 +1460,24 @@ For remotely hosted desktop web browsers on the BrowserStack service, the follow
 the table below. Refer to the [Browserstack-specific capabilities chart page](https://www.browserstack.com/automate/capabilities?tag=selenium-4)
 for information regarding the specific capabilities.
 
-| **Environment Variable** | **Description**                                                                                                                                                 |
-|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `WEB_BROWSER`            | Must be set to `browserstack`                                                                                                                                   |
-| `BS_USERNAME`            | Must be set to your BrowserStack account user name                                                                                                              |
-| `BS_AUTHKEY`             | Must be set to your BrowserStack account access key                                                                                                             |
-| `BS_OS`                  | Must be set to `OS X` or `Windows`                                                                                                                              |
-| `BS_OS_VERSION`          | Refer to `os_version` capability in chart                                                                                                                       |
-| `BS_BROWSER`             | Refer to `browser` capability in chart                                                                                                                          |
-| `BS_VERSION`             | [Optional] Refer to `browser_version` capability in chart. If not specified, latest stable version of browser will be used.                                     |
-| `TUNNELING`              | Must be `true` if you are testing against internal/local servers (`true` or `false`). If `true`, the BrowserStack Local instance will be automatically started. |
-| `RESOLUTION`             | [Optional] Refer to supported screen `resolution` capability in chart                                                                                           |
-| `RECORD_VIDEO`           | [Optional] Enable screen video recording during test execution (`true` or `false`)                                                                              |
-| `TIME_ZONE`              | [Optional] Specify custom time zone. Refer to `browserstack.timezone` capability in chart                                                                       |
-| `IP_GEOLOCATION`         | [Optional] Specify IP Geolocation. Refer to [IP Geolocation](https://www.browserstack.com/ip-geolocation) to select a country code.                             |
-| `ALLOW_POPUPS`           | [Optional] Allow popups (`true` or `false`) - for Safari, IE, and Edge browsers only                                                                            |
-| `ALLOW_COOKIES`          | [Optional] Allow all cookies (`true` or `false`) - for Safari browsers only                                                                                     |
-| `SCREENSHOTS`            | [Optional] Generate screenshots for debugging (`true` or `false`)                                                                                               |
-| `NETWORK_LOGS`           | [Optional] Capture network logs (`true` or `false`)                                                                                                             |
+| **Environment Variable** | **Description**                                                                                                                                                            |
+|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `WEB_BROWSER`            | Must be set to `browserstack`                                                                                                                                              |
+| `BS_USERNAME`            | Must be set to your BrowserStack account user name                                                                                                                         |
+| `BS_AUTHKEY`             | Must be set to your BrowserStack account access key                                                                                                                        |
+| `BS_OS`                  | Must be set to `OS X` or `Windows`                                                                                                                                         |
+| `BS_OS_VERSION`          | Refer to `os_version` capability in chart                                                                                                                                  |
+| `BS_BROWSER`             | Refer to `browserName` capability in chart                                                                                                                                 |
+| `BS_VERSION`             | [Optional] Refer to `browser_version` capability in chart. If not specified, latest stable version of browser will be used.                                                |
+| `TUNNELING`              | [Optional] Must be `true` if you are testing against internal/local servers (`true` or `false`). If `true`, the BrowserStack Local instance will be automatically started. |
+| `RESOLUTION`             | [Optional] Refer to supported screen `resolution` capability in chart                                                                                                      |
+| `RECORD_VIDEO`           | [Optional] Enable screen video recording during test execution (`true` or `false`)                                                                                         |
+| `TIME_ZONE`              | [Optional] Specify custom time zone. Refer to `browserstack.timezone` capability in chart                                                                                  |
+| `IP_GEOLOCATION`         | [Optional] Specify IP Geolocation. Refer to [IP Geolocation](https://www.browserstack.com/ip-geolocation) to select a country code.                                        |
+| `ALLOW_POPUPS`           | [Optional] Allow popups (`true` or `false`) - for Safari, IE, and Edge browsers only                                                                                       |
+| `ALLOW_COOKIES`          | [Optional] Allow all cookies (`true` or `false`) - for Safari browsers only                                                                                                |
+| `SCREENSHOTS`            | [Optional] Generate screenshots for debugging (`true` or `false`)                                                                                                          |
+| `NETWORK_LOGS`           | [Optional] Capture network logs (`true` or `false`)                                                                                                                        |
 
 If the BrowserStack Local instance is running (`TUNNELING` Environment Variable is `true`), call the`TestCentricity::WebDriverConnect.close_tunnel` method
 upon completion of your test suite to stop the Local instance. Place the code shown below in your `env.rb` or `hooks.rb` file.
@@ -1305,43 +1494,43 @@ For remotely hosted mobile web browsers on the BrowserStack service, the followi
 the table below. Refer to the [Browserstack-specific capabilities chart page](https://www.browserstack.com/automate/capabilities?tag=selenium-4)
 for information regarding the specific capabilities.
 
-| **Environment Variable** | **Description**                                                                                                                                                 |
-|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `WEB_BROWSER`            | Must be set to `browserstack`                                                                                                                                   |
-| `BS_USERNAME`            | Must be set to your BrowserStack account user name                                                                                                              |
-| `BS_AUTHKEY`             | Must be set to your BrowserStack account access key                                                                                                             |
-| `BS_OS`                  | Must be set to `ios` or `android`                                                                                                                               |
-| `BS_BROWSER`             | Must be set to `Safari` (for iOS) or `Chrome` (for Android)                                                                                                     |
-| `BS_DEVICE`              | Refer to `device` capability in chart                                                                                                                           |
-| `BS_REAL_MOBILE`         | Set to `true` if running against a real device                                                                                                                  |
-| `DEVICE_TYPE`            | Must be set to `phone` or `tablet`                                                                                                                              |
-| `TUNNELING`              | Must be `true` if you are testing against internal/local servers (`true` or `false`). If `true`, the BrowserStack Local instance will be automatically started. |
-| `ORIENTATION`            | [Optional] Set to `portrait` or `landscape`                                                                                                                     |
-| `RECORD_VIDEO`           | [Optional] Enable screen video recording during test execution (`true` or `false`)                                                                              |
-| `TIME_ZONE`              | [Optional] Specify custom time zone. Refer to `browserstack.timezone` capability in chart                                                                       |
-| `IP_GEOLOCATION`         | [Optional] Specify IP Geolocation. Refer to [IP Geolocation](https://www.browserstack.com/ip-geolocation) to select a country code.                             |
-| `SCREENSHOTS`            | [Optional] Generate screenshots for debugging (`true` or `false`)                                                                                               |
-| `NETWORK_LOGS`           | [Optional] Capture network logs (`true` or `false`)                                                                                                             |
-| `APPIUM_LOGS`            | [Optional] Generate Appium logs (`true` or `false`)                                                                                                             |
+| **Environment Variable** | **Description**                                                                                                                                                            |
+|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `WEB_BROWSER`            | Must be set to `browserstack`                                                                                                                                              |
+| `BS_USERNAME`            | Must be set to your BrowserStack account user name                                                                                                                         |
+| `BS_AUTHKEY`             | Must be set to your BrowserStack account access key                                                                                                                        |
+| `BS_OS`                  | Must be set to `ios` or `android`                                                                                                                                          |
+| `BS_BROWSER`             | Must be set to `Safari` (for iOS) or `Chrome` (for Android)                                                                                                                |
+| `BS_DEVICE`              | Refer to `deviceName` capability in chart                                                                                                                                  |
+| `BS_REAL_MOBILE`         | Set to `true` if running against a real device                                                                                                                             |
+| `DEVICE_TYPE`            | Must be set to `phone` or `tablet`                                                                                                                                         |
+| `TUNNELING`              | [Optional] Must be `true` if you are testing against internal/local servers (`true` or `false`). If `true`, the BrowserStack Local instance will be automatically started. |
+| `ORIENTATION`            | [Optional] Set to `portrait` or `landscape`                                                                                                                                |
+| `RECORD_VIDEO`           | [Optional] Enable screen video recording during test execution (`true` or `false`)                                                                                         |
+| `TIME_ZONE`              | [Optional] Specify custom time zone. Refer to `browserstack.timezone` capability in chart                                                                                  |
+| `IP_GEOLOCATION`         | [Optional] Specify IP Geolocation. Refer to [IP Geolocation](https://www.browserstack.com/ip-geolocation) to select a country code.                                        |
+| `SCREENSHOTS`            | [Optional] Generate screenshots for debugging (`true` or `false`)                                                                                                          |
+| `NETWORK_LOGS`           | [Optional] Capture network logs (`true` or `false`)                                                                                                                        |
+| `APPIUM_LOGS`            | [Optional] Generate Appium logs (`true` or `false`)                                                                                                                        |
 
 #### Remote desktop browsers on the Sauce Labs service
 
-For remotely hosted desktop web browsers on the Sauce Labs service, the following **Environment Variables** must be set as described in
-the table below. Use the Selenium API on the [Platform Configurator page](https://wiki.saucelabs.com/display/DOCS/Platform+Configurator#/) to obtain
-information regarding the specific capabilities.
-
-| **Environment Variable** | **Description**                                                                                                        |
-|--------------------------|------------------------------------------------------------------------------------------------------------------------|
-| `WEB_BROWSER`            | Must be set to `saucelabs`                                                                                             |
-| `SL_USERNAME`            | Must be set to your Sauce Labs account user name or email address                                                      |
-| `SL_AUTHKEY`             | Must be set to your Sauce Labs account access key                                                                      |
-| `DATA_CENTER`            | Must be set to your Sauce Labs account Data Center assignment (`us-west-1`, `eu-central-1`, `apac-southeast-1`)        |
-| `SL_OS`                  | Refer to `platform` capability in the Copy Code section of the Platform Configurator page                              |
-| `SL_BROWSER`             | Must be set to `chrome`, `firefox`, `safari`, `internet explorer`, or `edge`                                           |
-| `SL_VERSION`             | Refer to `version` capability in the Copy Code section of the Platform Configurator page                               |
-| `RESOLUTION`             | [Optional] Refer to supported `screenResolution` capability in the Copy Code section of the Platform Configurator page |
-| `BROWSER_SIZE `          | [Optional] Specify width, height of browser window                                                                     |
-| `RECORD_VIDEO`           | [Optional] Enable screen video recording during test execution (`true` or `false`)                                     |
+For remotely hosted desktop web browsers on the Sauce Labs service, the following **Environment Variables** must be set as described in the
+table below. Use the Selenium 4 selection on the [Platform Configurator page](https://wiki.saucelabs.com/display/DOCS/Platform+Configurator#/)
+to obtain information regarding the specific capabilities.
+
+| **Environment Variable** | **Description**                                                                                                            |
+|--------------------------|----------------------------------------------------------------------------------------------------------------------------|
+| `WEB_BROWSER`            | Must be set to `saucelabs`                                                                                                 |
+| `SL_USERNAME`            | Must be set to your Sauce Labs account user name or email address                                                          |
+| `SL_AUTHKEY`             | Must be set to your Sauce Labs account access key                                                                          |
+| `DATA_CENTER`            | Must be set to your Sauce Labs account Data Center assignment (`us-west-1`, `eu-central-1`, `apac-southeast-1`)            |
+| `SL_OS`                  | Refer to `platformName` capability in the Config Script section of the Platform Configurator page                          |
+| `SL_BROWSER`             | Must be set to `chrome`, `firefox`, `safari`, `internet explorer`, or `MicrosoftEdge`                                      |
+| `SL_VERSION`             | Refer to `browserVersion` capability in the Config Script section of the Platform Configurator page                        |
+| `RESOLUTION`             | [Optional] Refer to supported `screenResolution` capability in the Config Script section of the Platform Configurator page |
+| `BROWSER_SIZE `          | [Optional] Specify width, height of browser window                                                                         |
+| `RECORD_VIDEO`           | [Optional] Enable screen video recording during test execution (`true` or `false`)                                         |
 
 #### Remote desktop browsers on the TestingBot service
 
@@ -1357,24 +1546,24 @@ regarding the specific capabilities.
 | `TB_OS`                  | Refer to `platform` capability in chart                                                                           |
 | `TB_BROWSER`             | Refer to `browserName` capability in chart                                                                        |
 | `TB_VERSION`             | Refer to `version` capability in chart                                                                            |
-| `TUNNELING`              | Must be `true` if you are testing against internal/local servers (`true` or `false`)                              |
+| `TUNNELING`              | [Optional] Must be `true` if you are testing against internal/local servers (`true` or `false`)                   |
 | `RESOLUTION`             | [Optional] Possible values: `800x600`, `1024x768`, `1280x960`, `1280x1024`, `1600x1200`, `1920x1200`, `2560x1440` |
 | `BROWSER_SIZE`           | [Optional] Specify width, height of browser window                                                                |
 
 #### Remote desktop browsers on the LambdaTest service
 
 For remotely hosted desktop web browsers on the LambdaTest service, the following **Environment Variables** must be set as described in the table
-below. Use the Configuration Wizard on the [Selenium Desired Capabilities Generator](https://www.lambdatest.com/capabilities-generator/) to obtain
-information regarding the specific capabilities.
+below. Use the Selenium 4 Configuration Wizard on the [Selenium Desired Capabilities Generator](https://www.lambdatest.com/capabilities-generator/)
+to obtain information regarding the specific capabilities.
 
 | **Environment Variable** | **Description**                                                                          |
 |--------------------------|------------------------------------------------------------------------------------------|
 | `WEB_BROWSER`            | Must be set to `lambdatest`                                                              |
 | `LT_USERNAME`            | Must be set to your LambdaTest account user name or email address                        |
 | `LT_AUTHKEY`             | Must be set to your LambdaTest account access key                                        |
-| `LT_OS`                  | Refer to `platform` capability in the sample script of the Wizard                        |
+| `LT_OS`                  | Refer to `platformName` capability in the sample script of the Wizard                    |
 | `LT_BROWSER`             | Refer to `browserName` capability in the sample script of the Wizard                     |
-| `LT_VERSION`             | Refer to `version` capability in chart                                                   |
+| `LT_VERSION`             | Refer to `browserVersion` capability in chart                                            |
 | `RESOLUTION`             | [Optional] Refer to supported `resolution` capability in the sample script of the Wizard |
 | `BROWSER_SIZE`           | [Optional] Specify width, height of browser window                                       |
 | `RECORD_VIDEO`           | [Optional] Enable screen video recording during test execution (`true` or `false`)       |
@@ -1480,17 +1669,25 @@ that you intend to connect with.
     
     portrait:  ORIENTATION=portrait
     landscape: ORIENTATION=landscape
+
     
+    #==============
+    # profile to start Appium Server prior to running mobile browser tests on iOS or Android simulators or physical devices
+    #==============
     
+    run_appium: APPIUM_SERVER=run
+
+
     #==============
     # profiles for mobile Safari web browsers hosted within XCode iOS simulator
     # NOTE: Requires installation of XCode, iOS version specific target simulators, Appium, and the appium_capybara gem
     #==============
 
-    appium_ios: WEB_BROWSER=appium AUTOMATION_ENGINE=XCUITest APP_PLATFORM_NAME="ios" APP_BROWSER="Safari" NEW_COMMAND_TIMEOUT=30 SHUTDOWN_OTHER_SIMS=true SHOW_SIM_KEYBOARD=false
-    app_ios_15: --profile appium_ios APP_VERSION="15.2"
-    ipad_pro_12_9_15_sim: --profile app_ios_15 DEVICE_TYPE=tablet APP_DEVICE="iPad Pro (12.9-inch) (5th generation)" <%= desktop %>
-    ipad_air_15_sim: --profile app_ios_15 DEVICE_TYPE=tablet APP_DEVICE="iPad Air (4th generation)" <%= desktop %>
+    appium_ios: WEB_BROWSER=appium AUTOMATION_ENGINE=XCUITest APP_PLATFORM_NAME="ios" APP_BROWSER="Safari" NEW_COMMAND_TIMEOUT=30 SHOW_SIM_KEYBOARD=false
+    app_ios_15: --profile appium_ios APP_VERSION="15.4"
+    ipad_pro_12_15_sim: --profile app_ios_15 DEVICE_TYPE=tablet APP_DEVICE="iPad Pro (12.9-inch) (5th generation)"
+    ipad_air_15_sim:    --profile app_ios_15 DEVICE_TYPE=tablet APP_DEVICE="iPad Air (5th generation)" <%= desktop %>
+    ipad_15_sim:        --profile app_ios_15 DEVICE_TYPE=tablet APP_DEVICE="iPad (9th generation)"
 
 
     #==============
@@ -1608,38 +1805,62 @@ To specify a locally hosted target browser using a profile at runtime, you use t
 invoking Cucumber in the command line. For instance, the following command invokes Cucumber and specifies that a local instance of Firefox
 will be used as the target web browser:
     
-    $ cucumber -p firefox
+    cucumber -p firefox
 
 
-The following command specifies that Cucumber will run tests against an instance of Chrome hosted within a Dockerized Selenium Grid environment"
+The following command specifies that Cucumber will run tests against an instance of Chrome hosted within a Dockerized Selenium Grid 4
+environment:
     
-    $ cucumber -p chrome -p grid
+    cucumber -p chrome -p grid
 
 
 The following command specifies that Cucumber will run tests against a local instance of Chrome, which will be used to emulate an iPad Pro
 in landscape orientation:
     
-    $ cucumber -p ipad_pro -p landscape
+    cucumber -p ipad_pro -p landscape
 
 
-The following command specifies that Cucumber will run tests against an iPad Pro with iOS version 9.3 in an XCode Simulator
-in landscape orientation:
+The following command specifies that Cucumber will run tests against an iPad Pro (12.9-inch) (5th generation) with iOS version 15.2 in an
+XCode Simulator in landscape orientation:
     
-    $ cucumber -p ipad_pro_93_sim -p landscape
+    cucumber -p ipad_pro_12_15_sim -p landscape
     
     NOTE:  Appium must be running prior to executing this command
 
+You can ensure that Appium Server is running by including `-p run_appium` in your command line:
+
+    cucumber -p ipad_pro_12_15_sim -p landscape -p run_appium
+
 
-The following command specifies that Cucumber will run tests against a remotely hosted Safari web browser running on an OS X Mojave
+The following command specifies that Cucumber will run tests against a remotely hosted Safari web browser running on a macOS Monterey
 virtual machine on the BrowserStack service:
 
-    cucumber -p bs_safari_mojave
- 
+    cucumber -p bs_safari_monterey
+
+
 
-The following command specifies that Cucumber will run tests against a remotely hosted Mobile Safari web browser on an iPhone 6s Plus in
-landscape orientation running on the BrowserStack service:
+## Recommended Project Organization and Structure
 
-    $ cucumber -p bs_iphone6_plus -p landscape
+Below is an example of the project structure of a typical Cucumber based test automation framework with a Page Object Model
+architecture. `PageObject` class definitions should be stored in the `/features/support/pages` folder, organized in functional
+area sub-folders as needed. Likewise, `PageSection` class definitions should be stored in the `/features/support/sections` folder.
+
+    my_automation_project
+        ├── config
+        │   ├── locales
+        │   ├── test_data
+        │   └── cucumber.yml
+        ├── downloads
+        ├── features
+        │   ├── step_definitions
+        │   └── support
+        │   │   ├── pages
+        │   │   ├── sections
+        │   │   ├── env.rb
+        │   │   ├── hooks.rb
+        │   │   └── world_pages.rb
+        ├── Gemfile
+        └── README.md