Adding ability to detect spec-compliant capabilities in .NET

This commit updates the .NET `DesiredCapabilities` class to allow the
language bindings to construct the correct type of payload for the new
session command before sending the command to the remote end. This will
remove the burden from intermediate nodes (like the Java standalone server
and grid) from incorrectly parsing a driver using the legacy protocol
dialect (Edge, Safari, Chrome) and throwing an error on session creation.

Additionally, this commit also deprecates the static methods on the
`DesiredCapability` classes for specific browsers in .NET. For over a
year, the guidance for .NET users has been to use a browser-specific
options class (`FirefoxOptions`, `InternetExplorerOptions`, etc.) to
set specific capabilities for the driver to be instaniated. To use the
options classes with the Java standalone remote server or grid, call
the `ToCapabilities` method on the options object.

Fixes issue #4443.

Author: jimevans

dotnet/src/webdriver/Remote/DesiredCapabilities.cs

@@ -26,9 +26,10 @@ namespace OpenQA.Selenium.Remote
     /// Class to Create the capabilities of the browser you require for <see cref="IWebDriver"/>.
     /// If you wish to use default values use the static methods
     /// </summary>
-    public class DesiredCapabilities : ICapabilities
+    public class DesiredCapabilities : ICapabilities, ISpecificationCompliant
     {
         private readonly Dictionary<string, object> capabilities = new Dictionary<string, object>();
+        private bool isSpecCompliant = true;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="DesiredCapabilities"/> class
@@ -162,6 +163,15 @@ public bool AcceptInsecureCerts
             }
         }
 
+        /// <summary>
+        /// Gets or sets a value indicating whether this set of capabilities is compliant with the W3C WebDriver specification.
+        /// </summary>
+        bool ISpecificationCompliant.IsSpecificationCompliant
+        {
+            get { return this.isSpecCompliant; }
+            set { this.isSpecCompliant = value; }
+        }
+
         /// <summary>
         /// Gets the internal capabilities dictionary.
         /// </summary>
@@ -174,6 +184,7 @@ internal Dictionary<string, object> CapabilitiesDictionary
         /// Method to return a new DesiredCapabilities using defaults
         /// </summary>
         /// <returns>New instance of DesiredCapabilities for use with Firefox</returns>
