def link(locator):
    """
    Returns an :class:`Expression` for finding links matching the given locator.

    The query defines a link as an ``a`` element with an ``href`` attribute and will match links
    that meet at least one of the following criteria:
    * the element ``id`` exactly matches the locator
    * the element ``title`` matches the locator
    * the element text matches the locator
    * the ``alt`` of a nested ``img`` element matches the locator

    Args:
        locator (str): A string that identifies the desired links.

    Returns:
        Expression: An :class:`Expression` object matching the desired links.
    """

    expr = x.descendant("a")[x.attr("href")][
        x.attr("id").equals(locator) |
        x.attr("title").is_(locator) |
        x.string.n.is_(locator) |
        x.descendant("img")[x.attr("alt").is_(locator)]]

    return expr

    def test_selects_a_nodes_text(self):
        xpath = to_xpath(x.descendant("p")[x.text == "Bax"])
        results = self.find_all(xpath)
        self.assertEqual(results[0].text, "Bax")
        self.assertEqual(results[1].get("title"), "monkey")

        xpath = to_xpath(x.descendant("div")[x.descendant("p").text == "Bax"])
        results = self.find_all(xpath)
        self.assertEqual(results[0].get("title"), "fooDiv")

    def test_matches_encoded_unicode_characters(self):
        locator = "이름".encode("UTF-8") if sys.version_info >= (3, 0) else "이름"

        xpath = to_xpath(x.descendant("div")[x.string.n.is_(locator)])
        results = self.find_all(xpath)
        self.assertEqual(results[0].get("id"), "unicode")

        xpath = to_xpath(x.descendant("div")[x.attr("title") == locator])
        results = self.find_all(xpath)
        self.assertEqual(results[0].get("id"), "unicode")

    def test_matches_quotes(self):
        locator = "Who's quotes? \"Their\" quotes."

        xpath = to_xpath(x.descendant("div")[x.string.n.is_(locator)])
        results = self.find_all(xpath)
        self.assertEqual(results[0].get("id"), "quotes")

        xpath = to_xpath(x.descendant("div")[x.attr("title") == locator])
        results = self.find_all(xpath)
        self.assertEqual(results[0].get("id"), "quotes")

    def test_second_order_union_aliased_as_plus_sign(self):
        expr1 = x.descendant("p")
        expr2 = x.descendant("div")
        expr3 = x.descendant("span")

        collection1 = (expr1 + expr2)[x.attr("id") == "union-item-5"]
        collection2 = collection1 + expr3[x.attr("id") == "union-item-6"]

        xpath = to_xpath(collection2)

        results = self.find_all(xpath)
        self.assertEqual(results[0].text, "Fig")

    def test_creates_a_second_order_union(self):
        expr1 = x.descendant("p")
        expr2 = x.descendant("div")
        expr3 = x.descendant("span")

        collection1 = expr1.union(expr2)[x.attr("id") == "union-item-5"]
        collection2 = collection1.union(expr3[x.attr("id") == "union-item-6"])

        xpath = to_xpath(collection2)

        results = self.find_all(xpath)
        self.assertEqual(results[0].text, "Fig")

    def test_where_aliased_as_square_brackets(self):
        expr1 = x.descendant("p")
        expr2 = x.descendant("div")

        collection = expr1.union(expr2)

        xpath1 = to_xpath(collection[x.attr("id").equals("union-item-3")])
        xpath2 = to_xpath(collection[x.attr("id").equals("union-item-4")])

        results = self.find_all(xpath1)
        self.assertEqual(results[0].text, "Cherry")

        results = self.find_all(xpath2)
        self.assertEqual(results[0].text, "Date")

    def test_aliased_as_plus_sign(self):
        expr1 = x.descendant("p")
        expr2 = x.descendant("div")

        collection = expr1 + expr2

        xpath1 = to_xpath(collection.where(x.attr("id").equals("union-item-3")))
        xpath2 = to_xpath(collection.where(x.attr("id").equals("union-item-4")))

        results = self.find_all(xpath1)
        self.assertEqual(results[0].text, "Cherry")

        results = self.find_all(xpath2)
        self.assertEqual(results[0].text, "Date")

    def test_creates_a_union_expression(self):
        expr1 = x.descendant("p")
        expr2 = x.descendant("div")

        collection = expr1.union(expr2)

        xpath1 = to_xpath(collection.where(x.attr("id").equals("union-item-3")))
        xpath2 = to_xpath(collection.where(x.attr("id").equals("union-item-4")))

        results = self.find_all(xpath1)
        self.assertEqual(results[0].text, "Cherry")

        results = self.find_all(xpath2)
        self.assertEqual(results[0].text, "Date")

 def test_aliased_as_right_angle_bracket_equals(self):
     xpath = to_xpath(x.descendant("p")[x.position() >= 2])
     results = self.find_all(xpath)
     self.assertEqual(results[0].text, "Bax")
     self.assertEqual(results[1].get("title"), "monkey")
     self.assertEqual(results[2].text, "Bax")
     self.assertEqual(results[3].text, "Blah")

 def test_finds_multiple_kinds_of_nodes_regardless_of_the_context(self):
     xpath = to_xpath(x.descendant("div")[x.attr("id") == "woo"].anywhere("p", "ul"))
     results = self.find_all(xpath)
     self.assertEqual(inner_text(results[0]), "Blah")
     self.assertEqual(inner_text(results[3]), "A list")
     self.assertEqual(inner_text(results[4]), "A list")
     self.assertEqual(inner_text(results[6]), "Bax")

    def test_used_as_an_expression(self):
        parent = x.descendant("div")[x.attr("id").equals("union")]

        expr1 = x.descendant("p")
        expr2 = x.descendant("div")

        collection = expr1.union(expr2)

        xpath1 = to_xpath(parent.descendant(collection[x.attr("id").equals("union-item-3")]))
        xpath2 = to_xpath(parent.descendant(collection[x.attr("id").equals("union-item-4")]))

        results = self.find_all(xpath1)
        self.assertEqual(results[0].text, "Cherry")

        results = self.find_all(xpath2)
        self.assertEqual(results[0].text, "Date")

 def test_checks_greater_than_or_equal(self):
     xpath = to_xpath(x.descendant("p")[x.position().gte(2)])
     results = self.find_all(xpath)
     self.assertEqual(results[0].text, "Bax")
     self.assertEqual(results[1].get("title"), "monkey")
     self.assertEqual(results[2].text, "Bax")
     self.assertEqual(results[3].text, "Blah")

