WIP #49 - Add customizer to test

Author: craigfowler

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

@@ -13,6 +13,7 @@ public void GetWebDriverShouldCreateALocalChromeDriverFromAppropriateOptions([St
         {
             DriverType = nameof(ChromeDriver),
             OptionsFactory = () => new ChromeOptions(),
+            OptionsCustomizer = new AppveyorLinuxChromeCustomizer(),
         };
 
         using var driver = sut.GetWebDriver(options).WebDriver;
@@ -28,9 +29,22 @@ public void GetWebDriverShouldCustomiseDriverOptionsWithCallbackWhenItIsSpecifie
         {
             DriverType = nameof(ChromeDriver),
             OptionsFactory = () => driverOptions,
+            OptionsCustomizer = new AppveyorLinuxChromeCustomizer(),
         };
 
         using var driver = sut.GetWebDriver(options, o => o.AddAdditionalOption("Foo", "Bar")).WebDriver;
         Assert.That(driverOptions.ToCapabilities()["Foo"], Is.EqualTo("Bar"));
     }
+
+    public class AppveyorLinuxChromeCustomizer : ICustomizesOptions<ChromeOptions>
+    {
+        public void CustomizeOptions(ChromeOptions options)
+        {
+            if(string.Equals(Environment.GetEnvironmentVariable("APPVEYOR"), bool.TrueString, StringComparison.InvariantCultureIgnoreCase)
+               && Environment.GetEnvironmentVariable("APPVEYOR_BUILD_WORKER_IMAGE")!.Contains("ubuntu", StringComparison.InvariantCultureIgnoreCase))
+            {
+                options.AddArgument("--no-sandbox");
+            }
+        }
+    }
 }

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, [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>