testcentricity_web 4.1.3 → 4.1.6

data/README.md

@@ -3,12 +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).
+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)
@@ -20,6 +20,7 @@ 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
@@ -48,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'
@@ -56,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'
@@ -66,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'
 
@@ -238,7 +239,7 @@ the UI to hide implementation details, as shown below:
             remember_checkbox    => { exists: true, enabled: true, checked: false },
             forgot_password_link => { visible: true, caption: 'Forgot your password?' },
             error_message_label  => { visible: false }
-            }
+        }
         verify_ui_states(ui)
       end
     end
@@ -281,7 +282,7 @@ the UI to hide implementation details, as shown below:
                    password_field      => profile.password,
                    pword_confirm_field => profile.confirm_password,
                    email_opt_in_check  => profile.email_opt_in
-          }
+        }
         populate_data_fields(fields)
         sign_up_button.click
       end
@@ -502,6 +503,7 @@ With TestCentricity, all UI elements are based on the `UIElement` class, and inh
     element.displayed?
     element.obscured?
     element.focused?
+    element.required?
     element.content_editable?
     element.get_value
     element.count
@@ -568,9 +570,10 @@ interacted with.
 
 The `PageObject.populate_data_fields` and `PageSection.populate_data_fields` methods support the entry of test data into a collection of
 `UIElements`. The `populate_data_fields` method accepts a hash containing key/hash pairs of `UIElements` and their associated data to be
-entered. Data values must be in the form of a `String` for `textfield` and `selectlist` controls. For `checkbox` and `radio` controls, data
-must either be a `Boolean` or a `String` that evaluates to a `Boolean` value (Yes, No, 1, 0, true, false). For `section` objects, data values
-must be a `String`, and the `section` object must have a `set` method defined.
+entered. Data values must be in the form of a `String` for `textfield`, `selectlist`, and `filefield` controls. For `checkbox` and `radio`
+controls, data must either be a `Boolean` or a `String` that evaluates to a `Boolean` value (Yes, No, 1, 0, true, false). For `range` controls,
+data must be an `Integer`. For `input(type='color')` color picker controls, which are specified as a `textfield`, data must be in the form
+of a hex color `String`. For `section` objects, data values must be a `String`, and the `section` object must have a `set` method defined.
 
 The `populate_data_fields` method verifies that data attributes associated with each `UIElement` is not `nil` or `empty` before attempting to
 enter data into the `UIElement`.
@@ -633,6 +636,14 @@ The `verify_ui_states` method supports the following property/state pairs:
     :class             String
     :value or :caption String
     :attribute         Hash
+    :style             String
+    :tabindex          Integer
+    :required          Boolean
+
+**Pages:**
+
+    :secure Boolean
+    :title  String
 
 **Text Fields:**
 
@@ -645,12 +656,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
@@ -670,6 +686,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**
 
@@ -705,8 +723,6 @@ The `verify_ui_states` method supports the following property/state pairs:
 
 The `verify_ui_states` method supports the following ARIA accessibility property/state pairs:
 
-**All Objects:**
-
     :aria_label           String
     :aria_disabled        Boolean
     :aria_labelledby      String
@@ -737,8 +753,10 @@ 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 } }
@@ -843,6 +861,126 @@ Baseline translation strings are stored in `.yml` files in the `config/locales/`
         └── 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">
+
+
+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
 
@@ -1040,7 +1178,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
@@ -1155,7 +1293,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
@@ -1198,10 +1336,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
@@ -1217,7 +1357,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 `iOS`                                                                                                                                                  |
 | `APP_BROWSER`              | Must be set to `Safari`                                                                                                                                               |
-| `APP_VERSION`              | Must be set to `15.2`, `14.5`, or which ever iOS version you wish to run within the XCode Simulator                                                                   |
+| `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)                                                                                                     |
@@ -1238,12 +1378,12 @@ Once your test environment is properly configured, the following **Environment V
 
 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 secutity enabled. 
+Appium Server GUI app. A security violation error will occur without relaxed security enabled. 
 
-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 Chrome or Android browsers on Android Studio Virtual Device emulators
+#### 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)
@@ -1260,7 +1400,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`                                                                                    |
@@ -1272,16 +1412,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
 
-### 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
+Refer to **section 8.6 (Using Browser specific Profiles in cucumber.yml)** below.
+
+
+### 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
@@ -1290,24 +1468,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.
@@ -1324,43 +1502,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
 
@@ -1376,24 +1554,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`)       |
@@ -1499,17 +1677,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 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 %>
+    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)"
 
 
     #==============
@@ -1627,38 +1813,37 @@ 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.4 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:
 
-The following command specifies that Cucumber will run tests against a remotely hosted Safari web browser running on an OS X Mojave
-virtual machine on the BrowserStack service:
+    cucumber -p ipad_pro_12_15_sim -p landscape -p run_appium
 
-    cucumber -p bs_safari_mojave
- 
 
-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:
+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_iphone6_plus -p landscape
+    cucumber -p bs_safari_monterey