def field(locator):
    """
    Returns an :class:`Expression` for finding form fields matching the given locator.

    The query defines a form field as one of the following:
    * an ``input`` element whose ``type`` is neither "hidden", "image", nor "submit"
    * a ``select`` element
    * a ``textarea`` element

    The query will match form fields that meet at least one of the following criteria:
    * the element ``id`` exactly matches the locator
    * the element ``name`` exactly matches the locator
    * the element ``placeholder`` exactly matches the locator
    * the element ``id`` exactly matches the ``for`` attribute of a corresponding ``label`` element
      whose text matches the locator
    * the element is nested within a ``label`` element whose text matches the locator

    Args:
        locator (str): A string that identifies the desired form fields.
    Return:
        Expression: An :class:`Expression` object matching the desired form fields.
    """

    field_expr = x.descendant("input", "select", "textarea")[
        ~x.attr("type").one_of("hidden", "image", "submit")]
    return _locate_field(field_expr, locator)

def _locate_field(field_expr, locator):
    expr = field_expr[
        x.attr("id").equals(locator) |
        x.attr("name").equals(locator) |
        x.attr("placeholder").equals(locator) |
        x.attr("id").equals(x.anywhere("label")[x.string.n.is_(locator)].attr("for"))]
    expr += x.descendant("label")[x.string.n.is_(locator)].descendant(field_expr)

    return expr

 def test_finds_all_nodes_when_no_arguments_given_regardless_of_the_context(self):
     xpath = to_xpath(x.descendant("div")[x.attr("id") == "woo"].anywhere())
     results = self.find_all(xpath)
     self.assertEqual(results[0].tag, "html")
     self.assertEqual(results[1].tag, "head")
     self.assertEqual(results[3].tag, "body")
     self.assertEqual(inner_text(results[5]), "Blah")
     self.assertEqual(inner_text(results[9]), "A list")
     self.assertEqual(inner_text(results[12]), "A list")
     self.assertEqual(inner_text(results[14]), "Bax")

