WIP #41 - update docco

Provisionally, this is all done now.

Author: craigfowler

.vscode/tasks.json

@@ -26,7 +26,7 @@
 				"kind": "build"
 			},
 			"command": "docfx",
-			"args": ["build", "CSF.Extensions.WebDriver.Docs/docfx.json"],
+			"args": ["CSF.Extensions.WebDriver.Docs/docfx.json"],
 			"problemMatcher": [],
 			"label": "docfx: build"
 		},
@@ -35,7 +35,7 @@
 				"kind": "build"
 			},
 			"command": "docfx",
-			"args": ["build", "CSF.Extensions.WebDriver.Docs/docfx.json", "--serve"],
+			"args": ["CSF.Extensions.WebDriver.Docs/docfx.json", "--serve"],
 			"problemMatcher": [],
 			"label": "docfx: serve"
 		}

CSF.Extensions.WebDriver.Docs/docfx.json

@@ -8,8 +8,10 @@
             "**/*.csproj"
           ],
           "exclude": [
-            "CSF.Extensions.WebDriver.Tests/**",
-            "docs/**"
+            "docs/**",
+            "**/bin/**",
+            "**/obj/**",
+            "CSF.Extensions.WebDriver.Tests/**"
           ]
         }
       ],

CSF.Extensions.WebDriver.Docs/docs/DriverIdentification.md

@@ -0,0 +1,22 @@
+# WebDriver identification
+
+Most implementations of `IWebDriver` also implement `IHasCapabilities` and have capabilities indicating the browser name, version and platform.
+These values are strings though, which is particularly troublesome for the browser version when we need to answer questions such as _is this browser between versions X and Y?_
+
+When using [the universal WebDriver factory], the returned WebDriver is enhanced with an additional interface: [`IHasBrowserId`].
+This interface provides a get-only property of type [`BrowserId`], which in-turn provides a [`BrowserVersion`].
+This enhancement may be disabled by setting [`AddBrowserIdentification`] in the WebDriver creation options to `false`.
+
+[the universal WebDriver factory]: index.md
+[`IHasBrowserId`]: xref:CSF.Extensions.WebDriver.Identification.IHasBrowserId
+[`BrowserId`]: xref:CSF.Extensions.WebDriver.Identification.BrowserId
+[`BrowserVersion`]: xref:CSF.Extensions.WebDriver.Identification.BrowserVersion
+[`AddBrowserIdentification`]: xref:CSF.Extensions.WebDriver.Factories.WebDriverCreationOptions.AddBrowserIdentification
+
+## A note on proxies
+
+Be aware that when the WebDriver identification functionality is activated, [the WebDriver returned by the universal factory will be _a proxy object_] and not the original concrete WebDriver implementation.
+In best-practice scenarios where the WebDriver is utilised only by its interfaces this should make no difference.
+More information is available at the linked documentation above.
+
+[the WebDriver returned by the universal factory will be _a proxy object_]: Proxies.md

CSF.Extensions.WebDriver.Docs/docs/Proxies.md

