Adding support for relative locators for .NET

To use relative locators in .NET, take advantage of the RelativeBy
class to use with FindElement and FindElements. This change also
marks the IFindsBy* interfaces (IFindsById, IFindsByName, etc.) as
deprecated. The presence of individual methods for finding elements
by each mechanism is an artifact of an older architecture, and with
the standardization of the locator methods in the W3C WebDriver
Specification, they are now just excess code, and will be deleted.

dotnet/src/webdriver/BUILD.bazel

@@ -28,6 +28,7 @@ load(
         "Support/*.cs",
     ]),
     resources = [
+        "//javascript/atoms/fragments:find-elements.js",
         "//javascript/atoms/fragments:is-displayed.js",
         "//javascript/webdriver/atoms:get-attribute.js",
     ],
@@ -68,6 +69,7 @@ csharp_library(
         "Support/*.cs",
     ]),
     resources = [
+        "//javascript/atoms/fragments:find-elements.js",
         "//javascript/atoms/fragments:is-displayed.js",
         "//javascript/webdriver/atoms:get-attribute.js",
     ],
@@ -100,6 +102,7 @@ csharp_library(
     ]),
     keyfile = "//dotnet:WebDriver.snk",
     resources = [
+        "//javascript/atoms/fragments:find-elements.js",
         "//javascript/atoms/fragments:is-displayed.js",
         "//javascript/webdriver/atoms:get-attribute.js",
     ],
@@ -141,6 +144,7 @@ csharp_library(
     ]),
     keyfile = "//dotnet:WebDriver.snk",
     resources = [
+        "//javascript/atoms/fragments:find-elements.js",
         "//javascript/atoms/fragments:is-displayed.js",
         "//javascript/webdriver/atoms:get-attribute.js",
     ],

dotnet/src/webdriver/By.cs

@@ -17,7 +17,10 @@
 // </copyright>
 
 using System;
+using System.Collections.Generic;
 using System.Collections.ObjectModel;
+using System.Globalization;
+using System.Text.RegularExpressions;
 using OpenQA.Selenium.Internal;
 
 namespace OpenQA.Selenium
@@ -34,6 +37,8 @@ namespace OpenQA.Selenium
     public class By
     {
         private string description = "OpenQA.Selenium.By";
+        private string mechanism = string.Empty;
+        private string criteria = string.Empty;
         private Func<ISearchContext, IWebElement> findElementMethod;
         private Func<ISearchContext, ReadOnlyCollection<IWebElement>> findElementsMethod;
 
@@ -58,6 +63,22 @@ protected By(Func<ISearchContext, IWebElement> findElementMethod, Func<ISearchCo
             this.findElementsMethod = findElementsMethod;
         }
 
+        /// <summary>
+        /// Gets the value of the mechanism for this <see cref="By"/> class instance.
+        /// </summary>
+        public string Mechanism
+        {
+            get { return this.mechanism; }
+        }
+
+        /// <summary>
+        /// Gets the value of the criteria for this <see cref="By"/> class instance.
+        /// </summary>
+        public string Criteria
+        {
+            get { return this.criteria; }
+        }
+
         /// <summary>
         /// Gets or sets the value of the description for this <see cref="By"/> class instance.
         /// </summary>
@@ -132,10 +153,25 @@ public static By Id(string idToFind)
             }
 
             By by = new By();
-            by.findElementMethod = (ISearchContext context) => ((IFindsById)context).FindElementById(idToFind);
-            by.findElementsMethod = (ISearchContext context) => ((IFindsById)context).FindElementsById(idToFind);
-
             by.description = "By.Id: " + idToFind;
+            by.mechanism = "css selector";
+            string selector = By.EscapeCssSelector(idToFind);
+            by.criteria = "#" + selector;
+
+            by.findElementMethod = (ISearchContext context) => ((IFindsElement)context).FindElement(by.mechanism, by.criteria);
+            if (string.IsNullOrEmpty(selector))
+            {
+                // Finding multiple elements with an empty ID will return
+                // an empty list. However, finding by a CSS selector of '#'
+                // throws an exception, even in the multiple elements case,
+                // which means we need to short-circuit that behavior.
+                by.findElementsMethod = (ISearchContext context) => new List<IWebElement>().AsReadOnly();
+            }
+            else
+            {
+                by.findElementsMethod = (ISearchContext context) => ((IFindsElement)context).FindElements(by.mechanism, by.criteria);
+            }
+
             return by;
         }
 
