Merge pull request #50 from csf-dev/49-customize-options

Resolve #49 - add options customization and fix build on Linux

Author: craigfowler

.appveyor.yml

@@ -1,11 +1,40 @@
-image: Visual Studio 2022
+environment:
+    matrix:
+        - APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2022
+          JAVA_HOME: C:\Program Files\Java\jdk17
+        - APPVEYOR_BUILD_WORKER_IMAGE: Ubuntu2204
+          JAVA_HOME: /usr/lib/jvm/jdk15
+
+skip_branch_with_pr: true
+
+# A note/reminder for readers: Script items prefixed "cmd:" are executed on Windows-only environments.
+# Items with no prefix (or "ps:" prefix) are run on all environments (Windows & Linux)
+
 version: '{branch}-{build}'
+
 init:
-- cmd: git config --global core.autocrlf true
+    - cmd: git config --global core.autocrlf true
+
+install:
+    # This was taken from https://stackoverflow.com/questions/60304251/unable-to-open-x-display-when-trying-to-run-google-chrome-on-centos-rhel-7-5
+    # It's the minimum dependencies for running Chrome in a headless environment on Linux
+    - sh: |
+        sudo apt-get update
+        sudo apt install -y xorg xvfb gtk2-engines-pixbuf dbus-x11 xfonts-base xfonts-100dpi xfonts-75dpi xfonts-cyrillic xfonts-scalable
+
 before_build:
-    - dotnet tool update -g docfx
+    - dotnet --version
+    - dotnet restore --verbosity m
+    - dotnet clean
+    - cmd: dotnet tool update -g docfx
+    # Activate Xvfb and export a display so that Chrome can run in Linux
+    - sh: |
+        Xvfb -ac :99 -screen 0 1280x1024x16 &
+        export DISPLAY=:99
+
 build_script:
     - dotnet build
-    - docfx CSF.Extensions.WebDriver.Docs\docfx.json
+    - cmd: docfx CSF.Extensions.WebDriver.Docs\docfx.json
+
 test_script:
     - dotnet test

CSF.Extensions.WebDriver.Tests/CSF.Extensions.WebDriver.Tests.csproj

@@ -24,7 +24,10 @@
     <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="6.0.0" />
     <PackageReference Include="Microsoft.Extensions.Logging" Version="6.0.0" />
     <!-- Floating version should keep ChromeDriver up to date with the browser on the OS.  See #47 for more info. -->
-    <PackageReference Include="Selenium.WebDriver.ChromeDriver" Version="*" />
+    <PackageReference Include="Selenium.WebDriver.ChromeDriver" Version="*" Condition="'$(CI_LINUX)' != 'true'" />
+    <!-- AppVeyor Linux builds use a fixed Chrome version, this driver version must match it; note that
+         this might change over time (an will need to be manually kept in-sync) as they upgrade their CI images -->
+    <PackageReference Include="Selenium.WebDriver.ChromeDriver" Version="127.0.6533.9900" Condition="'$(CI_LINUX)' == 'true'" />
   </ItemGroup>
 
   <ItemGroup>

CSF.Extensions.WebDriver.Tests/Factories/SampleCustomizer.cs

@@ -0,0 +1,8 @@
+using OpenQA.Selenium.Chrome;
+
+namespace CSF.Extensions.WebDriver.Factories;
+
+public class SampleCustomizer : ICustomizesOptions<ChromeOptions>
+{
+    public void CustomizeOptions(ChromeOptions options) { /* Intentional no-op */ }
+}

CSF.Extensions.WebDriver.Tests/Factories/WebDriverCreationConfigureOptionsTests.cs

@@ -121,6 +121,19 @@ public async Task ConfigureShouldBeAbleToGetSelectedConfigWhenThereIsOnlyOnePres
 
         Assert.That(options.GetSelectedConfiguration()?.DriverType, Is.EqualTo("ChromeDriver"));
     }
