Selenium rewrite

.appveyor.yml

@@ -1,9 +1,11 @@
 environment:
     matrix:
-        - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2022
-          JAVA_HOME: C:\Program Files\Java\jdk17
+        #- APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2022
+        #  JAVA_HOME: C:\Program Files\Java\jdk17
+        #  "WebDriverFactory__SelectedConfiguration": DefaultChrome
         - APPVEYOR_BUILD_WORKER_IMAGE: Ubuntu2204
           JAVA_HOME: /usr/lib/jvm/jdk15
+          "WebDriverFactory__SelectedConfiguration": AppVeyorLinuxChrome
 
 skip_branch_with_pr: true
 
@@ -26,17 +28,16 @@ before_build:
     - dotnet --version
     - dotnet restore --verbosity m
     - dotnet clean
-    - cmd: >
-        IF NOT DEFINED APPVEYOR_PULL_REQUEST_HEAD_REPO_BRANCH (SET BranchName=%APPVEYOR_REPO_BRANCH%)
-        ELSE (SET BranchName=%APPVEYOR_PULL_REQUEST_HEAD_REPO_BRANCH%)
+    - cmd: Tools\appveyor-setup-env.bat
     - cmd: >
         dotnet-sonarscanner begin 
         /k:"csf-dev_CSF.Screenplay"
         /v:AppVeyor_build_%APPVEYOR_BUILD_NUMBER%
         /o:craigfowler-github
         /d:sonar.host.url=https://sonarcloud.io
         /d:sonar.token=%SONARCLOUD_SECRET_KEY%
-        /d:sonar.branch.name=%BranchName%
+        /d:%BranchParam%=%BranchName%
+        %PRParam%
         /d:sonar.javascript.lcov.reportPaths=%APPVEYOR_BUILD_FOLDER%\CSF.Screenplay.JsonToHtmlReport.Template\src\TestResults\lcov.info
         /s:%APPVEYOR_BUILD_FOLDER%\.sonarqube-analysisproperties.xml
 
@@ -61,3 +62,7 @@ after_test:
     - ps: if ($isWindows) { Tools\appveyor-upload-test-results.ps1 }
     - cmd: dotnet build -c Docs
     - ps: if ($isWindows) { Tools\appveyor_publish_docs.ps1 }
+
+on_finish:
+    - sh: export APPVEYOR_SSH_BLOCK=true
+    - sh: curl -sflL 'https://raw.githubusercontent.com/appveyor/ci/master/scripts/enable-ssh.sh' | bash -e -

.gitignore

@@ -4,5 +4,6 @@ obj/
 TestResults/
 Tests/**/*.feature.cs
 node_modules/
+*.orig
 /CSF.Screenplay.JsonToHtmlReport/template/
 /CSF.Screenplay.JsonToHtmlReport.Template/src/output/

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "dotnet",
+            "projectPath": "${workspaceFolder}/Tests/CSF.Screenplay.Selenium.TestWebapp/CSF.Screenplay.Selenium.TestWebapp.csproj",
+            "name": "Selenium testing web app",
+            "request": "launch",
+
+        }
+    ]
+}

CSF.Screenplay.Abstractions/Abilities/GetAssetFilePaths.cs

@@ -0,0 +1,39 @@
+using CSF.Screenplay.Reporting;
+
+namespace CSF.Screenplay.Abilities
+{
+    /// <summary>
+    /// Screenplay ability which gets the file system path for asset files generated by actors participating in the current performance.
+    /// </summary>
+    public class GetAssetFilePaths
+    {
+        readonly IGetsAssetFilePath pathProvider;
+
+        /// <summary>
+        /// Gets the file system path for the specified asset file.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// The returned file system path is an absolute path to which the asset file should be written. The path is determined by the
+        /// logic of the service <see cref="IGetsAssetFilePath"/>. This means that the final filename will not be identical to the
+        /// <paramref name="baseName"/> but will include that base name within it.
+        /// </para>
+        /// <para>
+        /// If this method returns <see langword="null" /> then the asset file should not be written to the file system.
+        /// </para>
+        /// </remarks>
+        /// <param name="baseName">A short descriptive file name fragment for the asset file, including the file extension.</param>
+        /// <returns>The asset file path.</returns>
+        /// <seealso cref="IGetsAssetFilePath.GetAssetFilePath(string)"/>
+        public string GetAssetFilePath(string baseName) => pathProvider.GetAssetFilePath(baseName);
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GetAssetFilePaths"/> class.
+        /// </summary>
+        /// <param name="pathProvider">The path provider used to get asset file paths.</param>
+        public GetAssetFilePaths(IGetsAssetFilePath pathProvider)
+        {
+            this.pathProvider = pathProvider ?? throw new System.ArgumentNullException(nameof(pathProvider));
+        }
+    }
+}