@@ -152,12 +188,12 @@ public static By LinkText(string linkTextToFind)
             }
 
             By by = new By();
-            by.findElementMethod =
-                (ISearchContext context) => ((IFindsByLinkText)context).FindElementByLinkText(linkTextToFind);
-            by.findElementsMethod =
-                (ISearchContext context) => ((IFindsByLinkText)context).FindElementsByLinkText(linkTextToFind);
-
             by.description = "By.LinkText: " + linkTextToFind;
+            by.mechanism = "link text";
+            by.criteria = linkTextToFind;
+
+            by.findElementMethod = (ISearchContext context) => ((IFindsElement)context).FindElement(by.mechanism, by.criteria);
+            by.findElementsMethod = (ISearchContext context) => ((IFindsElement)context).FindElements(by.mechanism, by.criteria);
             return by;
         }
 
@@ -174,10 +210,12 @@ public static By Name(string nameToFind)
             }
 
             By by = new By();
-            by.findElementMethod = (ISearchContext context) => ((IFindsByName)context).FindElementByName(nameToFind);
-            by.findElementsMethod = (ISearchContext context) => ((IFindsByName)context).FindElementsByName(nameToFind);
-
             by.description = "By.Name: " + nameToFind;
+            by.mechanism = "css selector";
+            by.criteria = "*[name =\"" + By.EscapeCssSelector(nameToFind) + "\"]";
+
+            by.findElementMethod = (ISearchContext context) => ((IFindsElement)context).FindElement(by.mechanism, by.criteria);
+            by.findElementsMethod = (ISearchContext context) => ((IFindsElement)context).FindElements(by.mechanism, by.criteria);
             return by;
         }
 
@@ -197,11 +235,12 @@ public static By XPath(string xpathToFind)
             }
 
             By by = new By();
-            by.findElementMethod = (ISearchContext context) => ((IFindsByXPath)context).FindElementByXPath(xpathToFind);
-            by.findElementsMethod =
-                (ISearchContext context) => ((IFindsByXPath)context).FindElementsByXPath(xpathToFind);
-
             by.description = "By.XPath: " + xpathToFind;
+            by.mechanism = "xpath";
+            by.criteria = xpathToFind;
+
+            by.findElementMethod = (ISearchContext context) => ((IFindsElement)context).FindElement(by.mechanism, by.criteria);
+            by.findElementsMethod = (ISearchContext context) => ((IFindsElement)context).FindElements(by.mechanism, by.criteria);
             return by;
         }
 
@@ -221,12 +260,20 @@ public static By ClassName(string classNameToFind)
             }
 
             By by = new By();
-            by.findElementMethod =
-                (ISearchContext context) => ((IFindsByClassName)context).FindElementByClassName(classNameToFind);
-            by.findElementsMethod =
-                (ISearchContext context) => ((IFindsByClassName)context).FindElementsByClassName(classNameToFind);
-
             by.description = "By.ClassName[Contains]: " + classNameToFind;
+            by.mechanism = "css selector";
+            by.criteria = "." + By.EscapeCssSelector(classNameToFind);
+            if (by.criteria.Contains(" "))
+            {
+                // Finding elements by class name with whitespace is not allowed.
+                // However, converting the single class name to a valid CSS selector
+                // by prepending a '.' may result in a still-valid, but incorrect
+                // selector. Thus, we short-ciruit that behavior here.
+                throw new InvalidSelectorException("Compound class names not allowed. Cannot have whitespace in class name. Use CSS selectors instead.");
+            }
+
+            by.findElementMethod = (ISearchContext context) => ((IFindsElement)context).FindElement(by.mechanism, by.criteria);
+            by.findElementsMethod = (ISearchContext context) => ((IFindsElement)context).FindElements(by.mechanism, by.criteria);
             return by;
         }
 
