From 762309cd3c1f2b1711b201a7223a8661fa4f885a Mon Sep 17 00:00:00 2001
From: Dylan Gordon <3656794+agentdylan@users.noreply.github.com>
Date: Wed, 6 Dec 2023 23:42:58 +1300
Subject: [PATCH] docs: add query ByRole performance notes

---
 docs/queries/byrole.mdx | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/queries/byrole.mdx b/docs/queries/byrole.mdx
index c0f94a52c..7c70db2f7 100644
--- a/docs/queries/byrole.mdx
+++ b/docs/queries/byrole.mdx
@@ -462,3 +462,20 @@ You can query a specific element like this
 ```js
 getByRole('alertdialog', {description: 'Your session is about to expire'})
 ```
+
+## Performance
+
+`getByRole` is the most preferred query to use as it most closely resembles the
+user experience, however the calculations it must perform to provide this
+confidence can be expensive (particularly with large DOM trees).
+
+Where test performance is a concern it may be desirable to trade some of this
+confidence for improved performance.
+
+`getByRole` performance can be improved by setting the option
+[`hidden`](#hidden) to `true` and thereby avoid expensive visibility checks.
+Note that in doing so inaccessible elements will now be included in the result.
+
+Another option may be to substitute `getByRole` for simpler `getByLabelText` and
+`getByText` queries which can be significantly faster though less robust
+alternatives.