CSF.Screenplay.Abstractions/Actor.performer.cs

@@ -79,7 +79,8 @@ protected virtual ValueTask<T> PerformAsync<T>(IPerformableWithResult<T> perform
 
         PerformableException GetPerformableException(object performable, Exception ex)
         {
-            return new PerformableException($"{Name} encountered an unexpected exception whilst performing a performable of type {performable.GetType().FullName}", ex)
+
+            return new PerformableException($"{Name} encountered an unexpected exception whilst executing the performable logic of {performable.GetType().FullName}", ex)
             {
                 Performable = performable,
             };

CSF.Screenplay.Abstractions/ActorExtensions.abilities.cs

@@ -80,6 +80,42 @@ public static object GetAbility(this ICanPerform actor, Type abilityType)
                 ?? throw new InvalidOperationException($"{((IHasName) actor).Name} must have an ability of type {abilityType.FullName}");
         }
 
+        /// <summary>Tries to get the first ability which the actor has of the specified type</summary>
+        /// <param name="actor">The actor from whom to get the ability</param>
+        /// <param name="ability">If this method returns <see langword="true" /> then this exposes the strongly-typed ability; if not then this value is undefined</param>
+        /// <typeparam name="T">The type of ability desired</typeparam>
+        /// <returns><see langword="true" /> if the actor has an ability of the specified type; <see langword="false" /> if not.</returns>
+        /// <exception cref="ArgumentNullException">If the <paramref name="actor"/> is <see langword="null" /></exception>
+        /// <exception cref="ArgumentException">If the actor does not implement <see cref="IHasAbilities"/></exception>
+        public static bool TryGetAbility<T>(this ICanPerform actor, out T ability)
+        {
+            ability = default;
+            if (!TryGetAbility(actor, typeof(T), out var untypedAbility)) return false;
+            ability = (T) untypedAbility;
+            return true;
+        }
+
+        /// <summary>Gets the first ability which the actor has of the specified type</summary>
+        /// <param name="actor">The actor from whom to get the ability</param>
+        /// <param name="abilityType">The type of ability desired</param>
+        /// <param name="ability">If this method returns <see langword="true" /> then this exposes the strongly-typed ability; if not then this value is undefined</param>
+        /// <returns><see langword="true" /> if the actor has an ability of the specified type; <see langword="false" /> if not.</returns>
+        /// <exception cref="ArgumentNullException">If any parameter is <see langword="null" /></exception>
+        public static bool TryGetAbility(this ICanPerform actor, Type abilityType, out object ability)
+        {
+            if(actor is null) throw new ArgumentNullException(nameof(actor));
+            if(abilityType is null) throw new ArgumentNullException(nameof(abilityType));
+
+            if(!actor.HasAbility(abilityType))
+            {
+                ability = default;
+                return false;
+            }
+
+            ability = actor.GetAbility(abilityType);
+            return true;
+        }
+
         /// <summary>Adds an ability to the specified actor</summary>
         /// <param name="actor">The actor from whom to get the ability</param>
         /// <param name="ability">The ability to add to the actor</param>

CSF.Screenplay.Abstractions/Performances/IRelaysPerformanceEvents.cs

@@ -103,17 +103,15 @@ public interface IRelaysPerformanceEvents
         /// <summary>
         /// Invokes an event indicating that a <see cref="IPerformance"/> has begun.
         /// </summary>
-        /// <param name="performanceIdentity">The performance identity</param>
-        /// <param name="namingHierarchy">The performance's hierarchical name</param>
-        void InvokePerformanceBegun(Guid performanceIdentity, IList<IdentifierAndName> namingHierarchy);
+        /// <param name="performance">The performance</param>
+        void InvokePerformanceBegun(IPerformance performance);
 
         /// <summary>
         /// Invokes an event indicating that a <see cref="IPerformance"/> has finished.
         /// </summary>
-        /// <param name="performanceIdentity">The performance identity</param>
-        /// <param name="namingHierarchy">The performance's hierarchical name</param>
+        /// <param name="performance">The performance</param>
         /// <param name="success">A value indicating whether or not the performance was a success</param>
-        void InvokePerformanceFinished(Guid performanceIdentity, IList<IdentifierAndName> namingHierarchy, bool? success);
+        void InvokePerformanceFinished(IPerformance performance, bool? success);
 
         #endregion
 

CSF.Screenplay.Abstractions/Performances/PerformanceCompleteEventArgs.cs

@@ -34,13 +34,10 @@ public class PerformanceFinishedEventArgs : PerformanceEventArgs
         public bool? Success { get; }
 
         /// <summary>Initialises a new instance of <see cref="PerformanceEventArgs"/></summary>
-        /// <param name="performanceIdentity">The performance identity</param>
-        /// <param name="namingHierarchy">The scenario hierarchy</param>
+        /// <param name="performance">The performance.</param>
         /// <param name="success">A value indicating whether or not the scenario completed with a succeess result</param>
         /// <exception cref="ArgumentNullException">If the scenario hierarchy is <see langword="null" /></exception>
-        public PerformanceFinishedEventArgs(Guid performanceIdentity,
-                                         IReadOnlyList<IdentifierAndName> namingHierarchy,
-                                         bool? success) : base(performanceIdentity, namingHierarchy)
+        public PerformanceFinishedEventArgs(IPerformance performance, bool? success) : base(performance)
         {
             Success = success;
         }

CSF.Screenplay.Abstractions/Performances/PerformanceEventArgs.cs

@@ -10,6 +10,11 @@ namespace CSF.Screenplay.Performances
     /// <seealso cref="PerformanceScopeEventArgs"/>
     public class PerformanceEventArgs : PerformanceScopeEventArgs
     {
+        /// <summary>
+        /// Gets the <see cref="IPerformance"/> to which this event relates.
+        /// </summary>
+        public IPerformance Performance { get; }
+
         /// <summary>Gets an ordered list of identifiers which indicate the <see cref="IPerformance"/>'s name within an organisational hierarchy.</summary>
         /// <remarks>
         /// <para>
@@ -18,15 +23,14 @@ public class PerformanceEventArgs : PerformanceScopeEventArgs
         /// </remarks>
         /// <seealso cref="IPerformance"/>
         /// <seealso cref="IPerformance.NamingHierarchy"/>
-        public IReadOnlyList<IdentifierAndName> NamingHierarchy { get; }
+        public IReadOnlyList<IdentifierAndName> NamingHierarchy => Performance.NamingHierarchy;
 
         /// <summary>Initialises a new instance of <see cref="PerformanceEventArgs"/></summary>
-        /// <param name="performanceIdentity">The performance identity</param>
-        /// <param name="namingHierarchy">The screenplay naming hierarchy</param>
+        /// <param name="performance">The performance</param>
         /// <exception cref="ArgumentNullException">If the scenario hierarchy is <see langword="null" /></exception>
-        public PerformanceEventArgs(Guid performanceIdentity, IReadOnlyList<IdentifierAndName> namingHierarchy) : base(performanceIdentity)
+        public PerformanceEventArgs(IPerformance performance) : base(performance.PerformanceIdentity)
         {
-            NamingHierarchy = namingHierarchy ?? throw new ArgumentNullException(nameof(namingHierarchy));
+            Performance = performance;
         }
     }
 }