def table(locator):
    """
    Returns an :class:`Expression` for finding tables matching the given locator.

    The query will match tables that meet at least one of the following criteria:
    * the element ``id`` exactly matches the locator
    * the element has a descendant ``caption`` element whose text matches the locator

    Args:
        locator (str): A string that identifies the desired tables.

    Returns:
        Expression: An :class:`Expression` object matching the desired tables.
    """

    expr = x.descendant("table")[
        x.attr("id").equals(locator) |
        x.descendant("caption").is_(locator)]

    return expr

def frame(locator):
    """
    Returns an :class:`Expression` for finding frames matching the given locator.

    The query defines a frame as one of the following:
    * a ``frame`` element
    * an ``iframe`` element

    The query will match frames that meet one of the following criteria:
    * the element ``id`` exactly matches the locator
    * the element ``name`` exactly matches the locator

    Args:
        locator (str): A string that identifies the desired frames.

    Returns:
        Expression: An :class:`Expression` object matching the desired frames.
    """

    frames = x.descendant("frame") + x.descendant("iframe")
    return frames[x.attr("id").equals(locator) | x.attr("name").equals(locator)]

def button(locator):
    """
    Returns an :class:`Expression` for finding buttons matching the given locator.

    The query defines a button as one of the following:
    * a ``button`` element
    * an ``input`` element with a ``type`` of "button"
    * an ``input`` element with a ``type`` of "image"
    * an ``input`` element with a ``type`` of "reset"
    * an ``input`` element with a ``type`` of "submit"

    The query will match buttons that meet at least one of the following criteria:
    * the element ``id`` exactly matches the locator
    * the element ``value`` matches the locator
    * the element ``title`` matches the locator
    * the element text matches the locator
    * the element ``alt`` of an "image" ``input`` element matches the locator

    Args:
        locator (str): A string that identifies the desired buttons.

    Returns:
        Expression: An :class:`Expression` object matching the desired buttons.
    """

    expr = x.descendant("button")[
        x.attr("id").equals(locator) |
        x.attr("value").is_(locator) |
        x.attr("title").is_(locator) |
        x.string.n.is_(locator)]
    expr += x.descendant("input")[x.attr("type").one_of("submit", "reset", "image", "button")][
        x.attr("id").equals(locator) |
        x.attr("value").is_(locator) |
        x.attr("title").is_(locator) |
        x.string.n.is_(locator)]
    expr += x.descendant("input")[x.attr("type").equals("image")][x.attr("alt").is_(locator)]

    return expr

    def test_finds_nodes_which_are_exactly_preceding_the_current_node(self):
        woo_div = x.descendant("p")[x.attr("id").equals("wooDiv")]
        gorilla = x.descendant("p")[x.attr("title").equals("gorilla")]

        xpath = to_xpath(woo_div.previous_sibling("p"))
        results = self.find_all(xpath)
        self.assertEqual(inner_text(results[0]), "Bax")

        xpath = to_xpath(woo_div.previous_sibling("ul", "p"))
        results = self.find_all(xpath)
        self.assertEqual(inner_text(results[0]), "Bax")

        xpath = to_xpath(gorilla.previous_sibling("ul", "p"))
        results = self.find_all(xpath)
        self.assertEqual(inner_text(results[0]), "A list")

        xpath = to_xpath(woo_div.previous_sibling("ul", "li"))
        results = self.find_all(xpath)
        self.assertSequenceEqual(results, [])

        xpath = to_xpath(woo_div.previous_sibling())
        results = self.find_all(xpath)
        self.assertEqual(inner_text(results[0]), "Bax")