+
+    [Test,AutoMoqData]
+    public async Task ConfigureShouldBeAbleToAddACustomizerToSomeOptions([StandardTypes] IGetsWebDriverAndOptionsTypes typeProvider)
+    {
+        var options = await GetOptionsAsync(typeProvider,
+@"{
+    ""DriverConfigurations"": {
+        ""Test"": { ""DriverType"": ""ChromeDriver"", ""OptionsCustomizerType"": ""CSF.Extensions.WebDriver.Factories.SampleCustomizer, CSF.Extensions.WebDriver.Tests"" }
+    }
+}");
+
+        Assert.That(options.GetSelectedConfiguration()?.OptionsCustomizer, Is.InstanceOf<SampleCustomizer>());
+    }
 
     [Test,AutoMoqData]
     public async Task ConfigureShouldBeAbleToGetSelectedConfigWhenASelectedConfigIsNamed([StandardTypes] IGetsWebDriverAndOptionsTypes typeProvider)

CSF.Extensions.WebDriver.Tests/Factories/WebDriverFromOptionsFactoryTests.cs

@@ -33,4 +33,31 @@ public void GetWebDriverShouldCustomiseDriverOptionsWithCallbackWhenItIsSpecifie
         using var driver = sut.GetWebDriver(options, o => o.AddAdditionalOption("Foo", "Bar")).WebDriver;
         Assert.That(driverOptions.ToCapabilities()["Foo"], Is.EqualTo("Bar"));
     }
+
+    [Test,AutoMoqData]
+    public void GetWebDriverShouldCustomiseDriverFromCustomizerInstanceIfSpecified([StandardTypes] IGetsWebDriverAndOptionsTypes typeProvider,
+                                                                                    WebDriverFromOptionsFactory sut)
+    {
+        var driverOptions = new ChromeOptions();
+        var customizer = new AppveyorLinuxChromeCustomizer();
+        var options = new WebDriverCreationOptions
+        {
+            DriverType = nameof(ChromeDriver),
+            OptionsFactory = () => driverOptions,
+            OptionsCustomizer = customizer,
+        };
+
+        using var driver = sut.GetWebDriver(options);
+        Assert.That(customizer.IsCustomized, Is.True);
+    }
+
+    public class AppveyorLinuxChromeCustomizer : ICustomizesOptions<ChromeOptions>
+    {
+        public bool IsCustomized { get; private set; }
+
+        public void CustomizeOptions(ChromeOptions options)
+        {
+            IsCustomized = true;
+        }
+    }
 }

CSF.Extensions.WebDriver/CSF.Extensions.WebDriver.csproj

@@ -3,7 +3,7 @@
   <PropertyGroup>
     <TargetFrameworks>netstandard2.0;net8.0;net462</TargetFrameworks>
     <RootNamespace>CSF.Extensions.WebDriver</RootNamespace>
-    <DocumentationFile>$(OutputPath)\$(AssemblyName).xml</DocumentationFile>
+    <DocumentationFile>$(MSBuildProjectDirectory)\bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
     <VersionPrefix>2.0.0</VersionPrefix>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>

CSF.Extensions.WebDriver/Factories/ICustomizesOptions.cs

@@ -0,0 +1,33 @@
+using OpenQA.Selenium;
+
+namespace CSF.Extensions.WebDriver.Factories
+{
+    /// <summary>
+    /// An object which can customize the options for a web driver before they are used to create the <see cref="IWebDriver"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Implementations of this interface are rarely required. They are used to customize the options for creating a web driver
+    /// after <see cref="WebDriverCreationOptions.OptionsFactory"/> has created the options instance but before it is used to
+    /// create the web driver.
+    /// </para>
+    /// <para>
+    /// This is useful when you need to customize the options for a web driver in a way which is not supported by the binding from
+    /// a configuration file.  For example, some web driver options do not provide property getters/setters but must be configured
+    /// using methods.  In this case you can implement this interface with a class to customize the options as required.
+    /// </para>
+    /// <para>
+    /// The implementation of this interface should be specified via the <see cref="WebDriverCreationOptions.OptionsCustomizer"/>
+    /// property.  This will instantiate the customizer and call the <see cref="CustomizeOptions"/> method before the web driver is
+    /// created.
+    /// </para>
+    /// </remarks>
+    public interface ICustomizesOptions<in TOptions> where TOptions : DriverOptions
+    {
+        /// <summary>
+        /// Customizes the options for a web driver.
+        /// </summary>
+        /// <param name="options">The WebDriver options.</param>
+        void CustomizeOptions(TOptions options);
+    }
+}

CSF.Extensions.WebDriver/Factories/WebDriverCreationConfigureOptions.cs

@@ -123,6 +123,21 @@ WebDriverCreationOptions GetDriverConfiguration(IConfigurationSection configurat
                 return null;
             }
 
