fix(dom): remove option from get_by and find_by queries

DanielleHuisman · DanielleHuisman · commit 5de1148c871a · 2025-08-16T14:36:05.000+02:00
diff --git a/book/src/core/user-actions/firing-events.md b/book/src/core/user-actions/firing-events.md
@@ -26,9 +26,7 @@ event.set_bubbles(true);
 event.set_cancelable(true);
 
 fire_event(
-    get_by_text(&container, "Submit")
-        .expect("Get should succeed.")
-        .expect("Get should return an element."),
+    get_by_text(&container, "Submit").expect("Get should succeed."),
     &event,
 ).expect("Event should be fired.");
 ```
diff --git a/packages/dom/src/get_queries_for_element.rs b/packages/dom/src/get_queries_for_element.rs
@@ -19,29 +19,29 @@ macro_rules! queries_for_element {
     ($(($name:ident, $matcher_type:ty, $options_type:ty)),*,) => {
         paste::paste! {
             impl BoundFunctions {
-                $(pub fn [< find_by_ $name >]<M: Into<$matcher_type>>(
+                $(pub async fn [< find_by_ $name >]<M: Into<$matcher_type>>(
                     &self,
                     matcher: M,
                     options: $options_type,
                     wait_for_options: WaitForOptions,
-                ) -> Result<Option<HtmlElement>, QueryError> {
-                    [< find_by_ $name >](&self.element, matcher, options, wait_for_options)
+                ) -> Result<HtmlElement, QueryError> {
+                    [< find_by_ $name >](&self.element, matcher, options, wait_for_options).await
                 })*
 
-                $(pub fn [< find_all_by_ $name >]<M: Into<$matcher_type>>(
+                $(pub async fn [< find_all_by_ $name >]<M: Into<$matcher_type>>(
                     &self,
                     matcher: M,
                     options: $options_type,
                     wait_for_options: WaitForOptions,
                 ) -> Result<Vec<HtmlElement>, QueryError> {
-                    [< find_all_by_ $name >](&self.element, matcher, options, wait_for_options)
+                    [< find_all_by_ $name >](&self.element, matcher, options, wait_for_options).await
                 })*
 
                 $(pub fn [< get_by_ $name >]<M: Into<$matcher_type>>(
                     &self,
                     matcher: M,
                     options: $options_type,
-                ) -> Result<Option<HtmlElement>, QueryError> {
+                ) -> Result<HtmlElement, QueryError> {
                     [< get_by_ $name >](&self.element, matcher, options)
                 })*
 
diff --git a/packages/dom/src/lib.rs b/packages/dom/src/lib.rs
@@ -20,6 +20,7 @@ pub use config::{configure, get_config};
 pub use error::QueryError;
 pub use events::*;
 pub use get_node_text::*;
+pub use get_queries_for_element::get_queries_for_element as within;
 pub use get_queries_for_element::*;
 pub use matches::get_default_normalizer;
 pub use pretty_dom::*;
@@ -34,4 +35,5 @@ pub use types::*;
 pub use wait_for::*;
 
 // TODO: Export useful types from `aria_query`.
+#[doc(no_inline)]
 pub use aria_query::{AriaRole, AriaRoleDefinitionKey};
diff --git a/packages/dom/src/queries/alt_text.rs b/packages/dom/src/queries/alt_text.rs
@@ -8,7 +8,7 @@ use crate::{
     types::{Matcher, MatcherOptions},
 };
 
-pub fn _query_all_by_alt_text<M: Into<Matcher>>(
+pub(crate) fn _query_all_by_alt_text<M: Into<Matcher>>(
     container: &HtmlElement,
     alt: M,
     options: MatcherOptions,
diff --git a/packages/dom/src/queries/display_value.rs b/packages/dom/src/queries/display_value.rs
@@ -10,7 +10,7 @@ use crate::{
     util::{html_collection_to_vec, node_list_to_vec},
 };
 
-pub fn _query_all_by_display_value<M: Into<Matcher>>(
+pub(crate) fn _query_all_by_display_value<M: Into<Matcher>>(
     container: &HtmlElement,
     value: M,
     options: MatcherOptions,
diff --git a/packages/dom/src/queries/label_text.rs b/packages/dom/src/queries/label_text.rs
@@ -10,7 +10,7 @@ use crate::{
     util::node_list_to_vec,
 };
 
-pub fn _query_all_by_label_text<M: Into<Matcher>>(
+pub(crate) fn _query_all_by_label_text<M: Into<Matcher>>(
     container: &HtmlElement,
     text: M,
     options: SelectorMatcherOptions,
diff --git a/packages/dom/src/queries/placeholder_text.rs b/packages/dom/src/queries/placeholder_text.rs
@@ -7,7 +7,7 @@ use crate::{
     types::{Matcher, MatcherOptions},
 };
 
-pub fn _query_all_by_placeholder_text<M: Into<Matcher>>(
+pub(crate) fn _query_all_by_placeholder_text<M: Into<Matcher>>(
     container: &HtmlElement,
     text: M,
     options: MatcherOptions,
diff --git a/packages/dom/src/queries/role.rs b/packages/dom/src/queries/role.rs
@@ -21,7 +21,7 @@ use crate::{
     util::node_list_to_vec,
 };
 
-pub fn _query_all_by_role<M: Into<ByRoleMatcher>>(
+pub(crate) fn _query_all_by_role<M: Into<ByRoleMatcher>>(
     container: &HtmlElement,
     role: M,
     options: ByRoleOptions,
diff --git a/packages/dom/src/queries/test_id.rs b/packages/dom/src/queries/test_id.rs
@@ -12,7 +12,7 @@ fn get_test_id_attribute() -> String {
     get_config().test_id_attribute
 }
 
-pub fn _query_all_by_test_id<M: Into<Matcher>>(
+pub(crate) fn _query_all_by_test_id<M: Into<Matcher>>(
     container: &HtmlElement,
     id: M,
     options: MatcherOptions,
diff --git a/packages/dom/src/queries/text.rs b/packages/dom/src/queries/text.rs
@@ -10,7 +10,7 @@ use crate::{
     util::node_list_to_vec,
 };
 
-pub fn _query_all_by_text<M: Into<Matcher>>(
+pub(crate) fn _query_all_by_text<M: Into<Matcher>>(
     container: &HtmlElement,
     text: M,
     options: SelectorMatcherOptions,
diff --git a/packages/dom/src/queries/title.rs b/packages/dom/src/queries/title.rs
@@ -18,7 +18,7 @@ fn is_svg_title(node: &HtmlElement) -> bool {
             .is_some_and(|parent_node| parent_node.tag_name().to_lowercase() == "svg")
 }
 
-pub fn _query_all_by_title<M: Into<Matcher>>(
+pub(crate) fn _query_all_by_title<M: Into<Matcher>>(
     container: &HtmlElement,
     text: M,
     options: MatcherOptions,
diff --git a/packages/dom/src/query_helpers.rs b/packages/dom/src/query_helpers.rs
@@ -93,12 +93,12 @@ pub fn get_suggestion_error(suggestion: String, container: Element) -> QueryErro
 
 #[macro_export]
 macro_rules! make_single_query {
-    ($all_query:ident, $get_multiple_error:ident, $name:ident, $matcher_type:ty, $options_type:ty) => {
+    ($all_query:ident, $get_multiple_error:ident, $name:ident, $matcher_type:ty, $options_type:ty, $return_type:ty, $func:ident $(,$args:literal)*) => {
         pub fn $name<M: Into<$matcher_type>>(
             container: &HtmlElement,
             matcher: M,
             options: $options_type,
-        ) -> Result<Option<HtmlElement>, QueryError> {
+        ) -> Result<$return_type, QueryError> {
             let matcher = matcher.into();
 
             let mut els = $all_query(container, matcher.clone(), options.clone())?;
@@ -118,7 +118,7 @@ macro_rules! make_single_query {
                     container.clone().into(),
                 ))
             } else {
-                Ok(els.pop())
+                Ok(Vec::$func(&mut els $(,$args)*))
             }
         }
     };
@@ -150,7 +150,7 @@ macro_rules! make_get_all_query {
 #[macro_export]
 macro_rules! make_find_query {
     ($getter:ident, $name:ident, $matcher_type:ty, $options_type:ty, $return_type:ty) => {
-        pub fn $name<M: Into<$matcher_type>>(
+        pub async fn $name<M: Into<$matcher_type>>(
             container: &HtmlElement,
             matcher: M,
             options: $options_type,
@@ -164,22 +164,23 @@ macro_rules! make_find_query {
                 },
                 wait_for_options.container(container.clone()),
             )
+            .await
         }
     };
 }
 
 #[macro_export]
 macro_rules! wrap_single_query_with_suggestion {
-    ($query:ident, $query_by_all_name:expr_2021, $variant:expr_2021, $name:ident, $matcher_type:ty, $options_type:ty) => {
+    ($query:ident, $query_by_all_name:expr, $variant:expr, $name:ident, $matcher_type:ty, $options_type:ty, $return_type:ty) => {
         pub fn $name<M: Into<$matcher_type>>(
             container: &HtmlElement,
             matcher: M,
             options: $options_type,
-        ) -> Result<Option<HtmlElement>, QueryError> {
+        ) -> Result<$return_type, QueryError> {
             let element = $query(container, matcher, options)?;
             let suggest = get_config().throw_suggestions;
 
-            if let Some(element) = element.as_ref() {
+            if let Some(element) = Option::<&HtmlElement>::from(&element) {
                 if suggest {
                     let suggestion = get_suggested_query(element, Some($variant), None);
                     if let Some(suggestion) = suggestion {
@@ -200,7 +201,7 @@ macro_rules! wrap_single_query_with_suggestion {
 
 #[macro_export]
 macro_rules! wrap_all_by_query_with_suggestion {
-    ($query:ident, $query_by_all_name:expr_2021, $variant:expr_2021, $name:ident, $matcher_type:ty, $options_type:ty) => {
+    ($query:ident, $query_by_all_name:expr, $variant:expr, $name:ident, $matcher_type:ty, $options_type:ty) => {
         pub fn $name<M: Into<$matcher_type>>(
             container: &HtmlElement,
             matcher: M,
@@ -240,10 +241,10 @@ macro_rules! build_queries {
                 $crate::wrap_all_by_query_with_suggestion!($query_by_all, stringify!($query_by_all), Variant::QueryAll, [<query_all_by_ $name>], $matcher_type, $options_type);
 
                 // Internal query by
-                $crate::make_single_query!($query_by_all, $get_multiple_error, [<_query_by_ $name>], $matcher_type, $options_type);
+                $crate::make_single_query!($query_by_all, $get_multiple_error, [<_query_by_ $name>], $matcher_type, $options_type, Option<HtmlElement>, pop);
 
                 // Query by
-                $crate::wrap_single_query_with_suggestion!([<_query_by_ $name>], stringify!($query_by_all), Variant::Query, [<query_by_ $name>], $matcher_type, $options_type);
+                $crate::wrap_single_query_with_suggestion!([<_query_by_ $name>], stringify!($query_by_all), Variant::Query, [<query_by_ $name>], $matcher_type, $options_type, Option<HtmlElement>);
 
                 // Internal get all by
                 $crate::make_get_all_query!($query_by_all, $get_missing_error, [<_get_all_by_ $name>], $matcher_type, $options_type);
@@ -252,10 +253,10 @@ macro_rules! build_queries {
                 $crate::wrap_all_by_query_with_suggestion!([<_get_all_by_ $name>], stringify!($query_by_all).replace("query", "get"), Variant::GetAll, [<get_all_by_ $name>], $matcher_type, $options_type);
 
                 // Internal get by
-                $crate::make_single_query!([<_get_all_by_ $name>], $get_multiple_error, [<_get_by_ $name>], $matcher_type, $options_type);
+                $crate::make_single_query!([<_get_all_by_ $name>], $get_multiple_error, [<_get_by_ $name>], $matcher_type, $options_type, HtmlElement, swap_remove, 0);
 
                 // Get by
-                $crate::wrap_single_query_with_suggestion!([<_get_by_ $name>], stringify!($query_by_all), Variant::Get, [<get_by_ $name>], $matcher_type, $options_type);
+                $crate::wrap_single_query_with_suggestion!([<_get_by_ $name>], stringify!($query_by_all), Variant::Get, [<get_by_ $name>], $matcher_type, $options_type, HtmlElement);
 
                 // Internal find all by
                 $crate::wrap_all_by_query_with_suggestion!([<_get_all_by_ $name>], stringify!($query_by_all), Variant::FindAll, [<_find_all_by_ $name>], $matcher_type, $options_type);
@@ -264,10 +265,10 @@ macro_rules! build_queries {
                 $crate::make_find_query!([<_find_all_by_ $name>], [<find_all_by_ $name>], $matcher_type, $options_type, Vec<HtmlElement>);
 
                 // Internal find by
-                $crate::wrap_single_query_with_suggestion!([<_get_by_ $name>], stringify!($query_by_all), Variant::Find, [<_find_by_ $name>], $matcher_type, $options_type);
+                $crate::wrap_single_query_with_suggestion!([<_get_by_ $name>], stringify!($query_by_all), Variant::Find, [<_find_by_ $name>], $matcher_type, $options_type, HtmlElement);
 
                 // Find by
-                $crate::make_find_query!([<_find_by_ $name>], [<find_by_ $name>], $matcher_type, $options_type, Option<HtmlElement>);
+                $crate::make_find_query!([<_find_by_ $name>], [<find_by_ $name>], $matcher_type, $options_type, HtmlElement);
             }
         }
     };
diff --git a/packages/dom/src/wait_for.rs b/packages/dom/src/wait_for.rs
@@ -1,5 +1,5 @@
 use crate::types::WaitForOptions;
 
-pub fn wait_for<T>(callback: Box<dyn Fn() -> T>, _options: WaitForOptions) -> T {
+pub async fn wait_for<T>(callback: Box<dyn Fn() -> T>, _options: WaitForOptions) -> T {
     callback()
 }
diff --git a/packages/dom/tests/aria_attributes.rs b/packages/dom/tests/aria_attributes.rs
@@ -103,14 +103,12 @@ fn busy_true_false_matches_busy_regions() {
     assert!(
         container_queries
             .get_by_role(AriaRole::Log, ByRoleOptions::default().busy(true))
-            .expect("Get should succeed.")
-            .is_some(),
+            .is_ok()
     );
     assert!(
         container_queries
             .get_by_role(AriaRole::Log, ByRoleOptions::default().busy(false))
-            .expect("Get should succeed.")
-            .is_some(),
+            .is_ok()
     );
 }
 
@@ -128,14 +126,12 @@ fn checked_true_false_matches_checked_checkboxes() {
     assert!(
         container_queries
             .get_by_role(AriaRole::Checkbox, ByRoleOptions::default().checked(true))
-            .expect("Get should succeed.")
-            .is_some(),
+            .is_ok()
     );
     assert!(
         container_queries
             .get_by_role(AriaRole::Checkbox, ByRoleOptions::default().checked(false))
-            .expect("Get should succeed.")
-            .is_some(),
+            .is_ok(),
     );
 }
 
@@ -153,14 +149,12 @@ fn checked_true_false_matches_checked_elements_with_proper_role() {
     assert!(
         container_queries
             .get_by_role(AriaRole::Checkbox, ByRoleOptions::default().checked(true))
-            .expect("Get should succeed.")
-            .is_some(),
+            .is_ok()
     );
     assert!(
         container_queries
             .get_by_role(AriaRole::Checkbox, ByRoleOptions::default().checked(false))
-            .expect("Get should succeed.")
-            .is_some(),
+            .is_ok()
     );
 }
 
@@ -179,13 +173,11 @@ fn checked_true_false_does_not_match_element_in_indeterminate_state() {
     container_queries
         .get_by_label_text("indeteminate yes", SelectorMatcherOptions::default())
         .expect("Get should succeed.")
-        .expect("Get should return a result.")
         .unchecked_into::<HtmlInputElement>()
         .set_indeterminate(true);
     container_queries
         .get_by_label_text("indeteminate no", SelectorMatcherOptions::default())
         .expect("Get should succeed.")
-        .expect("Get should return a result.")
         .unchecked_into::<HtmlInputElement>()
         .set_indeterminate(true);
 
diff --git a/packages/dom/tests/element_queries.rs b/packages/dom/tests/element_queries.rs
diff --git a/packages/dom/tests/role_helpers.rs b/packages/dom/tests/role_helpers.rs

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ fn get_test_id_attribute() -> String {`
`12`	`12`	`get_config().test_id_attribute`
`13`	`13`	`}`
`14`	`14`
`15`		`-pub fn _query_all_by_test_id<M: Into<Matcher>>(`
	`15`	`+pub(crate) fn _query_all_by_test_id<M: Into<Matcher>>(`
`16`	`16`	`container: &HtmlElement,`
`17`	`17`	`id: M,`
`18`	`18`	`options: MatcherOptions,`