// <copyright file="By.cs" company="Selenium 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 OpenQA.Selenium.Internal;
using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Globalization;
using System.Text.RegularExpressions;
namespace OpenQA.Selenium;
/// <summary>
/// Provides a mechanism by which to find elements within a document.
/// </summary>
/// <remarks>It is possible to create your own locating mechanisms for finding documents.
/// In order to do this,subclass this class and override the protected methods. However,
/// it is expected that that all subclasses rely on the basic finding mechanisms provided
/// through static methods of this class. An example of this can be found in OpenQA.Support.ByIdOrName
/// </remarks>
[Serializable]
public class By
{
private const string CssSelectorMechanism = "css selector";
private const string XPathSelectorMechanism = "xpath";
private const string TagNameMechanism = "tag name";
private const string LinkTextMechanism = "link text";
private const string PartialLinkTextMechanism = "partial link text";
/// <summary>
/// Initializes a new instance of the <see cref="By"/> class.
/// </summary>
protected By()
{
}
/// <summary>
/// Initializes a new instance of the <see cref="By"/> class using the specified mechanism and criteria for finding elements.
/// </summary>
/// <param name="mechanism">The mechanism to use in finding elements.</param>
/// <param name="criteria">The criteria to use in finding elements.</param>
/// <remarks>
/// Customizing nothing else, instances using this constructor will attempt to find elements
/// using the <see cref="IFindsElement.FindElement(string, string)"/> method, taking string arguments.
/// </remarks>
protected By(string mechanism, string criteria)
{
this.Mechanism = mechanism;
this.Criteria = criteria;
this.FindElementMethod = (ISearchContext context) => ((IFindsElement)context).FindElement(this.Mechanism, this.Criteria);
this.FindElementsMethod = (ISearchContext context) => ((IFindsElement)context).FindElements(this.Mechanism, this.Criteria);
}
/// <summary>
/// Initializes a new instance of the <see cref="By"/> class using the given functions to find elements.
/// </summary>
/// <param name="findElementMethod">A function that takes an object implementing <see cref="ISearchContext"/>
/// and returns the found <see cref="IWebElement"/>.</param>
/// <param name="findElementsMethod">A function that takes an object implementing <see cref="ISearchContext"/>
/// and returns a <see cref="ReadOnlyCollection{T}"/> of the found<see cref="IWebElement">IWebElements</see>.
/// <see cref="IWebElement">IWebElements</see>/>.</param>
protected By(Func<ISearchContext, IWebElement> findElementMethod, Func<ISearchContext, ReadOnlyCollection<IWebElement>> findElementsMethod)
{
this.FindElementMethod = findElementMethod;
this.FindElementsMethod = findElementsMethod;
}
/// <summary>
/// Gets the value of the mechanism for this <see cref="By"/> class instance.
/// </summary>
public string Mechanism { get; } = string.Empty;
/// <summary>
/// Gets the value of the criteria for this <see cref="By"/> class instance.
/// </summary>
public string Criteria { get; } = string.Empty;
/// <summary>
/// Gets or sets the value of the description for this <see cref="By"/> class instance.
/// </summary>
protected string Description { get; set; } = "OpenQA.Selenium.By";
/// <summary>
/// Gets or sets the method used to find a single element matching specified criteria, or throws <see cref="NoSuchElementException"/> if no element is found.
/// </summary>
protected Func<ISearchContext, IWebElement>? FindElementMethod { get; set; }
/// <summary>
/// Gets or sets the method used to find all elements matching specified criteria.
/// </summary>
protected Func<ISearchContext, ReadOnlyCollection<IWebElement>>? FindElementsMethod { get; set; }
/// <summary>
/// Determines if two <see cref="By"/> instances are equal.
/// </summary>
/// <param name="one">One instance to compare.</param>
/// <param name="two">The other instance to compare.</param>
/// <returns><see langword="true"/> if the two instances are equal; otherwise, <see langword="false"/>.</returns>
public static bool operator ==(By? one, By? two)
{
// If both are null, or both are same instance, return true.
if (ReferenceEquals(one, two))
{
return true;
}
// If one is null, but not both, return false.
if ((one is null) || (two is null))
{
return false;
}
return one.Equals(two);
}
/// <summary>
/// Determines if two <see cref="By"/> instances are unequal.
/// </summary>s
/// <param name="one">One instance to compare.</param>
/// <param name="two">The other instance to compare.</param>
/// <returns><see langword="true"/> if the two instances are not equal; otherwise, <see langword="false"/>.</returns>
public static bool operator !=(By? one, By? two)
{
return !(one == two);
}
/// <summary>
/// Gets a mechanism to find elements by their ID.
/// </summary>
/// <param name="idToFind">The ID to find.</param>
/// <returns>A <see cref="By"/> object the driver can use to find the elements.</returns>
/// <exception cref="ArgumentNullException">If <paramref name="idToFind"/> is <see langword="null"/>.</exception>
public static By Id(string idToFind)
{
if (idToFind == null)
{
throw new ArgumentNullException(nameof(idToFind), "Cannot find elements with a null id attribute.");
}
string selector = EscapeCssSelector(idToFind);
By by = new By(CssSelectorMechanism, "#" + selector);
by.Description = "By.Id: " + idToFind;
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();
}
return by;
}
/// <summary>
/// Gets a mechanism to find elements by their link text.
/// </summary>
/// <param name="linkTextToFind">The link text to find.</param>
/// <returns>A <see cref="By"/> object the driver can use to find the elements.</returns>
/// <exception cref="ArgumentNullException">If <paramref name="linkTextToFind"/> is null.</exception>
public static By LinkText(string linkTextToFind)
{
if (linkTextToFind == null)
{
throw new ArgumentNullException(nameof(linkTextToFind), "Cannot find elements when link text is null.");
}
return new By(LinkTextMechanism, linkTextToFind)
{
Description = "By.LinkText: " + linkTextToFind
};
}
/// <summary>
/// Gets a mechanism to find elements by their name.
/// </summary>
/// <param name="nameToFind">The name to find.</param>
/// <returns>A <see cref="By"/> object the driver can use to find the elements.</returns>
/// <exception cref="ArgumentNullException">If <paramref name="nameToFind"/> is null.</exception>
public static By Name(string nameToFind)
{
if (nameToFind == null)
{
throw new ArgumentNullException(nameof(nameToFind), "Cannot find elements when name text is null.");
}
return new By(CssSelectorMechanism, $"*[name =\"{EscapeCssSelector(nameToFind)}\"]")
{
Description = "By.Name: " + nameToFind
};
}
/// <summary>
/// Gets a mechanism to find elements by an XPath query.
/// When searching within a WebElement using xpath be aware that WebDriver follows standard conventions:
/// a search prefixed with "//" will search the entire document, not just the children of this current node.
/// Use ".//" to limit your search to the children of this WebElement.
/// </summary>
/// <param name="xpathToFind">The XPath query to use.</param>
/// <returns>A <see cref="By"/> object the driver can use to find the elements.</returns>
/// <exception cref="ArgumentNullException">If <paramref name="xpathToFind"/> is null.</exception>
public static By XPath(string xpathToFind)
{
if (xpathToFind == null)
{
throw new ArgumentNullException(nameof(xpathToFind), "Cannot find elements when the XPath expression is null.");
}
return new By(XPathSelectorMechanism, xpathToFind)
{
Description = "By.XPath: " + xpathToFind
};
}
/// <summary>
/// Gets a mechanism to find elements by their CSS class.
/// </summary>
/// <param name="classNameToFind">The CSS class to find.</param>
/// <returns>A <see cref="By"/> object the driver can use to find the elements.</returns>
/// <remarks>If an element has many classes then this will match against each of them.
/// For example if the value is "one two onone", then the following values for the
/// className parameter will match: "one" and "two".</remarks>
/// <exception cref="ArgumentNullException">If <paramref name="classNameToFind"/> is null.</exception>
public static By ClassName(string classNameToFind)
{
if (classNameToFind == null)
{
throw new ArgumentNullException(nameof(classNameToFind), "Cannot find elements when the class name expression is null.");
}
string selector = "." + EscapeCssSelector(classNameToFind);
if (selector.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-circuit that behavior here.
throw new InvalidSelectorException("Compound class names not allowed. Cannot have whitespace in class name. Use CSS selectors instead.");
}
return new By(CssSelectorMechanism, selector)
{
Description = "By.ClassName[Contains]: " + classNameToFind
};
}
/// <summary>
/// Gets a mechanism to find elements by a partial match on their link text.
/// </summary>
/// <param name="partialLinkTextToFind">The partial link text to find.</param>
/// <returns>A <see cref="By"/> object the driver can use to find the elements.</returns>
/// <exception cref="ArgumentNullException">If <paramref name="partialLinkTextToFind"/> is null.</exception>
public static By PartialLinkText(string partialLinkTextToFind)
{
if (partialLinkTextToFind == null)
{
throw new ArgumentNullException(nameof(partialLinkTextToFind), "Cannot find elements when partial link text is null.");
}
return new By(PartialLinkTextMechanism, partialLinkTextToFind)
{
Description = "By.PartialLinkText: " + partialLinkTextToFind
};
}
/// <summary>
/// Gets a mechanism to find elements by their tag name.
/// </summary>
/// <param name="tagNameToFind">The tag name to find.</param>
/// <returns>A <see cref="By"/> object the driver can use to find the elements.</returns>
/// <exception cref="ArgumentNullException">If <paramref name="tagNameToFind"/> is null.</exception>
public static By TagName(string tagNameToFind)
{
if (tagNameToFind == null)
{
throw new ArgumentNullException(nameof(tagNameToFind), "Cannot find elements when name tag name is null.");
}
return new By(TagNameMechanism, tagNameToFind)
{
Description = "By.TagName: " + tagNameToFind
};
}
/// <summary>
/// Gets a mechanism to find elements by their cascading style sheet (CSS) selector.
/// </summary>
/// <param name="cssSelectorToFind">The CSS selector to find.</param>
/// <returns>A <see cref="By"/> object the driver can use to find the elements.</returns>
/// <exception cref="ArgumentNullException">If <paramref name="cssSelectorToFind"/> is null.</exception>
public static By CssSelector(string cssSelectorToFind)
{
if (cssSelectorToFind == null)
{
throw new ArgumentNullException(nameof(cssSelectorToFind), "Cannot find elements when name CSS selector is null.");
}
return new By(CssSelectorMechanism, cssSelectorToFind)
{
Description = "By.CssSelector: " + cssSelectorToFind
};
}
/// <summary>
/// Finds the first element matching the criteria.
/// </summary>
/// <param name="context">An <see cref="ISearchContext"/> object to use to search for the elements.</param>
/// <returns>The first matching <see cref="IWebElement"/> on the current context.</returns>
/// <exception cref="NoSuchElementException">If no element matches the criteria.</exception>
public virtual IWebElement FindElement(ISearchContext context)
{
if (this.FindElementMethod is not { } findElementMethod)
{
throw new InvalidOperationException("FindElement method not set. Override the By.FindElement method, set the By.FindElementMethod property, or use a constructor that sets a query mechanism.");
}
return findElementMethod(context);
}
/// <summary>
/// Finds all elements matching the criteria.
/// </summary>
/// <param name="context">An <see cref="ISearchContext"/> object to use to search for the elements.</param>
/// <returns>A <see cref="ReadOnlyCollection{T}"/> of all <see cref="IWebElement">WebElements</see>
/// matching the current criteria, or an empty list if nothing matches.</returns>
public virtual ReadOnlyCollection<IWebElement> FindElements(ISearchContext context)
{
if (this.FindElementsMethod is not { } findElementsMethod)
{
throw new InvalidOperationException("FindElements method not set. Override the By.FindElements method, set the By.FindElementsMethod property, or use a constructor that sets a query mechanism.");
}
return findElementsMethod(context);
}
/// <summary>
/// Gets a string representation of the finder.
/// </summary>
/// <returns>The string displaying the finder content.</returns>
public override string ToString()
{
return this.Description;
}
/// <summary>
/// Determines whether the specified <see cref="object">Object</see> is equal
/// to the current <see cref="object">Object</see>.
/// </summary>
/// <param name="obj">The <see cref="object">Object</see> to compare with the
/// current <see cref="object">Object</see>.</param>
/// <returns><see langword="true"/> if the specified <see cref="object">Object</see>
/// is equal to the current <see cref="object">Object</see>; otherwise,
/// <see langword="false"/>.</returns>
public override bool Equals(object? obj)
{
var other = obj as By;
// TODO(dawagner): This isn't ideal
return other != null && this.Description.Equals(other.Description);
}
/// <summary>
/// Serves as a hash function for a particular type.
/// </summary>
/// <returns>A hash code for the current <see cref="object">Object</see>.</returns>
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 = InvalidCharsRegex.Replace(selector, @"\$1");
if (selector.Length > 0 && char.IsDigit(selector[0]))
{
int digitCode = 30 + int.Parse(selector.Substring(0, 1), CultureInfo.InvariantCulture);
escaped = $"\\{digitCode.ToString(CultureInfo.InvariantCulture)} {selector.Substring(1)}";
}
return escaped;
}
private static readonly Regex InvalidCharsRegex = new Regex(@"([ '""\\#.:;,!?+<>=~*^$|%&@`{}\-/\[\]\(\)])", RegexOptions.Compiled);
}