+            var customizerTypeName = configuration.GetValue<string>("OptionsCustomizerType");
+            try
+            {
+                creationOptions.OptionsCustomizer = GetOptionsCustomizer(optionsType, customizerTypeName);
+            }
+            catch(Exception e)
+            {
+                logger.LogError(e,
+                                "An unexpected error occurred binding the {OptionsCustomizer} type {CustomizerType}; the configuration '{ConfigKey}' will be omitted.",
+                                nameof(WebDriverCreationOptions.OptionsCustomizer),
+                                customizerTypeName,
+                                configuration.Key);
+                return null;
+            }
+
             return creationOptions;
         }
 
@@ -136,6 +151,19 @@ static Func<DriverOptions> GetOptions(Type optionsType, IConfigurationSection co
             };
         }
 
+        static object GetOptionsCustomizer(Type optionsType, string customizerTypeName)
+        {
+            if(string.IsNullOrWhiteSpace(customizerTypeName)) return null;
+            var customizerType = Type.GetType(customizerTypeName, true);
+
+            if(!typeof(ICustomizesOptions<>).MakeGenericType(optionsType).IsAssignableFrom(customizerType))
+                throw new ArgumentException($"The specified customizer type must implement {nameof(ICustomizesOptions<DriverOptions>)}<{optionsType.Name}>.", nameof(customizerTypeName));
+            if(customizerType.GetConstructor(Type.EmptyTypes) == null)
+                throw new ArgumentException($"The specified customizer type must have a public parameterless constructor.", nameof(customizerTypeName));
+            
+            return Activator.CreateInstance(customizerType);
+        }
+
         /// <summary>
         /// Initialises a new instance of <see cref="WebDriverCreationConfigureOptions"/>.
         /// </summary>

CSF.Extensions.WebDriver/Factories/WebDriverCreationOptions.cs

@@ -94,29 +94,57 @@ public class WebDriverCreationOptions
         public string GridUrl { get; set; }
 
         /// <summary>
-        /// Gets or sets a factory object which can create instances of WebDriver options, to be provided to the WebDriver implementation.
+        /// Gets or sets a function which creates the object which derives from <see cref="DriverOptions"/>, used as the creation options for the <see cref="IWebDriver"/>.
         /// </summary>
         /// <remarks>
         /// <para>
+        /// In the most common scenario - providing WebDriver options from a JSON configuration file such as <c>appsettings.json</c> - this property is bound
+        /// from a configuration key named <c>Options</c>, rather than "OptionsFactory".  In a configuration file, the options are specified as a simple
+        /// JSON object. However, after binding to this property this becomes a factory function instead.  That is because of two factors:
+        /// </para>
+        /// <list type="bullet">
+        /// <item><description>Instances of types which derive from <see cref="DriverOptions"/> are not reusable and should not be shared between WebDriver instances</description></item>
+        /// <item><description>This WebDriver factory framework must be capable of creating multiple <see cref="IWebDriver"/> instances from one configuration, thus
+        /// requiring many options instances</description></item>
+        /// When bound from a configuration file, the options object which would be returned from this factory function will have properties set
+        /// as specified in that configuration.
+        /// </list>
+        /// <para>
         /// The return value of this function must be an object of an appropriate type to match the implementation of <see cref="IWebDriver"/>
         /// that is selected, via <see cref="DriverType"/>.
-        /// When deserializing this value from configuration (such as an <c>appsettings.json</c> file), the <see cref="OptionsType"/>
-        /// will be used to select the appropriate polymorphic type to which the configuration should be bound.
-        /// For local WebDriver implementations which are shipped with Selenium, the options type need not be specified explicitly;
-        /// it will be inferred from the chosen driver type.
+        /// If this value was bound from a configuration file then the generated factory function will automatically instantiate an instance of either:
         /// </para>
+        /// <list type="bullet">
+        /// <item><description>The options type specified in the configuration file, if <see cref="OptionsType"/> is set</description></item>
+        /// <item><description>The options type which is inferred from the <see cref="DriverType"/>, if <see cref="OptionsType"/> is not set.
+        /// See the documentation for <see cref="OptionsType"/> for more information</description></item>
+        /// </list>
+        /// </remarks>
+        public Func<DriverOptions> OptionsFactory { get; set; }
+
+        /// <summary>
+        /// An optional object which implements <see cref="ICustomizesOptions{TOptions}"/> for the corresponding <see cref="DriverOptions"/>
+        /// type for the <see cref="DriverType"/>/<see cref="OptionsType"/>.
+        /// </summary>
+        /// <remarks>
         /// <para>