+        [Obsolete("Use the FirefoxOptions class to set capabilities for use with Firefox. For use with the Java remote server or grid, use the ToCapabilites method of the FirefoxOptions class.")]
         public static DesiredCapabilities Firefox()
         {
             DesiredCapabilities dc = new DesiredCapabilities("firefox", string.Empty, new Platform(PlatformType.Any));
@@ -187,13 +198,16 @@ public static DesiredCapabilities Firefox()
         /// <returns>New instance of DesiredCapabilities for use with Firefox</returns>
         public static DesiredCapabilities PhantomJS()
         {
-            return new DesiredCapabilities("phantomjs", string.Empty, new Platform(PlatformType.Any));
+            DesiredCapabilities dc = new DesiredCapabilities("phantomjs", string.Empty, new Platform(PlatformType.Any));
+            dc.isSpecCompliant = false;
+            return dc;
         }
 
         /// <summary>
         /// Method to return a new DesiredCapabilities using defaults
         /// </summary>
         /// <returns>New instance of DesiredCapabilities for use with Internet Explorer</returns>
+        [Obsolete("Use the InternetExplorerOptions class to set capabilities for use with Internet Explorer. For use with the Java remote server or grid, use the ToCapabilites method of the InternetExplorerOptions class.")]
         public static DesiredCapabilities InternetExplorer()
         {
             return new DesiredCapabilities("internet explorer", string.Empty, new Platform(PlatformType.Windows));
@@ -203,9 +217,12 @@ public static DesiredCapabilities InternetExplorer()
         /// Method to return a new DesiredCapabilities using defaults
         /// </summary>
         /// <returns>New instance of DesiredCapabilities for use with Microsoft Edge</returns>
+        [Obsolete("Use the EdgeOptions class to set capabilities for use with Edge. For use with the Java remote server or grid, use the ToCapabilites method of the EdgeOptions class.")]
         public static DesiredCapabilities Edge()
         {
-            return new DesiredCapabilities("MicrosoftEdge", string.Empty, new Platform(PlatformType.Windows));
+            DesiredCapabilities dc = new DesiredCapabilities("MicrosoftEdge", string.Empty, new Platform(PlatformType.Windows));
+            dc.isSpecCompliant = false;
+            return dc;
         }
 
         /// <summary>
@@ -214,7 +231,9 @@ public static DesiredCapabilities Edge()
         /// <returns>New instance of DesiredCapabilities for use with HTMLUnit</returns>
         public static DesiredCapabilities HtmlUnit()
         {
-            return new DesiredCapabilities("htmlunit", string.Empty, new Platform(PlatformType.Any));
+            DesiredCapabilities dc = new DesiredCapabilities("htmlunit", string.Empty, new Platform(PlatformType.Any));
+            dc.isSpecCompliant = false;
+            return dc;
         }
 
         /// <summary>
@@ -225,13 +244,15 @@ public static DesiredCapabilities HtmlUnitWithJavaScript()
         {
             DesiredCapabilities dc = new DesiredCapabilities("htmlunit", string.Empty, new Platform(PlatformType.Any));
             dc.SetCapability(CapabilityType.IsJavaScriptEnabled, true);
+            dc.isSpecCompliant = false;
             return dc;
         }
 
         /// <summary>
         /// Method to return a new DesiredCapabilities using defaults
         /// </summary>
         /// <returns>New instance of DesiredCapabilities for use with iPhone</returns>
+        [Obsolete("Selenium no longer provides an iOS device driver.")]
         public static DesiredCapabilities IPhone()
         {
             return new DesiredCapabilities("iPhone", string.Empty, new Platform(PlatformType.Mac));
@@ -241,6 +262,7 @@ public static DesiredCapabilities IPhone()
         /// Method to return a new DesiredCapabilities using defaults
         /// </summary>
         /// <returns>New instance of DesiredCapabilities for use with iPad</returns>
+        [Obsolete("Selenium no longer provides an iOS device driver.")]
         public static DesiredCapabilities IPad()
         {
             return new DesiredCapabilities("iPad", string.Empty, new Platform(PlatformType.Mac));
@@ -250,17 +272,20 @@ public static DesiredCapabilities IPad()
         /// Method to return a new DesiredCapabilities using defaults
         /// </summary>
         /// <returns>New instance of DesiredCapabilities for use with Chrome</returns>
+        [Obsolete("Use the ChromeOptions class to set capabilities for use with Chrome. For use with the Java remote server or grid, use the ToCapabilites method of the ChromeOptions class.")]
         public static DesiredCapabilities Chrome()
         {
             // This is strangely inconsistent.
             DesiredCapabilities dc = new DesiredCapabilities("chrome", string.Empty, new Platform(PlatformType.Any));
+            dc.isSpecCompliant = false;
             return dc;
         }
 
         /// <summary>
         /// Method to return a new DesiredCapabilities using defaults
         /// </summary>
         /// <returns>New instance of DesiredCapabilities for use with Android</returns>
+        [Obsolete("Selenium no longer provides an Android device driver.")]
         public static DesiredCapabilities Android()
         {
             return new DesiredCapabilities("android", string.Empty, new Platform(PlatformType.Android));
@@ -270,18 +295,24 @@ public static DesiredCapabilities Android()
         /// Method to return a new DesiredCapabilities using defaults
         /// </summary>
         /// <returns>New instance of DesiredCapabilities for use with Opera</returns>
+        [Obsolete("Use the OperaOptions class to set capabilities for use with Opera. For use with the Java remote server or grid, use the ToCapabilites method of the OperaOptions class.")]
         public static DesiredCapabilities Opera()
         {
-            return new DesiredCapabilities("opera", string.Empty, new Platform(PlatformType.Any));
+            DesiredCapabilities dc = new DesiredCapabilities("opera", string.Empty, new Platform(PlatformType.Any));
+            dc.isSpecCompliant = false;
+            return dc;
         }
 
         /// <summary>
         /// Method to return a new DesiredCapabilities using defaults
         /// </summary>
         /// <returns>New instance of DesiredCapabilities for use with Safari</returns>
+        [Obsolete("Use the SafariOptions class to set capabilities for use with Safari. For use with the Java remote server or grid, use the ToCapabilites method of the SafariOptions class.")]
         public static DesiredCapabilities Safari()
         {
-            return new DesiredCapabilities("safari", string.Empty, new Platform(PlatformType.Mac));
+            DesiredCapabilities dc = new DesiredCapabilities("safari", string.Empty, new Platform(PlatformType.Mac));
+            dc.isSpecCompliant = false;
+            return dc;
         }
 
         /// <summary>

dotnet/src/webdriver/Remote/ISpecificationCompliant.cs

@@ -0,0 +1,36 @@
+// <copyright file="ISpecificationCompliant.cs" company="WebDriver Committers">
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+
+namespace OpenQA.Selenium.Remote
+{
+    /// <summary>
+    /// Interface used to determine whether an implementing object is compliant with the W3C WebDriver specification.
+    /// </summary>
+    internal interface ISpecificationCompliant
+    {
+        /// <summary>
+        /// Gets or sets a value indicating whether this set of capabilities is compliant with the W3C WebDriver specification.
+        /// </summary>
+        bool IsSpecificationCompliant { get; set; }
+  }
+}

dotnet/src/webdriver/Remote/RemoteWebDriver.cs

@@ -1102,14 +1102,18 @@ protected void StartSession(ICapabilities desiredCapabilities)
             Dictionary<string, object> parameters = new Dictionary<string, object>();
             parameters.Add("desiredCapabilities", this.GetLegacyCapabilitiesDictionary(desiredCapabilities));
 
-            Dictionary<string, object> firstMatchCapabilities = this.GetCapabilitiesDictionary(desiredCapabilities);
+            ISpecificationCompliant specCompliantCapabilities = desiredCapabilities as ISpecificationCompliant;
+            if (specCompliantCapabilities != null && specCompliantCapabilities.IsSpecificationCompliant)
+            {
+                Dictionary<string, object> firstMatchCapabilities = this.GetCapabilitiesDictionary(desiredCapabilities);
 
-            List<object> firstMatchCapabilitiesList = new List<object>();
-            firstMatchCapabilitiesList.Add(firstMatchCapabilities);
+                List<object> firstMatchCapabilitiesList = new List<object>();
+                firstMatchCapabilitiesList.Add(firstMatchCapabilities);
 
-            Dictionary<string, object> specCompliantCapabilities = new Dictionary<string, object>();
-            specCompliantCapabilities["firstMatch"] = firstMatchCapabilitiesList;
-            parameters.Add("capabilities", specCompliantCapabilities);
+                Dictionary<string, object> specCompliantCapabilitiesDictionary = new Dictionary<string, object>();
+                specCompliantCapabilitiesDictionary["firstMatch"] = firstMatchCapabilitiesList;
+                parameters.Add("capabilities", specCompliantCapabilitiesDictionary);
+            }
 
             Response response = this.Execute(DriverCommand.NewSession, parameters);
 

dotnet/src/webdriver/WebDriver.csproj

@@ -214,6 +214,7 @@
     <Compile Include="Remote\ICommandExecutor.cs" />
     <Compile Include="Remote\ICommandServer.cs" />
     <Compile Include="Remote\IHasSessionId.cs" />
+    <Compile Include="Remote\ISpecificationCompliant.cs" />
     <Compile Include="Remote\JsonConverters\CharArrayJsonConverter.cs" />
     <Compile Include="Remote\JsonConverters\ResponseValueJsonConverter.cs" />
     <Compile Include="Remote\LocalFileDetector.cs" />