From 2add3129ccbe2f2ad7046f70c559129f1063252e Mon Sep 17 00:00:00 2001
From: Tim Fischbach <tfischbach@codevise.de>
Date: Tue, 23 Sep 2025 09:48:04 +0200
Subject: [PATCH] feat(ByRole): Treat inert subtrees as hidden in role queries

https://html.spec.whatwg.org/multipage/interaction.html#inert-subtrees:

   Inert nodes generally cannot be focused, and user agents do not
   expose the inert nodes to accessibility APIs or assistive
   technologies.

Since jsdom does not yet fully support the `inert` attribute [1], we
use `element.hasAttribute('inert')` instead of `element.inert`.

fixes #1364

[1] https://github.com/jsdom/jsdom/issues/3605
---
 src/__tests__/role-helpers.js |  1 +
 src/__tests__/role.js         | 19 +++++++++++++++++++
 src/role-helpers.js           |  4 ++++
 3 files changed, 24 insertions(+)

diff --git a/src/__tests__/role-helpers.js b/src/__tests__/role-helpers.js
index f47daa42..3735a352 100644
--- a/src/__tests__/role-helpers.js
+++ b/src/__tests__/role-helpers.js
@@ -205,6 +205,7 @@ test.each([
   ['<div style="display: none;"/>', true],
   ['<div style="visibility: hidden;"/>', true],
   ['<div aria-hidden="true" />', true],
+  ['<div inert />', true],
 ])('shouldExcludeFromA11yTree for %s returns %p', (html, expected) => {
   const {container} = render(html)
   container.firstChild.appendChild(document.createElement('button'))
diff --git a/src/__tests__/role.js b/src/__tests__/role.js
index cf598583..d5e0cf81 100644
--- a/src/__tests__/role.js
+++ b/src/__tests__/role.js
@@ -175,6 +175,25 @@ test('by default excludes elements which have aria-hidden="true" or any of their
   `)
 })
 
+test('by default excludes elements which have inert attribute or any of their parents', () => {
+  const {getByRole} = render('<div inert><ul /></div>')
+
+  expect(() => getByRole('list')).toThrowErrorMatchingInlineSnapshot(`
+    Unable to find an accessible element with the role "list"
+
+    There are no accessible roles. But there might be some inaccessible roles. If you wish to access them, then set the \`hidden\` option to \`true\`. Learn more about this here: https://testing-library.com/docs/dom-testing-library/api-queries#byrole
+
+    Ignored nodes: comments, script, style
+    <div>
+      <div
+        inert=""
+      >
+        <ul />
+      </div>
+    </div>
+  `)
+})
+
 test('considers the computed visibility style not the parent', () => {
   // this behavior deviates from the spec which includes "any descendant"
   // if visibility is hidden. However, chrome a11y tree and nvda will include
diff --git a/src/role-helpers.js b/src/role-helpers.js
index 8d7e7cb0..9e931016 100644
--- a/src/role-helpers.js
+++ b/src/role-helpers.js
@@ -21,6 +21,10 @@ function isSubtreeInaccessible(element) {
     return true
   }
 
+  if (element.hasAttribute('inert')) {
+    return true
+  }
+
   const window = element.ownerDocument.defaultView
   if (window.getComputedStyle(element).display === 'none') {
     return true