Merge pull request #270 from q2ebanking/update-switching-to-frames

Update Switching to Frames

Boa.Constrictor.Selenium/Boa.Constrictor.Selenium.csproj

@@ -2,13 +2,13 @@
 
   <PropertyGroup>
     <TargetFrameworks>netstandard2.0</TargetFrameworks>
-    <Version>4.0.0</Version>
+    <Version>4.1.0</Version>
     <Authors>Pandy Knight and the PrecisionLender SETs</Authors>
     <Company>Q2</Company>
     <Title>Boa.Constrictor.Selenium</Title>
     <Product>Boa.Constrictor.Selenium</Product>
     <Description>Boa Constrictor is the .NET Screenplay Pattern! This package is the Selenium WebDriver interaction library.</Description>
-    <Copyright>Copyright © 2020-2023 Q2 Holdings Inc.</Copyright>
+    <Copyright>Copyright © 2020-2024 Q2 Holdings Inc.</Copyright>
     <RepositoryUrl>https://github.com/q2ebanking/boa-constrictor</RepositoryUrl>
     <RepositoryType>git</RepositoryType>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Boa.Constrictor.Selenium/CHANGELOG.md

@@ -20,12 +20,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 (none)
 
 
+## [4.1.0] - 2024-01-29
+
+### Added
+- Added `SwitchFrames` property to control switching to DefaultContent first
+- Added functionality to switch into nested frames in `SwitchFrames`
+
+### Changed
+- `SwitchFrames` `Locator` property is now a list
+
+
 ## [4.0.0] - 2023-05-29
 
 ### Added
 
 - Added `SwitchFrame` Task with automatic waiting
-- Addd commented code for a potential `PerformInFrame` Task
+- Add commented code for a potential `PerformInFrame` Task
   - This one is currently exhibiting flaky errors
   - We must investigate further before releasing it officially
 

Boa.Constrictor.Selenium/Tasks/SwitchFrame.cs

@@ -1,11 +1,14 @@
-using System;
-using Boa.Constrictor.Screenplay;
+using Boa.Constrictor.Screenplay;
 using OpenQA.Selenium;
+using System;
+using System.Collections.Generic;
+using System.Linq;
 
 namespace Boa.Constrictor.Selenium
 {
     /// <summary>
     /// Switches the frame.
+    /// Start from DefaultContent by default.
     /// </summary>
     public class SwitchFrame : AbstractWebTask
     {
@@ -15,11 +18,12 @@ public class SwitchFrame : AbstractWebTask
         /// Private constructor.
         /// (Use static builder methods to construct.)
         /// </summary>
-        /// <param name="locator">The locator.</param>
-        /// <param name="useDefaultContent">If true use DefaultContent instead of the locator.</param>
-        private SwitchFrame(IWebLocator locator, bool useDefaultContent)
+        /// <param name="locators">The list of locators.</param>
+        /// <param name="useDefaultContent">If true use DefaultContent instead of the locators.</param>
+        private SwitchFrame(List<IWebLocator> locators, bool useDefaultContent)
         {
-            Locator = locator;
+            Locators = locators;
+            StartFromCurrentLocation = false;
             UseDefaultContent = useDefaultContent;
         }
 
@@ -28,12 +32,17 @@ private SwitchFrame(IWebLocator locator, bool useDefaultContent)
         #region Properties
 
         /// <summary>
-        /// The target Web element's locator.
+        /// The list of target Web element locators.
+        /// </summary>
+        public List<IWebLocator> Locators { get; }
+
+        /// <summary>
+        /// Start from current location instead of switching to DefaultContent first.
         /// </summary>
-        public IWebLocator Locator { get; }
+        public bool StartFromCurrentLocation { get; set; }
 
         /// <summary>
-        /// The DefaultContent is used.
+        /// Switch to DefaultContent instead of a target frame.
         /// </summary>
         public bool UseDefaultContent { get; }
 
@@ -46,13 +55,31 @@ private SwitchFrame(IWebLocator locator, bool useDefaultContent)
         /// </summary>
         /// <param name="locator">The locator.</param>
         /// <returns></returns>
-        public static SwitchFrame To(IWebLocator locator) => new SwitchFrame(locator, false);
+        public static SwitchFrame To(IWebLocator locator) =>
+            new SwitchFrame(new List<IWebLocator> { locator }, false);
 
         /// <summary>
         /// Constructs the Task object for DefaultContent.
         /// </summary>
         /// <returns></returns>
-        public static SwitchFrame ToDefaultContent() => new SwitchFrame(null, true);
+        public static SwitchFrame ToDefaultContent() => new SwitchFrame(new List<IWebLocator>(), true);
+
+        /// <summary>
+        /// Constructs the Task object for the given locator list.
+        /// </summary>
+        /// <param name="locators">The list of locators.</param>
+        /// <returns></returns>
+        public static SwitchFrame ToNested(List<IWebLocator> locators) => new SwitchFrame(locators, false);
+
+        /// <summary>
+        /// Sets the Task to start from current location instead of DefaultContent.
+        /// </summary>
+        /// <returns></returns>
+        public SwitchFrame AndStartFromCurrentLocation()
+        {
+            StartFromCurrentLocation = true;
+            return this;
+        }
 
         #endregion
 
@@ -65,12 +92,16 @@ private SwitchFrame(IWebLocator locator, bool useDefaultContent)
         /// <param name="driver">The WebDriver.</param>
         public override void PerformAs(IActor actor, IWebDriver driver)
         {
-            driver.SwitchTo().DefaultContent();
+            if (UseDefaultContent || !StartFromCurrentLocation)
+                driver.SwitchTo().DefaultContent();
 
             if (!UseDefaultContent)
             {
-                actor.WaitsUntil(Existence.Of(Locator), IsEqualTo.True());
-                driver.SwitchTo().Frame(Locator.FindElement(driver));
+                foreach (IWebLocator locator in Locators)
+                {
+                    actor.WaitsUntil(Existence.Of(locator), IsEqualTo.True());
+                    driver.SwitchTo().Frame(locator.FindElement(driver));
+                }
             }
         }
 
@@ -80,24 +111,25 @@ public override void PerformAs(IActor actor, IWebDriver driver)
         /// <param name="obj">The other object.</param>
         public override bool Equals(object obj) =>
             obj is SwitchFrame frame &&
-            Locator.Equals(frame.Locator) &&
+            Locators.SequenceEqual(frame.Locators) &&
+            StartFromCurrentLocation == frame.StartFromCurrentLocation &&
             UseDefaultContent == frame.UseDefaultContent;
 
         /// <summary>
         /// Gets a unique hash code for this interaction.
         /// </summary>
         /// <returns></returns>
         public override int GetHashCode() =>
-            HashCode.Combine(GetType(), Locator, UseDefaultContent);
+            HashCode.Combine(GetType(), Locators, StartFromCurrentLocation, UseDefaultContent);
 
         /// <summary>
         /// Returns a description of the Task.
         /// </summary>
         /// <returns></returns>
-        public override string ToString() => 
-            UseDefaultContent 
+        public override string ToString() =>
+            UseDefaultContent
                 ? "switch frame to DefaultContent"
-                : $"switch frame to '{Locator.Description}'";
+                : $"switch frame to '{Locators.Last().Description}'";
 
         #endregion
     }