@@ -0,0 +1,51 @@
+# Proxied WebDrivers
+
+Two of the functions of the universal factory require adding additional interfaces to the WebDriver:
+
+* [Browser identification]
+* [WebDriver quirks]
+
+The only sensible way to do this at runtime, without either disrupting other interfaces which were present on the WebDriver or [being forced to violate LSP], is to make use of a proxying library.
+In the case of CSF.Extensions.WebDriver, [Castle DynamicProxy] is used.
+
+What this means is that when the [universal WebDriver factory] returns a WebDriver, if either or both of the functionalities above are enabled, then the WebDriver returned will be a proxy object and not the original concrete implementation of `IWebDriver`.
+
+[Browser identification]: DriverIdentification.md
+[WebDriver quirks]: Quirks.md
+[being forced to violate LSP]: https://en.wikipedia.org/wiki/Liskov_substitution_principle
+[Castle DynamicProxy]: https://www.castleproject.org/projects/dynamicproxy/
+[universal WebDriver factory]: index.md
+
+## Consequences
+
+Take the following code as an example, the first two lines would create a minimal default local Chrome WebDriver.
+
+```csharp
+// Imagine this factory has been dependency-injected
+ICreatesWebDriverFromOptions factory;
+
+var webDriver = factory.GetWebDriver(new () { DriverType = "ChromeDriver" });
+var hasActiveDevTools = ((ChromeDriver) webDriver).HasActiveDevToolsSession;
+```
+
+_The last line of code above would crash_ with an `InvalidCastException`.
+That's because the `webDriver` object is not an instance of `ChromeDriver`, it is a proxy object wrapping that `ChromeDriver` instance.
+
+When using Selenium, and in software development in general, it is bad practice to depend upon concrete classes when interfaces are available.
+In well-written logic which depends upon only interfaces, the limitation above does not come into play.
+_Proxy WebDrivers have all of the same interfaces as the WebDriver with which they were created_ and provide the same functionality for all of them.
+Those interfaces are detected upon the WebDriver as the proxy is created, so third party WebDrivers with additional/unknown interfaces would also be supported.
+
+## Unproxying
+
+If you encounter an (unexpected) situation where the proxied WebDriver causes a problem, this library provides a mechanism of getting the original 'unproxied' WebDriver:
+
+```csharp
+var unproxied = maybeProxy.Unproxy();
+```
+
+In the example above, if `maybeProxy` was a proxied WebDriver, `unproxied` is now the original WebDriver instance which was wrapped by the proxy.
+The [`Unproxy()`] extension method is safe to use on both proxy and non-proxy WebDrivers.
+If used upon a WebDriver which is not a proxy then it simply does nothing and returns the same WebDriver instance.
+
+[`Unproxy()`]: xref:OpenQA.Selenium.WebDriverExtensions.Unproxy(OpenQA.Selenium.IWebDriver)

CSF.Extensions.WebDriver.Docs/docs/QuickStart.md

@@ -0,0 +1,78 @@
+# WebDriver quirks
+
+_There are a lot of web browsers and browser versions out there!_
+Unfortunately they do not all behave in a perfectly uniform manner; some WebDriver implementations have bugs and some just have oddities which are unique to them.
+A real (albeit now-outdated) example is that [WebDriver for Apple Safari v11 could not change the selection of an HTML `<select>` element].
+When faced with that bug, the only course of action a developer could take was to work around it.
+
+[WebDriver for Apple Safari v11 could not change the selection of an HTML `<select>` element]: https://github.com/SeleniumHQ/selenium/issues/5475#issuecomment-365082942
+
+## How the 'quirks' architecture can help
+
+Developers do not want to litter their WebDriver-consuming code with browser detection logic.
+Just like in regular web development, [browser detection is bad, feature detection is better].
+What the quirks architecture provides is an additional interface, added to WebDrivers created by [the universal WebDriver factory]: [`IHasQuirks`].
+
+WebDrivers which implement `IHasQuirks` can cross-reference their [browser identification] with source data listing which browsers are affected by which quirks.
+The result is the [`AllQuirks`] property and the following extension methods (for convenience):
+
+* [`HasQuirk(string)`]
+* [`GetQuirks()`]
+* [`GetFirstApplicableQuirk(params string［］)`]
+
+[browser detection is bad, feature detection is better]: https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing/Feature_detection
+[the universal WebDriver factory]: index.md
+[`IHasQuirks`]: xref:CSF.Extensions.WebDriver.Quirks.IHasQuirks
+[browser identification]: DriverIdentification.md
+[`AllQuirks`]: xref:CSF.Extensions.WebDriver.Quirks.IHasQuirks.AllQuirks
+
+[`HasQuirk(string)`]: xref:OpenQA.Selenium.WebDriverExtensions.HasQuirk(OpenQA.Selenium.IWebDriver,System.String)
+[`GetQuirks()`]: xref:OpenQA.Selenium.WebDriverExtensions.GetQuirks(OpenQA.Selenium.IWebDriver)
+[`GetFirstApplicableQuirk(params string［］)`]: xref:OpenQA.Selenium.WebDriverExtensions.GetFirstApplicableQuirk(OpenQA.Selenium.IWebDriver,System.String[])
+
+## The quirks source data
+
+Quirks source data may come from two sources.
+To use quirks _at least one source must be activated_ and it is recommended to enable both.
+
+* Hard-coded into an application/library
+* Supplementary configuration data
+
+The intent is that an application or library may ship with quirks information that is known at the time of writing.
+This information may be supplemented or (in part or wholly) overwritten by quirks information provided by the consumer.
+This allows consuming logic to react to changes in browser quirks (as time moves on) by adding their own quirks configuration and not needing to wait for an upstream app/library to release an updated version with new quirks source data.
+
+This library uses a simple merging algorithm to combine the hard-coded and options data-sources.
+Where the two sources list quirks that the other source does not, the resultant data will contain both quirks.
+Where the two sources list the same quirk, the Options data will _win the disagreement_, so to speak, and will shadow the hard-coded data.
+
+Developers may use this technique to update the affected browsers for a quirk or even to (effectively) remove it, by giving it an empty set of affected browsers.
+
+## Setting up quirks functionality
+
+To configure the source data you must activate it in source control.
+In the following example, `quirksData` represents data which would be hard-coded into your application/library (design-time).
+
+```csharp
+services.AddWebDriverQuirks(quirksData);
+```
+
+The [`AddWebDriverQuirks`] method is customisable with a number of parameters, most of which are not shown above.
+By default any quirks data specified in [the app Configuration], via [the Options Pattern], will be used to supplement and/or override that hard-coded data.
+The default configuration path for quirks data is `WebDriverQuirks`.
+
+Lastly, to use quirks functionality it must also be activated in the [`WebDriverCreationOptions`], via the [`AddBrowserQuirks`] property.
+
+[`AddWebDriverQuirks`]: xref:CSF.Extensions.WebDriver.ServiceCollectionExtensions.AddWebDriverQuirks(Microsoft.Extensions.DependencyInjection.IServiceCollection,CSF.Extensions.WebDriver.Quirks.QuirksData,System.Boolean,System.String)
+[the app Configuration]: https://learn.microsoft.com/en-us/dotnet/core/extensions/configuration
+[the Options Pattern]: https://learn.microsoft.com/en-us/dotnet/core/extensions/options
+[`WebDriverCreationOptions`]: xref:CSF.Extensions.WebDriver.Factories.WebDriverCreationOptions
+[`AddBrowserQuirks`]: xref:CSF.Extensions.WebDriver.Factories.WebDriverCreationOptions.AddBrowserQuirks
+
+## A note on proxies
+
+Be aware that when the WebDriver quirks functionality is activated, [the WebDriver returned by the universal factory will be _a proxy object_] and not the original concrete WebDriver implementation.
+In best-practice scenarios where the WebDriver is utilised only by its interfaces this should make no difference.
+More information is available at the linked documentation above.
+
+[the WebDriver returned by the universal factory will be _a proxy object_]: Proxies.md

