Merge pull request #42 from csf-dev/feature/41-version2

Resolve #41 - version 2 of the library

Author: craigfowler

.appveyor.yml

@@ -1,12 +1,11 @@
-version: '{branch}-{build}'
+image: Visual Studio 2022
+version: '{branch}-{build}'
 init:
 - cmd: git config --global core.autocrlf true
 before_build:
-- cmd: Tools\Appveyor.before_build.bat
-build:
-  project: CSF.WebDriverExtras.sln
-  verbosity: normal
-test:
-  assemblies:
-    except:
-    - '**\Ploeh.AutoFixture.NUnit3.dll'
+    - dotnet tool update -g docfx
+build_script:
+    - dotnet build
+    - docfx CSF.Extensions.WebDriver.Docs\docfx.json
+test_script:
+    - dotnet test

.editorconfig

@@ -0,0 +1,4 @@
+[*.cs]
+
+# IDE0011: Add braces
+csharp_prefer_braces = when_multiline

.gitignore

@@ -1,19 +1,10 @@
 bin/
 obj/
-packages/*/*
-testrunner/
-.directory
 *.userprefs
 *.csproj.user
-.vs/
 TestResult.xml
-TestResult.formatted.xml
-*.report.txt
-Tests/Temp/
-Screenshots/
 *.log
 *.orig
-.xsp4.pid
-Backup/
-UpgradeLog.htm
 *.nupkg
+CSF.Extensions.WebDriver.Docs/_site/
+CSF.Extensions.WebDriver.Docs/api/

.travis.yml

@@ -0,0 +1,43 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"type": "dotnet",
+			"task": "build",
+			"group": {
+				"kind": "build",
+				"isDefault": true
+			},
+			"problemMatcher": [],
+			"label": "dotnet: build"
+		},
+		{
+			"group": {
+				"kind": "test",
+				"isDefault": true
+			},
+			"command": "dotnet",
+			"args": ["test"],
+			"problemMatcher": [],
+			"label": "dotnet: test"
+		},
+		{
+			"group": {
+				"kind": "build"
+			},
+			"command": "docfx",
+			"args": ["CSF.Extensions.WebDriver.Docs/docfx.json"],
+			"problemMatcher": [],
+			"label": "docfx: build"
+		},
+		{
+			"group": {
+				"kind": "build"
+			},
+			"command": "docfx",
+			"args": ["CSF.Extensions.WebDriver.Docs/docfx.json", "--serve"],
+			"problemMatcher": [],
+			"label": "docfx: serve"
+		}
+	]
+}

.vscode/tasks.json

@@ -0,0 +1,50 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "../",
+          "files": [
+            "**/*.csproj"
+          ],
+          "exclude": [
+            "docs/**",
+            "**/bin/**",
+            "**/obj/**",
+            "CSF.Extensions.WebDriver.Tests/**"
+          ]
+        }
+      ],
+      "dest": "api"
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "**/*.{md,yml}"
+        ],
+        "exclude": []
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**",
+          ".nojekyll"
+        ]
+      }
+    ],
+    "output": "../docs",
+    "template": [
+      "default",
+      "modern"
+    ],
+    "globalMetadata": {
+      "_appName": "CSF.Extensions.WebDriver",
+      "_appTitle": "CSF.Extensions.WebDriver",
+      "_enableSearch": true,
+      "pdf": false
+    }
+  }
+}

CSF.Extensions.WebDriver.Docs/.nojekyll

@@ -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/docfx.json

@@ -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/DriverIdentification.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