-        /// This option is provided as a factory, rather than an instance of <see cref="DriverOptions"/> because it will create options
-        /// instances for - potentially - many usages throughout the application/test lifetime. It is a poor design choice to use a single
-        /// options instance for every one of the WebDriver instances which will be used. In some cases, this would cause functional issues,
-        /// such as where additional per-scenario capabilities need to be injected into each options instance.
+        /// If this instance is bound from a configuration file - such as <c>appsettings.json</c> - then this property is bound from a configuration key named
+        /// <c>OptionsCustomizerType</c> rather than "OptionsCustomizer".  The value of that configuration key should be the assembly-qualified type name of
+        /// the concrete implementation of <see cref="ICustomizesOptions{TOptions}"/> which should be used to customize the options. In this scenario this type
+        /// must also have a public parameterless constructor.
         /// </para>
         /// <para>
-        /// Please note that when using Microsoft.Extensions.Configuration to bind an instance of this type, this factory function is bound
-        /// from an <see cref="IConfiguration"/> key named <c>Options</c> and not OptionsFactory as its member name might suggest.
+        /// This configuration property is rarely required. This object is used to customize the options for creating a web driver
+        /// after <see cref="OptionsFactory"/> has created the options instance but before it is used to
+        /// create the web driver.
+        /// </para>
+        /// <para>
+        /// This is useful when you need to customize the options for a web driver in a way which is not supported by the binding from
+        /// a configuration file.  For example, some web driver options do not provide property getters/setters but must be configured
+        /// using methods.  In this case you can implement this interface with a class to customize the options as required.
         /// </para>
         /// </remarks>
-        public Func<DriverOptions> OptionsFactory { get; set; }
+        public object OptionsCustomizer { get; set; }
 
         /// <summary>
         /// Unneeded except in unusual circumstances, gets or sets the name of a type which is used to construct the WebDriver instance.

CSF.Extensions.WebDriver/Factories/WebDriverFromOptionsFactory.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Linq;
+using System.Reflection;
 using Microsoft.Extensions.Logging;
 using OpenQA.Selenium;
 
@@ -10,6 +11,8 @@ namespace CSF.Extensions.WebDriver.Factories
     /// </summary>
     public class WebDriverFromOptionsFactory : ICreatesWebDriverFromOptions
     {
+        static readonly MethodInfo customizeGenericMethod = typeof(WebDriverFromOptionsFactory).GetMethod(nameof(CuztomizeOptionsGeneric), BindingFlags.NonPublic | BindingFlags.Static);
+
         readonly IGetsWebDriverAndOptionsTypes typeProvider;
         readonly ILogger logger;
 
@@ -28,12 +31,30 @@ public WebDriverAndOptions GetWebDriver(WebDriverCreationOptions options, Action
                                             nameof(options));
 
             var driverOptions = options.OptionsFactory();
+            CustomizeOptions(driverOptions, options.OptionsCustomizer);
             supplementaryConfiguration?.Invoke(driverOptions);
             var driver = (IWebDriver) Activator.CreateInstance(driverType, driverOptions);
             logger.LogInformation("Driver created via reflection: {Driver}", driver);
             return new WebDriverAndOptions(driver, driverOptions);
         }
 
+        static void CustomizeOptions(DriverOptions options, object customizer)
+        {
+            if (customizer is null) return;
+            var method = customizeGenericMethod.MakeGenericMethod(options.GetType());
+            method.Invoke(null, new[] { options, customizer });
+        }
+
+        static void CuztomizeOptionsGeneric<TOptions>(TOptions options, object customizer)
+            where TOptions : DriverOptions
+        {
+            if (!(customizer is ICustomizesOptions<TOptions> customizerInstance))
+                throw new ArgumentException($"The customizer type {customizer.GetType().FullName} does not implement {customizeGenericMethod.Name}<{typeof(TOptions).Name}>.",
+                                            nameof(customizer));
+
+            customizerInstance.CustomizeOptions(options);
+        }
+
         /// <summary>
         /// Initialises a new instance of <see cref="WebDriverFromOptionsFactory"/>.
         /// </summary>