<commit_before>[[navigator]]
= Interacting with content

Geb provides a concise and Groovy interface to the content and controls in your browser.
This is implemented through the `Navigator` API which is a jQuery inspired mechanism for finding, filtering and interacting with DOM elements.

== The `$()` function

The `$()` function is the access point to the browser's page content.
It returns a `{navigator-api}` object that is roughly analogous to a jQuery object.
It is analogous in that it represents one or more elements on the page and can be used to refine the matched content or query the matched content.
When a `$()` function is called that does not match any content, an “empty” navigator object is returned that represents no content.
Operations on “empty” navigators return `null` or another “empty” navigator or other values that make sense (e.g. the `size()` method returns `0`).

The signature of the `$()` function is as follows…

[source,groovy]
----
$(«css selector», «index or range», «attribute / text matchers»)
----

The following is a concrete example…

[source,groovy]
----
include::{test-dir}/navigator/DollarExamplesSpec.groovy[tag=concrete_example,indent=0]
----

This would find the 3rd (elements are 0 indexed) `h1` element whose `class` _attribute_ is exactly “`heading`”.

All arguments are optional, meaning the following calls are all valid:

[source,groovy]
----
include::{test-dir}/navigator/DollarExamplesSpec.groovy[tag=other_examples,indent=0]
----

[NOTE]
====
There is an alias for the dollar function named “find” if a method named “$” is not to your taste.
====

=== CSS Selectors

You can use any CSS selector that the underlying `WebDriver` supports…

[source,groovy]
----
include::{test-dir}/navigator/DollarExamplesSpec.groovy[tag=css3_selectors,indent=0]
----

HTMLUnit driver only partially supports CSS 3.
A future version of the HTMLUnit driver may gain better CSS 3 support.

=== Using WebDriver's `By` class selectors

For all signatures of `$()` function that accept a css selector there is an equivalent signature where an instance of WebDriver's `{by-api}` class can be used instead of a `String`.

Using CSS selectors is the idiomatic way of using Geb and should be preferred to using `By` selectors.
It is always possible to select the same elements using a css selector as when using a certain `By` selector apart from certain XPath selectors which is why this convenience mechanism is provided.

Following are some examples of using `By` selectors…

[source,groovy]
----
include::{test-dir}/navigator/DollarExamplesSpec.groovy[tag=by_selectors,indent=0]
----

=== Indexes and ranges

When matching, a single positive integer or integer range can be given to restrict by index.

Consider the following html…

[source,html]
----
include::{test-dir}/navigator/DollarExamplesSpec.groovy[tag=indexes_and_ranges_html,indent=0]
----

We can use indexes to match content like so…<commit_msg>Remove outdated information about HtmlUnit CSS3 capabilities from the manual<commit_after>[[navigator]]
= Interacting with content

Geb provides a concise and Groovy interface to the content and controls in your browser.
This is implemented through the `Navigator` API which is a jQuery inspired mechanism for finding, filtering and interacting with DOM elements.

== The `$()` function

The `$()` function is the access point to the browser's page content.
It returns a `{navigator-api}` object that is roughly analogous to a jQuery object.
It is analogous in that it represents one or more elements on the page and can be used to refine the matched content or query the matched content.
When a `$()` function is called that does not match any content, an “empty” navigator object is returned that represents no content.
Operations on “empty” navigators return `null` or another “empty” navigator or other values that make sense (e.g. the `size()` method returns `0`).

The signature of the `$()` function is as follows…

[source,groovy]
----
$(«css selector», «index or range», «attribute / text matchers»)
----

The following is a concrete example…

[source,groovy]
----
include::{test-dir}/navigator/DollarExamplesSpec.groovy[tag=concrete_example,indent=0]
----

This would find the 3rd (elements are 0 indexed) `h1` element whose `class` _attribute_ is exactly “`heading`”.

All arguments are optional, meaning the following calls are all valid:

[source,groovy]
----
include::{test-dir}/navigator/DollarExamplesSpec.groovy[tag=other_examples,indent=0]
----

[NOTE]
====
There is an alias for the dollar function named “find” if a method named “$” is not to your taste.
====

=== CSS Selectors

You can use any CSS selector that the underlying `WebDriver` implementation supports…

[source,groovy]
----
include::{test-dir}/navigator/DollarExamplesSpec.groovy[tag=css3_selectors,indent=0]
----

=== Using WebDriver's `By` class selectors

For all signatures of `$()` function that accept a css selector there is an equivalent signature where an instance of WebDriver's `{by-api}` class can be used instead of a `String`.

Using CSS selectors is the idiomatic way of using Geb and should be preferred to using `By` selectors.
It is always possible to select the same elements using a css selector as when using a certain `By` selector apart from certain XPath selectors which is why this convenience mechanism is provided.

Following are some examples of using `By` selectors…

[source,groovy]
----
include::{test-dir}/navigator/DollarExamplesSpec.groovy[tag=by_selectors,indent=0]
----

=== Indexes and ranges

When matching, a single positive integer or integer range can be given to restrict by index.

Consider the following html…

[source,html]
----
include::{test-dir}/navigator/DollarExamplesSpec.groovy[tag=indexes_and_ranges_html,indent=0]
----

We can use indexes to match content like so…
{'fraction_non_alphanumeric': 0.09649272882805816, 'fraction_numerical': 0.003934987168520102, 'mean_word_length': 4.753937007874016, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2551179', 'n_tokens_mistral': 1652, 'n_tokens_neox': 1582, 'n_words': 753}