@@ -237,15 +284,18 @@ public static By ClassName(string classNameToFind)
         /// <returns>A <see cref="By"/> object the driver can use to find the elements.</returns>
         public static By PartialLinkText(string partialLinkTextToFind)
         {
-            By by = new By();
-            by.findElementMethod =
-                (ISearchContext context) =>
-                ((IFindsByPartialLinkText)context).FindElementByPartialLinkText(partialLinkTextToFind);
-            by.findElementsMethod =
-                (ISearchContext context) =>
-                ((IFindsByPartialLinkText)context).FindElementsByPartialLinkText(partialLinkTextToFind);
+            if (partialLinkTextToFind == null)
+            {
+                throw new ArgumentNullException("partialLinkTextToFind", "Cannot find elements when partial link text is null.");
+            }
 
+            By by = new By();
             by.description = "By.PartialLinkText: " + partialLinkTextToFind;
+            by.mechanism = "partial link text";
+            by.criteria = partialLinkTextToFind;
+
+            by.findElementMethod = (ISearchContext context) => ((IFindsElement)context).FindElement(by.mechanism, by.criteria);
+            by.findElementsMethod = (ISearchContext context) => ((IFindsElement)context).FindElements(by.mechanism, by.criteria);
             return by;
         }
 
@@ -262,12 +312,12 @@ public static By TagName(string tagNameToFind)
             }
 
             By by = new By();
-            by.findElementMethod =
-                (ISearchContext context) => ((IFindsByTagName)context).FindElementByTagName(tagNameToFind);
-            by.findElementsMethod =
-                (ISearchContext context) => ((IFindsByTagName)context).FindElementsByTagName(tagNameToFind);
-
             by.description = "By.TagName: " + tagNameToFind;
+            by.mechanism = "css selector";
+            by.criteria = tagNameToFind;
+
+            by.findElementMethod = (ISearchContext context) => ((IFindsElement)context).FindElement(by.mechanism, by.criteria);
+            by.findElementsMethod = (ISearchContext context) => ((IFindsElement)context).FindElements(by.mechanism, by.criteria);
             return by;
         }
 
@@ -284,12 +334,12 @@ public static By CssSelector(string cssSelectorToFind)
             }
 
             By by = new By();
-            by.findElementMethod =
-                (ISearchContext context) => ((IFindsByCssSelector)context).FindElementByCssSelector(cssSelectorToFind);
-            by.findElementsMethod =
-                (ISearchContext context) => ((IFindsByCssSelector)context).FindElementsByCssSelector(cssSelectorToFind);
-
             by.description = "By.CssSelector: " + cssSelectorToFind;
+            by.mechanism = "css selector";
+            by.criteria = cssSelectorToFind;
+
+            by.findElementMethod = (ISearchContext context) => ((IFindsElement)context).FindElement(by.mechanism, by.criteria);
+            by.findElementsMethod = (ISearchContext context) => ((IFindsElement)context).FindElements(by.mechanism, by.criteria);
             return by;
         }
 
@@ -348,5 +398,21 @@ public override int GetHashCode()
         {
             return this.description.GetHashCode();
         }
+
+        /// <summary>
+        /// Escapes invalid characters in a CSS selector.
+        /// </summary>
+        /// <param name="selector">The selector to escape.</param>
+        /// <returns>The selector with invalid characters escaped.</returns>
+        internal static string EscapeCssSelector(string selector)
+        {
+            string escaped = Regex.Replace(selector, @"([ '""\\#.:;,!?+<>=~*^$|%&@`{}\-/\[\]\(\)])", @"\$1");
+            if (selector.Length > 0 && char.IsDigit(selector[0]))
+            {
+                escaped = @"\" + (30 + int.Parse(selector.Substring(0, 1), CultureInfo.InvariantCulture)).ToString(CultureInfo.InvariantCulture) + " " + selector.Substring(1);
+            }
+
+            return escaped;
+        }
     }
 }

dotnet/src/webdriver/Internal/IFindsByClassName.cs

@@ -16,13 +16,15 @@
 // limitations under the License.
 // </copyright>
 