CSF.Screenplay.Abstractions/Reporting/IGetsAssetFilePath.cs

@@ -0,0 +1,29 @@
+namespace CSF.Screenplay.Reporting
+{
+    /// <summary>
+    /// A service which gets a filesystem path to which Screenplay asset files should be written, if they are to be written at all.
+    /// </summary>
+    public interface IGetsAssetFilePath
+    {
+        /// <summary>
+        /// Gets the filesystem path to which an asset file should be written.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// If reporting is disabled, for the same reasons as <see cref="IGetsReportPath.GetReportPath"/> would return <see langword="null" />,
+        /// then this method will also return <see langword="null" />.
+        /// In that case, reporting is disabled and no asset files should be written to the file system.
+        /// </para>
+        /// <para>
+        /// If reporting is enabled, then this method should return an absolute file system path to which an asset file should be written,
+        /// where the asset has the specified 'base name'.  That base name should be a short filename fragment which describes the asset.
+        /// This file name will be embellished with other information by this method, such as to ensure that the file name is unique within
+        /// the current Screenplay run.
+        /// </para>
+        /// </remarks>
+        /// <param name="baseName">A short &amp; descriptive filename fragment, which includes the file extension but no path information</param>
+        /// <returns>An absolute file system path at which the asset file should be saved, or a <see langword="null" /> reference indicating that
+        /// the asset file should not be saved.</returns>
+        string GetAssetFilePath(string baseName);
+    }
+}