CSF.Extensions.WebDriver.Docs/docs/Quirks.md

@@ -0,0 +1,85 @@
+# Universal WebDriver factory
+
+A common requirement when performing browser testing is to conduct tests using a variety of browsers.
+This helps ensure that app functionality is not reliant upon a particular browser feature or quirk and it's truly cross-browser compatible.
+The universal WebDriver factory is a configuration-driven mechanism by which WebDriver instances may be constructed.
+It is based upon Microsoft [Dependency Injection] and optionally the [Options Pattern] and [Configuration].
+
+The WebDriver factory is the mechanism by which other functionality in this library is activated.
+To begin using it, follow the three steps below.
+
+[Dependency Injection]: https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection
+[Options Pattern]: https://learn.microsoft.com/en-us/dotnet/core/extensions/options
+[Configuration]: https://learn.microsoft.com/en-us/dotnet/core/extensions/configuration
+
+## 1. Add the factory to dependency injection
+
+It is recommended to use [`AddWebDriverFactory`] with your dependency injection configuration.
+This enables the Microsoft Options Pattern and Configuration for the WebDriver factory.
+You may alternatively use [`AddWebDriverFactoryWithoutOptionsPattern`] if you do not with to use those technologies, although some features will be unavailable to you if you choose this.
+
+```csharp
+services.AddConfiguration();
+services.AddWebDriverFactory();
+```
+
+There are overloads of `AddWebDriverFactory` available to:
+
+* Specify a non-default configuration path for the WebDriver factory options; the default is `WebDriverFactory`
+* Specify a configuration section from which to build the WebDriver factory options
+* Specify an additional configuration callback to provide extra options outside the configuration system
+
+Read the documentation for these functions (linked above) for more info.
+
+[`AddWebDriverFactory`]: xref:CSF.Extensions.WebDriver.ServiceCollectionExtensions.AddWebDriverFactory(Microsoft.Extensions.DependencyInjection.IServiceCollection,System.String,System.Action{CSF.Extensions.WebDriver.Factories.WebDriverCreationOptionsCollection})
+[`AddWebDriverFactoryWithoutOptionsPattern`]: xref:CSF.Extensions.WebDriver.ServiceCollectionExtensions.AddWebDriverFactoryWithoutOptionsPattern(Microsoft.Extensions.DependencyInjection.IServiceCollection)
+
+## 2. Include configuration for one or more WebDrivers
+
+This configuration should be written using whichever configuration mechanism you wish to use.
+Here is an example using the common `appsettings.json` format:
+
+```json
+{
+    "WebDriverFactory": {
+        "DriverConfigurations": {
+            "MyRemoteSafari": {
+                "DriverType": "RemoteWebDriver",
+                "OptionsType": "SafariOptions",
+                "GridUrl": "https://gridurl.example.com/url-path"
+            },
+            "MyLocalChrome": {
+                "DriverType": "ChromeDriver"
+            }
+        },
+        "SelectedConfiguration": "MyLocalChrome"
+    }
+}
+```
+
+You may set one of your configurations to be 'the selected default' if you wish, enabling you to use [`GetDefaultWebDriver()`].
+Do not forget that you may provide configuration from multiple sources; for example you may specify your available driver configurations in a JSON file but specify the default selected one via a command-line parameter such as:
+
+```txt
+--WebDriverFactory::SelectedConfiguration MyConfigurationName
+```
+
+> [!TIP]
+> Do not store secrets such as passwords in your configuration.
+> The methods of [`IGetsWebDriver`] and [`ICreatesWebDriverFromOptions`] provide parameters whereby secrets may be injected into the `DriverOptions` from external sources, such as environment variables.
+> This avoids the need to add secrets to source-controlled files.
+
+[`GetDefaultWebDriver()`]: xref:CSF.Extensions.WebDriver.IGetsWebDriver.GetDefaultWebDriver(System.Action{OpenQA.Selenium.DriverOptions})
+
+## 3. Inject and use the services
+
+Use dependency injection to inject an [`IGetsWebDriver`].
+Use this service to get WebDriver instances.
+
+`IGetsWebDriver` is unavailable if you used [`AddWebDriverFactoryWithoutOptionsPattern`] when setting this functionality up.
+In that case you must use [`ICreatesWebDriverFromOptions`] instead.
+This service offers the same functionality except that the consumer is responsible for specifying the [`WebDriverCreationOptions`]; they are not retrieved from Options.
+
+[`IGetsWebDriver`]: xref:CSF.Extensions.WebDriver.IGetsWebDriver
+[`ICreatesWebDriverFromOptions`]: xref:CSF.Extensions.WebDriver.Factories.ICreatesWebDriverFromOptions
+[`WebDriverCreationOptions`]: xref:CSF.Extensions.WebDriver.Factories.WebDriverCreationOptions

CSF.Extensions.WebDriver.Docs/docs/UniversalFactory.md

@@ -1,8 +1,8 @@
-- name: Quick start
-  href: QuickStart.md
 - name: Universal factory
-  href: UniversalFactory.md
+  href: index.md
 - name: Driver identification
   href: DriverIdentification.md
 - name: Quirks
   href: Quirks.md
+- name: Proxies
+  href: Proxies.md

CSF.Extensions.WebDriver.Docs/docs/index.md

@@ -11,10 +11,7 @@ This is broadly organised into three features:
 * A mechanism to [reliably identify WebDriver instances] and their version information, after they are created
 * A mechanism to ['mark WebDrivers up' with information about their quirks] which affect that browser/WebDriver/version combination
 
-To get going straight away, read [the **quick start** documentation].
-
 [Selenium WebDriver]: https://www.selenium.dev/documentation/webdriver/
-[universal WebDriver factory]: Docs/UniversalFactory.md
+[universal WebDriver factory]: Docs/index.md
 [reliably identify WebDriver instances]: Docs/DriverIdentification.md
 ['mark WebDrivers up' with information about their quirks]: Docs/Quirks.md
-[the **quick start** documentation]: Docs/QuickStart.md