+using System;
 using System.Collections.ObjectModel;
 
 namespace OpenQA.Selenium.Internal
 {
     /// <summary>
     /// Defines the interface through which the user finds elements by their CSS class.
     /// </summary>
+    [Obsolete("The internal IFindsBy interfaces are being deprecated in favor of common implementation.")]
     public interface IFindsByClassName
     {
         /// <summary>

dotnet/src/webdriver/Internal/IFindsByCssSelector.cs

@@ -1,4 +1,4 @@
-// <copyright file="IFindsByCssSelector.cs" company="WebDriver Committers">
+// <copyright file="IFindsByCssSelector.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
@@ -16,13 +16,15 @@
 // limitations under the License.
 // </copyright>
 
+using System;
 using System.Collections.ObjectModel;
 
 namespace OpenQA.Selenium.Internal
 {
     /// <summary>
     /// Defines the interface through which the user finds elements by their cascading style sheet (CSS) selector.
     /// </summary>
+    [Obsolete("The internal IFindsBy interfaces are being deprecated in favor of common implementation.")]
     public interface IFindsByCssSelector
     {
         /// <summary>

dotnet/src/webdriver/Internal/IFindsById.cs

@@ -16,13 +16,15 @@
 // limitations under the License.
 // </copyright>
 
+using System;
 using System.Collections.ObjectModel;
 
 namespace OpenQA.Selenium.Internal
 {
     /// <summary>
     /// Defines the interface through which the user finds elements by their ID.
     /// </summary>
+    [Obsolete("The internal IFindsBy interfaces are being deprecated in favor of common implementation.")]
     public interface IFindsById
     {
         /// <summary>

dotnet/src/webdriver/Internal/IFindsByLinkText.cs

@@ -16,13 +16,15 @@
 // limitations under the License.
 // </copyright>
 
+using System;
 using System.Collections.ObjectModel;
 
 namespace OpenQA.Selenium.Internal
 {
     /// <summary>
     /// Defines the interface through which the user finds elements by their link text.
     /// </summary>
+    [Obsolete("The internal IFindsBy interfaces are being deprecated in favor of common implementation.")]
     public interface IFindsByLinkText
     {
         /// <summary>

dotnet/src/webdriver/Internal/IFindsByName.cs

@@ -16,13 +16,15 @@
 // limitations under the License.
 // </copyright>
 
+using System;
 using System.Collections.ObjectModel;
 
 namespace OpenQA.Selenium.Internal
 {
     /// <summary>
     /// Defines the interface through which the user finds elements by their name.
     /// </summary>
+    [Obsolete("The internal IFindsBy interfaces are being deprecated in favor of common implementation.")]
     public interface IFindsByName
     {
         /// <summary>

dotnet/src/webdriver/Internal/IFindsByPartialLinkText.cs

@@ -16,13 +16,15 @@
 // limitations under the License.
 // </copyright>
 
+using System;
 using System.Collections.ObjectModel;
 
 namespace OpenQA.Selenium.Internal
 {
     /// <summary>
     /// Defines the interface through which the user finds elements by a partial match on their link text.
     /// </summary>
+    [Obsolete("The internal IFindsBy interfaces are being deprecated in favor of common implementation.")]
     public interface IFindsByPartialLinkText
     {
         /// <summary>

dotnet/src/webdriver/Internal/IFindsByTagName.cs

@@ -16,13 +16,15 @@
 // limitations under the License.
 // </copyright>
 
+using System;
 using System.Collections.ObjectModel;
 
 namespace OpenQA.Selenium.Internal
 {
     /// <summary>
     /// Defines the interface through which the user finds elements by their tag name.
     /// </summary>
+    [Obsolete("The internal IFindsBy interfaces are being deprecated in favor of common implementation.")]
     public interface IFindsByTagName
     {
         /// <summary>

dotnet/src/webdriver/Internal/IFindsByXPath.cs

@@ -16,13 +16,15 @@
 // limitations under the License.
 // </copyright>
 
+using System;
 using System.Collections.ObjectModel;
 
 namespace OpenQA.Selenium.Internal
 {
     /// <summary>
     /// Defines the interface through which the user finds elements by XPath.
     /// </summary>
+    [Obsolete("The internal IFindsBy interfaces are being deprecated in favor of common implementation.")]
     public interface IFindsByXPath
     {
         /// <summary>