CSF.Screenplay.Abstractions/Reporting/IGetsReportPath.cs

@@ -0,0 +1,26 @@
+namespace CSF.Screenplay.Reporting
+{
+    /// <summary>
+    /// A service which gets the path to which the Screenplay report should be written.
+    /// </summary>
+    public interface IGetsReportPath
+    {
+        /// <summary>
+        /// Gets the path to which the report should be written.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// If the returned path is <see langword="null" /> then Screenplay's reporting functionality should be disabled and no report should be written.
+        /// Otherwise, implementations of this interface should return an absolute file system path to which the report should be written.
+        /// This path must be writable by the executing process.
+        /// </para>
+        /// <para>
+        /// Reporting could be disabled if either the Screenplay Options report path is <see langword="null" /> or a whitespace-only string, or if the path
+        /// indicated by those options is not writable.
+        /// </para>
+        /// </remarks>
+        /// <returns>The report path.</returns>
+        string GetReportPath();
+    }    
+}
+

CSF.Screenplay.Docs/docfx.json

@@ -9,8 +9,8 @@
             "docs/**",
             "**/bin/**",
             "**/obj/**",
-            "Tests_old/**",
-            "Tests/**"
+            "Tests/**",
+            "*_old/**"
           ]
         }
       ],

CSF.Screenplay.JsonToHtmlReport/CSF.Screenplay.JsonToHtmlReport.csproj

@@ -7,6 +7,9 @@
     <NoWarn>NU1903,NU1902</NoWarn>
     <RootNamespace>CSF.Screenplay.JsonToHtmlReport</RootNamespace>
     <DocumentationFile>$(MSBuildProjectDirectory)\bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
+    <!-- It's true that netcoreapp3.1 is already long out of support and net6.0 will be soon, but these are only here for backwards compatibility.
+         This project is multi-targeted and includes up-to-date TFMs -->
+    <CheckEolTargetFramework>false</CheckEolTargetFramework>
   </PropertyGroup>
 
   <ItemGroup>

CSF.Screenplay.Selenium.BrowserFlags.Tests_old/AutoMoqDataAttribute.cs

@@ -0,0 +1,14 @@
+using System;
+using Ploeh.AutoFixture;
+using Ploeh.AutoFixture.AutoMoq;
+using Ploeh.AutoFixture.NUnit3;
+
+namespace CSF.Screenplay.Selenium.Tests
+{
+  public class AutoMoqDataAttribute : AutoDataAttribute
+  {
+    public AutoMoqDataAttribute() : base(new Fixture().Customize(new AutoMoqCustomization()))
+    {
+    }
+  }
+}