From fbaebfb19c6926e6e2b6e4997f1f36a5cd0c9be5 Mon Sep 17 00:00:00 2001
From: Scott Sauber <stsauber@gmail.com>
Date: Tue, 24 Mar 2026 15:33:44 -0700
Subject: [PATCH 1/3] feat: add findbyrole

---
 src/bunit.web.query/ByRoleElementFactory.cs   |  31 ++
 .../Roles/AccessibleNameCalculator.cs         | 130 ++++++
 src/bunit.web.query/Roles/AriaRole.cs         | 183 ++++++++
 src/bunit.web.query/Roles/ByRoleOptions.cs    |  66 +++
 .../Roles/ImplicitRoleMapping.cs              |  94 ++++
 .../Roles/RoleNotFoundException.cs            |  53 +++
 .../Roles/RoleQueryExtensions.cs              | 350 +++++++++++++++
 .../BlazorE2E/RoleQueryCounter.razor          |   9 +
 .../Roles/RoleQueryExtensionsTest.cs          | 405 ++++++++++++++++++
 9 files changed, 1321 insertions(+)
 create mode 100644 src/bunit.web.query/ByRoleElementFactory.cs
 create mode 100644 src/bunit.web.query/Roles/AccessibleNameCalculator.cs
 create mode 100644 src/bunit.web.query/Roles/AriaRole.cs
 create mode 100644 src/bunit.web.query/Roles/ByRoleOptions.cs
 create mode 100644 src/bunit.web.query/Roles/ImplicitRoleMapping.cs
 create mode 100644 src/bunit.web.query/Roles/RoleNotFoundException.cs
 create mode 100644 src/bunit.web.query/Roles/RoleQueryExtensions.cs
 create mode 100644 tests/bunit.testassets/BlazorE2E/RoleQueryCounter.razor
 create mode 100644 tests/bunit.web.query.tests/Roles/RoleQueryExtensionsTest.cs

diff --git a/src/bunit.web.query/ByRoleElementFactory.cs b/src/bunit.web.query/ByRoleElementFactory.cs
new file mode 100644
index 000000000..153efd344
--- /dev/null
+++ b/src/bunit.web.query/ByRoleElementFactory.cs
@@ -0,0 +1,31 @@
+using AngleSharp.Dom;
+using Bunit.Web.AngleSharp;
+
+namespace Bunit;
+
+internal sealed class ByRoleElementFactory : IElementWrapperFactory
+{
+	private readonly IRenderedComponent<IComponent> testTarget;
+	private readonly AriaRole role;
+	private readonly ByRoleOptions options;
+
+	public Action? OnElementReplaced { get; set; }
+
+	public ByRoleElementFactory(IRenderedComponent<IComponent> testTarget, AriaRole role, ByRoleOptions options)
+	{
+		this.testTarget = testTarget;
+		this.role = role;
+		this.options = options;
+		testTarget.OnMarkupUpdated += FragmentsMarkupUpdated;
+	}
+
+	private void FragmentsMarkupUpdated(object? sender, EventArgs args)
+		=> OnElementReplaced?.Invoke();
+
+	public TElement GetElement<TElement>() where TElement : class, IElement
+	{
+		var element = testTarget.FindByRoleInternal(role, options) as TElement;
+
+		return element ?? throw new ElementRemovedFromDomException(role.ToRoleString());
+	}
+}
diff --git a/src/bunit.web.query/Roles/AccessibleNameCalculator.cs b/src/bunit.web.query/Roles/AccessibleNameCalculator.cs
new file mode 100644
index 000000000..33f8dce83
--- /dev/null
+++ b/src/bunit.web.query/Roles/AccessibleNameCalculator.cs
@@ -0,0 +1,130 @@
+using AngleSharp.Dom;
+
+namespace Bunit.Roles;
+
+internal static class AccessibleNameCalculator
+{
+	internal static string? GetAccessibleName(IElement element, INodeList rootNodes)
+	{
+		// 1. aria-labelledby — resolve each referenced ID, join with spaces
+		var labelledBy = element.GetAttribute("aria-labelledby");
+		if (!string.IsNullOrEmpty(labelledBy))
+		{
+			var ids = labelledBy.Split(' ', StringSplitOptions.RemoveEmptyEntries);
+			var parts = new List<string>();
+			foreach (var id in ids)
+			{
+				var referenced = rootNodes.TryQuerySelector($"#{id}");
+				if (referenced is not null)
+				{
+					var text = referenced.TextContent.Trim();
+					if (!string.IsNullOrEmpty(text))
+						parts.Add(text);
+				}
+			}
+
+			if (parts.Count > 0)
+				return string.Join(" ", parts);
+		}
+
+		// 2. aria-label attribute
+		var ariaLabel = element.GetAttribute("aria-label");
+		if (!string.IsNullOrEmpty(ariaLabel))
+			return ariaLabel.Trim();
+
+		// 3. For IMG, AREA, INPUT[type=image]: alt attribute
+		var isImageInput = element.NodeName == "INPUT" &&
+			string.Equals(element.GetAttribute("type"), "image", StringComparison.OrdinalIgnoreCase);
+		if (element.NodeName is "IMG" or "AREA" || isImageInput)
+		{
+			var alt = element.GetAttribute("alt");
+			if (!string.IsNullOrEmpty(alt))
+				return alt.Trim();
+		}
+
+		// 4. For form controls: associated <label>
+		if (element.NodeName is "INPUT" or "SELECT" or "TEXTAREA" or "METER" or "OUTPUT" or "PROGRESS")
+		{
+			var labelName = GetLabelName(element, rootNodes);
+			if (labelName is not null)
+				return labelName;
+		}
+
+		// 5. Text content (for buttons, links, headings, etc.)
+		var textContent = element.TextContent.Trim();
+		if (!string.IsNullOrEmpty(textContent))
+			return textContent;
+
+		// 6. title attribute (fallback)
+		var title = element.GetAttribute("title");
+		if (!string.IsNullOrEmpty(title))
+			return title.Trim();
+
+		// 7. placeholder attribute (fallback for inputs)
+		if (element.NodeName is "INPUT" or "TEXTAREA")
+		{
+			var placeholder = element.GetAttribute("placeholder");
+			if (!string.IsNullOrEmpty(placeholder))
+				return placeholder.Trim();
+		}
+
+		return null;
+	}
+
+	private static string? GetLabelName(IElement element, INodeList rootNodes)
+	{
+		// Check for label via "for" attribute matching element's id
+		var id = element.GetAttribute("id");
+		if (!string.IsNullOrEmpty(id))
+		{
+			var labels = rootNodes.TryQuerySelectorAll($"label[for='{id}']");
+			foreach (var label in labels)
+			{
+				var text = label.TextContent.Trim();
+				if (!string.IsNullOrEmpty(text))
+					return text;
+			}
+		}
+
+		// Check for wrapping <label>
+		var parent = element.ParentElement;
+		while (parent is not null)
+		{
+			if (parent.NodeName == "LABEL")
+			{
+				var text = GetTextContentExcluding(parent, element).Trim();
+				if (!string.IsNullOrEmpty(text))
+					return text;
+			}
+
+			parent = parent.ParentElement;
+		}
+
+		return null;
+	}
+
+	private static string GetTextContentExcluding(IElement container, IElement excluded)
+	{
+		var parts = new List<string>();
+		CollectTextNodes(container, excluded, parts);
+		return string.Join("", parts);
+	}
+
+	private static void CollectTextNodes(INode node, IElement excluded, List<string> parts)
+	{
+		foreach (var child in node.ChildNodes)
+		{
+			if (child == excluded)
+				continue;
+
+			if (child.NodeType == NodeType.Text)
+			{
+				parts.Add(child.TextContent);
+			}
+			else if (child.NodeType == NodeType.Element)
+			{
+				CollectTextNodes(child, excluded, parts);
+			}
+		}
+	}
+}
diff --git a/src/bunit.web.query/Roles/AriaRole.cs b/src/bunit.web.query/Roles/AriaRole.cs
new file mode 100644
index 000000000..a854f923a
--- /dev/null
+++ b/src/bunit.web.query/Roles/AriaRole.cs
@@ -0,0 +1,183 @@
+namespace Bunit;
+
+/// <summary>
+/// Represents WAI-ARIA roles used to identify the type of an element.
+/// Mirrors Playwright.NET's AriaRole enum for familiarity.
+/// </summary>
+public enum AriaRole
+{
+	Alert,
+	AlertDialog,
+	Application,
+	Article,
+	Banner,
+	Blockquote,
+	Button,
+	Caption,
+	Cell,
+	Checkbox,
+	Code,
+	ColumnHeader,
+	Combobox,
+	Complementary,
+	ContentInfo,
+	Definition,
+	Deletion,
+	Dialog,
+	Directory,
+	Document,
+	Emphasis,
+	Feed,
+	Figure,
+	Form,
+	Generic,
+	Grid,
+	GridCell,
+	Group,
+	Heading,
+	Img,
+	Insertion,
+	Link,
+	List,
+	Listbox,
+	Listitem,
+	Log,
+	Main,
+	Mark,
+	Marquee,
+	Math,
+	Menu,
+	Menubar,
+	Menuitem,
+	Menuitemcheckbox,
+	Menuitemradio,
+	Meter,
+	Navigation,
+	None,
+	Note,
+	Option,
+	Paragraph,
+	Presentation,
+	Progressbar,
+	Radio,
+	Radiogroup,
+	Region,
+	Row,
+	Rowgroup,
+	Rowheader,
+	Scrollbar,
+	Search,
+	Searchbox,
+	Separator,
+	Slider,
+	Spinbutton,
+	Status,
+	Strong,
+	Subscript,
+	Superscript,
+	Switch,
+	Tab,
+	Table,
+	Tablist,
+	Tabpanel,
+	Term,
+	Textbox,
+	Time,
+	Timer,
+	Toolbar,
+	Tooltip,
+	Tree,
+	Treegrid,
+	Treeitem,
+}
+
+internal static class AriaRoleExtensions
+{
+	internal static string ToRoleString(this AriaRole role) => role switch
+	{
+		AriaRole.Alert => "alert",
+		AriaRole.AlertDialog => "alertdialog",
+		AriaRole.Application => "application",
+		AriaRole.Article => "article",
+		AriaRole.Banner => "banner",
+		AriaRole.Blockquote => "blockquote",
+		AriaRole.Button => "button",
+		AriaRole.Caption => "caption",
+		AriaRole.Cell => "cell",
+		AriaRole.Checkbox => "checkbox",
+		AriaRole.Code => "code",
+		AriaRole.ColumnHeader => "columnheader",
+		AriaRole.Combobox => "combobox",
+		AriaRole.Complementary => "complementary",
+		AriaRole.ContentInfo => "contentinfo",
+		AriaRole.Definition => "definition",
+		AriaRole.Deletion => "deletion",
+		AriaRole.Dialog => "dialog",
+		AriaRole.Directory => "directory",
+		AriaRole.Document => "document",
+		AriaRole.Emphasis => "emphasis",
+		AriaRole.Feed => "feed",
+		AriaRole.Figure => "figure",
+		AriaRole.Form => "form",
+		AriaRole.Generic => "generic",
+		AriaRole.Grid => "grid",
+		AriaRole.GridCell => "gridcell",
+		AriaRole.Group => "group",
+		AriaRole.Heading => "heading",
+		AriaRole.Img => "img",
+		AriaRole.Insertion => "insertion",
+		AriaRole.Link => "link",
+		AriaRole.List => "list",
+		AriaRole.Listbox => "listbox",
+		AriaRole.Listitem => "listitem",
+		AriaRole.Log => "log",
+		AriaRole.Main => "main",
+		AriaRole.Mark => "mark",
+		AriaRole.Marquee => "marquee",
+		AriaRole.Math => "math",
+		AriaRole.Menu => "menu",
+		AriaRole.Menubar => "menubar",
+		AriaRole.Menuitem => "menuitem",
+		AriaRole.Menuitemcheckbox => "menuitemcheckbox",
+		AriaRole.Menuitemradio => "menuitemradio",
+		AriaRole.Meter => "meter",
+		AriaRole.Navigation => "navigation",
+		AriaRole.None => "none",
+		AriaRole.Note => "note",
+		AriaRole.Option => "option",
+		AriaRole.Paragraph => "paragraph",
+		AriaRole.Presentation => "presentation",
+		AriaRole.Progressbar => "progressbar",
+		AriaRole.Radio => "radio",
+		AriaRole.Radiogroup => "radiogroup",
+		AriaRole.Region => "region",
+		AriaRole.Row => "row",
+		AriaRole.Rowgroup => "rowgroup",
+		AriaRole.Rowheader => "rowheader",
+		AriaRole.Scrollbar => "scrollbar",
+		AriaRole.Search => "search",
+		AriaRole.Searchbox => "searchbox",
+		AriaRole.Separator => "separator",
+		AriaRole.Slider => "slider",
+		AriaRole.Spinbutton => "spinbutton",
+		AriaRole.Status => "status",
+		AriaRole.Strong => "strong",
+		AriaRole.Subscript => "subscript",
+		AriaRole.Superscript => "superscript",
+		AriaRole.Switch => "switch",
+		AriaRole.Tab => "tab",
+		AriaRole.Table => "table",
+		AriaRole.Tablist => "tablist",
+		AriaRole.Tabpanel => "tabpanel",
+		AriaRole.Term => "term",
+		AriaRole.Textbox => "textbox",
+		AriaRole.Time => "time",
+		AriaRole.Timer => "timer",
+		AriaRole.Toolbar => "toolbar",
+		AriaRole.Tooltip => "tooltip",
+		AriaRole.Tree => "tree",
+		AriaRole.Treegrid => "treegrid",
+		AriaRole.Treeitem => "treeitem",
+		_ => throw new ArgumentOutOfRangeException(nameof(role), role, $"Unknown AriaRole value: {role}"),
+	};
+}
diff --git a/src/bunit.web.query/Roles/ByRoleOptions.cs b/src/bunit.web.query/Roles/ByRoleOptions.cs
new file mode 100644
index 000000000..6c7850d6b
--- /dev/null
+++ b/src/bunit.web.query/Roles/ByRoleOptions.cs
@@ -0,0 +1,66 @@
+namespace Bunit;
+
+/// <summary>
+/// Allows overrides of behavior for FindByRole method.
+/// </summary>
+public record class ByRoleOptions
+{
+	/// <summary>
+	/// The default behavior used by FindByRole if no overrides are specified.
+	/// </summary>
+	internal static readonly ByRoleOptions Default = new();
+
+	/// <summary>
+	/// Gets or sets the accessible name to filter by. When set, only elements whose
+	/// accessible name matches this value will be returned.
+	/// </summary>
+	public string? Name { get; set; }
+
+	/// <summary>
+	/// Gets or sets the heading level to filter by. Only applicable for the Heading role.
+	/// Matches aria-level attribute or implicit level from h1-h6 elements.
+	/// </summary>
+	public int? Level { get; set; }
+
+	/// <summary>
+	/// Gets or sets the checked state to filter by.
+	/// Matches aria-checked attribute or native checkbox/radio checked state.
+	/// Use null to not filter, true to match checked, false to match unchecked.
+	/// </summary>
+	public bool? Checked { get; set; }
+
+	/// <summary>
+	/// Gets or sets the pressed state to filter by.
+	/// Matches aria-pressed attribute on toggle buttons.
+	/// </summary>
+	public bool? Pressed { get; set; }
+
+	/// <summary>
+	/// Gets or sets the selected state to filter by.
+	/// Matches aria-selected attribute or native option selected state.
+	/// </summary>
+	public bool? Selected { get; set; }
+
+	/// <summary>
+	/// Gets or sets the expanded state to filter by.
+	/// Matches aria-expanded attribute.
+	/// </summary>
+	public bool? Expanded { get; set; }
+
+	/// <summary>
+	/// Gets or sets the disabled state to filter by.
+	/// Matches aria-disabled attribute or native disabled attribute.
+	/// </summary>
+	public bool? Disabled { get; set; }
+
+	/// <summary>
+	/// Gets or sets whether the Name match should be exact (default true).
+	/// When false, substring matching is used.
+	/// </summary>
+	public bool Exact { get; set; } = true;
+
+	/// <summary>
+	/// Gets or sets the StringComparison used for comparing the Name. Defaults to Ordinal (case sensitive).
+	/// </summary>
+	public StringComparison NameComparisonType { get; set; } = StringComparison.Ordinal;
+}
diff --git a/src/bunit.web.query/Roles/ImplicitRoleMapping.cs b/src/bunit.web.query/Roles/ImplicitRoleMapping.cs
new file mode 100644
index 000000000..79ffccfc5
--- /dev/null
+++ b/src/bunit.web.query/Roles/ImplicitRoleMapping.cs
@@ -0,0 +1,94 @@
+using AngleSharp.Dom;
+
+namespace Bunit.Roles;
+
+internal static class ImplicitRoleMapping
+{
+	internal static AriaRole? GetImplicitRole(IElement element) => element.NodeName switch
+	{
+		"A" => element.HasAttribute("href") ? AriaRole.Link : AriaRole.Generic,
+		"AREA" => element.HasAttribute("href") ? AriaRole.Link : AriaRole.Generic,
+		"ARTICLE" => AriaRole.Article,
+		"ASIDE" => AriaRole.Complementary,
+		"BUTTON" => AriaRole.Button,
+		"DATALIST" => AriaRole.Listbox,
+		"DETAILS" => AriaRole.Group,
+		"DIALOG" => AriaRole.Dialog,
+		"FIELDSET" => AriaRole.Group,
+		"FIGURE" => AriaRole.Figure,
+		"FOOTER" => AriaRole.ContentInfo,
+		"FORM" => HasAccessibleName(element) ? AriaRole.Form : null,
+		"H1" or "H2" or "H3" or "H4" or "H5" or "H6" => AriaRole.Heading,
+		"HEADER" => AriaRole.Banner,
+		"HR" => AriaRole.Separator,
+		"IMG" => GetImgRole(element),
+		"INPUT" => GetInputRole(element),
+		"LI" => AriaRole.Listitem,
+		"MAIN" => AriaRole.Main,
+		"MATH" => AriaRole.Math,
+		"MENU" or "OL" or "UL" => AriaRole.List,
+		"METER" => AriaRole.Meter,
+		"NAV" => AriaRole.Navigation,
+		"OPTION" => AriaRole.Option,
+		"OPTGROUP" => AriaRole.Group,
+		"OUTPUT" => AriaRole.Status,
+		"PROGRESS" => AriaRole.Progressbar,
+		"SEARCH" => AriaRole.Search,
+		"SECTION" => HasAccessibleName(element) ? AriaRole.Region : null,
+		"SELECT" => element.HasAttribute("multiple") ? AriaRole.Listbox : AriaRole.Combobox,
+		"TABLE" => AriaRole.Table,
+		"TBODY" or "THEAD" or "TFOOT" => AriaRole.Rowgroup,
+		"TD" => AriaRole.Cell,
+		"TEXTAREA" => AriaRole.Textbox,
+		"TH" => AriaRole.ColumnHeader,
+		"TR" => AriaRole.Row,
+		_ => null,
+	};
+
+	internal static int? GetHeadingLevel(IElement element)
+	{
+		// Check aria-level first
+		var ariaLevel = element.GetAttribute("aria-level");
+		if (ariaLevel is not null && int.TryParse(ariaLevel, out var level))
+			return level;
+
+		return element.NodeName switch
+		{
+			"H1" => 1,
+			"H2" => 2,
+			"H3" => 3,
+			"H4" => 4,
+			"H5" => 5,
+			"H6" => 6,
+			_ => null,
+		};
+	}
+
+	private static AriaRole? GetInputRole(IElement element)
+	{
+		var type = element.GetAttribute("type")?.ToUpperInvariant();
+		return type switch
+		{
+			null or "" or "TEXT" or "EMAIL" or "TEL" or "URL" or "PASSWORD" => AriaRole.Textbox,
+			"CHECKBOX" => AriaRole.Checkbox,
+			"RADIO" => AriaRole.Radio,
+			"RANGE" => AriaRole.Slider,
+			"NUMBER" => AriaRole.Spinbutton,
+			"SEARCH" => AriaRole.Searchbox,
+			"BUTTON" or "SUBMIT" or "RESET" or "IMAGE" => AriaRole.Button,
+			"HIDDEN" => null,
+			_ => AriaRole.Textbox,
+		};
+	}
+
+	private static AriaRole? GetImgRole(IElement element)
+	{
+		var alt = element.GetAttribute("alt");
+		return alt == string.Empty ? AriaRole.Presentation : AriaRole.Img;
+	}
+
+	private static bool HasAccessibleName(IElement element)
+	{
+		return element.HasAttribute("aria-label") || element.HasAttribute("aria-labelledby");
+	}
+}
diff --git a/src/bunit.web.query/Roles/RoleNotFoundException.cs b/src/bunit.web.query/Roles/RoleNotFoundException.cs
new file mode 100644
index 000000000..ae92c1bd6
--- /dev/null
+++ b/src/bunit.web.query/Roles/RoleNotFoundException.cs
@@ -0,0 +1,53 @@
+namespace Bunit;
+
+/// <summary>
+/// Represents a failure to find an element with the specified ARIA role.
+/// </summary>
+public sealed class RoleNotFoundException : Exception
+{
+	/// <summary>
+	/// Gets the ARIA role used to search with.
+	/// </summary>
+	public AriaRole Role { get; }
+
+	/// <summary>
+	/// Gets the options used during the search.
+	/// </summary>
+	public ByRoleOptions Options { get; }
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="RoleNotFoundException"/> class.
+	/// </summary>
+	public RoleNotFoundException(AriaRole role, ByRoleOptions options)
+		: base(BuildMessage(role, options))
+	{
+		Role = role;
+		Options = options;
+	}
+
+	private static string BuildMessage(AriaRole role, ByRoleOptions options)
+	{
+		var message = $"Unable to find an element with the role '{role.ToRoleString()}'";
+
+		var filters = new List<string>();
+		if (options.Name is not null)
+			filters.Add($"name: '{options.Name}'");
+		if (options.Level.HasValue)
+			filters.Add($"level: {options.Level.Value}");
+		if (options.Checked.HasValue)
+			filters.Add($"checked: {(options.Checked.Value == true ? "true" : "false")}");
+		if (options.Pressed.HasValue)
+			filters.Add($"pressed: {(options.Pressed.Value == true ? "true" : "false")}");
+		if (options.Selected.HasValue)
+			filters.Add($"selected: {(options.Selected.Value == true ? "true" : "false")}");
+		if (options.Expanded.HasValue)
+			filters.Add($"expanded: {(options.Expanded.Value == true ? "true" : "false")}");
+		if (options.Disabled.HasValue)
+			filters.Add($"disabled: {(options.Disabled.Value == true ? "true" : "false")}");
+
+		if (filters.Count > 0)
+			message += $" ({string.Join(", ", filters)})";
+
+		return message + ".";
+	}
+}
diff --git a/src/bunit.web.query/Roles/RoleQueryExtensions.cs b/src/bunit.web.query/Roles/RoleQueryExtensions.cs
new file mode 100644
index 000000000..a26d6ded6
--- /dev/null
+++ b/src/bunit.web.query/Roles/RoleQueryExtensions.cs
@@ -0,0 +1,350 @@
+using AngleSharp.Dom;
+using Bunit.Roles;
+using Bunit.Web.AngleSharp;
+
+namespace Bunit;
+
+/// <summary>
+/// Extension methods for querying <see cref="IRenderedComponent{TComponent}"/> by ARIA role.
+/// </summary>
+public static class RoleQueryExtensions
+{
+	/// <summary>
+	/// Returns the first element with the specified ARIA role.
+	/// </summary>
+	/// <param name="renderedComponent">The rendered fragment to search.</param>
+	/// <param name="role">The ARIA role to search for.</param>
+	/// <param name="configureOptions">Method used to override the default behavior of FindByRole.</param>
+	public static IElement FindByRole(this IRenderedComponent<IComponent> renderedComponent, AriaRole role, Action<ByRoleOptions>? configureOptions = null)
+	{
+		var options = ByRoleOptions.Default;
+		if (configureOptions is not null)
+		{
+			options = options with { };
+			configureOptions.Invoke(options);
+		}
+
+		return FindByRoleInternal(renderedComponent, role, options) ?? throw new RoleNotFoundException(role, options);
+	}
+
+	/// <summary>
+	/// Returns all elements with the specified ARIA role.
+	/// </summary>
+	/// <param name="renderedComponent">The rendered fragment to search.</param>
+	/// <param name="role">The ARIA role to search for.</param>
+	/// <param name="configureOptions">Method used to override the default behavior of FindAllByRole.</param>
+	/// <returns>A read-only collection of elements matching the role. Returns an empty collection if no matches are found.</returns>
+	public static IReadOnlyList<IElement> FindAllByRole(this IRenderedComponent<IComponent> renderedComponent, AriaRole role, Action<ByRoleOptions>? configureOptions = null)
+	{
+		var options = ByRoleOptions.Default;
+		if (configureOptions is not null)
+		{
+			options = options with { };
+			configureOptions.Invoke(options);
+		}
+
+		return FindAllByRoleInternal(renderedComponent, role, options);
+	}
+
+	internal static IElement? FindByRoleInternal(this IRenderedComponent<IComponent> renderedComponent, AriaRole role, ByRoleOptions options)
+	{
+		return FindAllByRoleInternal(renderedComponent, role, options).FirstOrDefault();
+	}
+
+	internal static IReadOnlyList<IElement> FindAllByRoleInternal(this IRenderedComponent<IComponent> renderedComponent, AriaRole role, ByRoleOptions options)
+	{
+		var allElements = renderedComponent.Nodes.TryQuerySelectorAll("*");
+		var results = new List<IElement>();
+
+		foreach (var element in allElements)
+		{
+			var effectiveRole = GetEffectiveRole(element);
+			if (effectiveRole != role)
+				continue;
+
+			if (!MatchesOptions(element, options, renderedComponent.Nodes))
+				continue;
+
+			results.Add(element.WrapUsing(new ByRoleElementFactory(renderedComponent, role, options)));
+		}
+
+		return results;
+	}
+
+	private static bool MatchesOptions(IElement element, ByRoleOptions options, INodeList rootNodes)
+	{
+		// Name filter
+		if (options.Name is not null)
+		{
+			var accessibleName = AccessibleNameCalculator.GetAccessibleName(element, rootNodes);
+			if (accessibleName is null)
+				return false;
+
+			if (options.Exact)
+			{
+				if (!accessibleName.Equals(options.Name, options.NameComparisonType))
+					return false;
+			}
+			else
+			{
+				if (!accessibleName.Contains(options.Name, options.NameComparisonType))
+					return false;
+			}
+		}
+
+		// Level filter
+		if (options.Level.HasValue)
+		{
+			var headingLevel = ImplicitRoleMapping.GetHeadingLevel(element);
+			if (headingLevel != options.Level.Value)
+				return false;
+		}
+
+		// Selected filter — absent treated as false
+		if (options.Selected.HasValue)
+		{
+			var isSelected = GetElementSelected(element) ?? false;
+			if (isSelected != options.Selected.Value)
+				return false;
+		}
+
+		// Checked filter — absent treated as false
+		if (options.Checked.HasValue)
+		{
+			var isChecked = GetElementChecked(element) ?? false;
+			if (isChecked != options.Checked.Value)
+				return false;
+		}
+
+		// Pressed filter — absent treated as false
+		if (options.Pressed.HasValue)
+		{
+			var isPressed = GetAriaTriStateBoolean(element, "aria-pressed") ?? false;
+			if (isPressed != options.Pressed.Value)
+				return false;
+		}
+
+		// Expanded filter — absent means no match (strict)
+		if (options.Expanded.HasValue)
+		{
+			var isExpanded = GetElementExpanded(element);
+			if (isExpanded is null || isExpanded != options.Expanded.Value)
+				return false;
+		}
+
+		// Disabled filter
+		if (options.Disabled.HasValue)
+		{
+			var isDisabled = IsElementDisabled(element);
+			if (isDisabled != options.Disabled.Value)
+				return false;
+		}
+
+		return true;
+	}
+
+	private static AriaRole? GetEffectiveRole(IElement element)
+	{
+		var explicitRole = element.GetAttribute("role");
+		if (!string.IsNullOrEmpty(explicitRole))
+		{
+			// role attribute can have space-separated values; take the first token
+			var firstToken = explicitRole.Split(' ', StringSplitOptions.RemoveEmptyEntries)[0].ToLowerInvariant();
+			return ParseRoleString(firstToken);
+		}
+
+		return ImplicitRoleMapping.GetImplicitRole(element);
+	}
+
+	private static AriaRole? ParseRoleString(string roleString) => roleString switch
+	{
+		"alert" => AriaRole.Alert,
+		"alertdialog" => AriaRole.AlertDialog,
+		"application" => AriaRole.Application,
+		"article" => AriaRole.Article,
+		"banner" => AriaRole.Banner,
+		"blockquote" => AriaRole.Blockquote,
+		"button" => AriaRole.Button,
+		"caption" => AriaRole.Caption,
+		"cell" => AriaRole.Cell,
+		"checkbox" => AriaRole.Checkbox,
+		"code" => AriaRole.Code,
+		"columnheader" => AriaRole.ColumnHeader,
+		"combobox" => AriaRole.Combobox,
+		"complementary" => AriaRole.Complementary,
+		"contentinfo" => AriaRole.ContentInfo,
+		"definition" => AriaRole.Definition,
+		"deletion" => AriaRole.Deletion,
+		"dialog" => AriaRole.Dialog,
+		"directory" => AriaRole.Directory,
+		"document" => AriaRole.Document,
+		"emphasis" => AriaRole.Emphasis,
+		"feed" => AriaRole.Feed,
+		"figure" => AriaRole.Figure,
+		"form" => AriaRole.Form,
+		"generic" => AriaRole.Generic,
+		"grid" => AriaRole.Grid,
+		"gridcell" => AriaRole.GridCell,
+		"group" => AriaRole.Group,
+		"heading" => AriaRole.Heading,
+		"img" => AriaRole.Img,
+		"insertion" => AriaRole.Insertion,
+		"link" => AriaRole.Link,
+		"list" => AriaRole.List,
+		"listbox" => AriaRole.Listbox,
+		"listitem" => AriaRole.Listitem,
+		"log" => AriaRole.Log,
+		"main" => AriaRole.Main,
+		"mark" => AriaRole.Mark,
+		"marquee" => AriaRole.Marquee,
+		"math" => AriaRole.Math,
+		"menu" => AriaRole.Menu,
+		"menubar" => AriaRole.Menubar,
+		"menuitem" => AriaRole.Menuitem,
+		"menuitemcheckbox" => AriaRole.Menuitemcheckbox,
+		"menuitemradio" => AriaRole.Menuitemradio,
+		"meter" => AriaRole.Meter,
+		"navigation" => AriaRole.Navigation,
+		"none" => AriaRole.None,
+		"note" => AriaRole.Note,
+		"option" => AriaRole.Option,
+		"paragraph" => AriaRole.Paragraph,
+		"presentation" => AriaRole.Presentation,
+		"progressbar" => AriaRole.Progressbar,
+		"radio" => AriaRole.Radio,
+		"radiogroup" => AriaRole.Radiogroup,
+		"region" => AriaRole.Region,
+		"row" => AriaRole.Row,
+		"rowgroup" => AriaRole.Rowgroup,
+		"rowheader" => AriaRole.Rowheader,
+		"scrollbar" => AriaRole.Scrollbar,
+		"search" => AriaRole.Search,
+		"searchbox" => AriaRole.Searchbox,
+		"separator" => AriaRole.Separator,
+		"slider" => AriaRole.Slider,
+		"spinbutton" => AriaRole.Spinbutton,
+		"status" => AriaRole.Status,
+		"strong" => AriaRole.Strong,
+		"subscript" => AriaRole.Subscript,
+		"superscript" => AriaRole.Superscript,
+		"switch" => AriaRole.Switch,
+		"tab" => AriaRole.Tab,
+		"table" => AriaRole.Table,
+		"tablist" => AriaRole.Tablist,
+		"tabpanel" => AriaRole.Tabpanel,
+		"term" => AriaRole.Term,
+		"textbox" => AriaRole.Textbox,
+		"time" => AriaRole.Time,
+		"timer" => AriaRole.Timer,
+		"toolbar" => AriaRole.Toolbar,
+		"tooltip" => AriaRole.Tooltip,
+		"tree" => AriaRole.Tree,
+		"treegrid" => AriaRole.Treegrid,
+		"treeitem" => AriaRole.Treeitem,
+		_ => null,
+	};
+
+	private static bool? GetElementSelected(IElement element)
+	{
+		var ariaSelected = element.GetAttribute("aria-selected");
+		if (ariaSelected is not null)
+			return string.Equals(ariaSelected, "true", StringComparison.OrdinalIgnoreCase);
+
+		// Native <option> selected attribute
+		if (element.NodeName == "OPTION")
+			return element.HasAttribute("selected");
+
+		return null;
+	}
+
+	private static bool? GetElementChecked(IElement element)
+	{
+		var ariaChecked = element.GetAttribute("aria-checked");
+		if (ariaChecked is not null)
+			return string.Equals(ariaChecked, "true", StringComparison.OrdinalIgnoreCase);
+
+		// Native checkbox/radio checked attribute
+		if (element.NodeName == "INPUT")
+			return element.HasAttribute("checked");
+
+		return null;
+	}
+
+	private static bool? GetAriaTriStateBoolean(IElement element, string attribute)
+	{
+		var value = element.GetAttribute(attribute);
+		if (value is null)
+			return null;
+		return string.Equals(value, "true", StringComparison.OrdinalIgnoreCase);
+	}
+
+	private static bool? GetElementExpanded(IElement element)
+	{
+		var ariaExpanded = element.GetAttribute("aria-expanded");
+		if (ariaExpanded is not null)
+			return string.Equals(ariaExpanded, "true", StringComparison.OrdinalIgnoreCase);
+
+		// Native <details> open attribute
+		if (element.NodeName == "DETAILS")
+			return element.HasAttribute("open");
+
+		return null;
+	}
+
+	private static bool IsElementDisabled(IElement element)
+	{
+		var ariaDisabled = element.GetAttribute("aria-disabled");
+		if (ariaDisabled is not null)
+			return string.Equals(ariaDisabled, "true", StringComparison.OrdinalIgnoreCase);
+
+		// Native disabled attribute
+		if (element.HasAttribute("disabled"))
+			return true;
+
+		// Fieldset disabled inheritance
+		if (IsDisabledByFieldset(element))
+			return true;
+
+		// Disabled optgroup inheritance
+		if (element.NodeName == "OPTION" && element.ParentElement is { NodeName: "OPTGROUP" } optgroup && optgroup.HasAttribute("disabled"))
+			return true;
+
+		return false;
+	}
+
+	private static bool IsDisabledByFieldset(IElement element)
+	{
+		var parent = element.ParentElement;
+		while (parent is not null)
+		{
+			if (parent.NodeName == "FIELDSET" && parent.HasAttribute("disabled"))
+			{
+				// Exception: elements in the first <legend> of a disabled fieldset are NOT disabled
+				if (!IsInFirstLegend(element, parent))
+					return true;
+			}
+
+			parent = parent.ParentElement;
+		}
+
+		return false;
+	}
+
+	private static bool IsInFirstLegend(IElement element, IElement fieldset)
+	{
+		var firstLegend = fieldset.Children.FirstOrDefault(c => c.NodeName == "LEGEND");
+		if (firstLegend is null)
+			return false;
+
+		// Check if element is a descendant of the first legend
+		var current = element.ParentElement;
+		while (current is not null && current != fieldset)
+		{
+			if (current == firstLegend)
+				return true;
+			current = current.ParentElement;
+		}
+
+		return false;
+	}
+}
diff --git a/tests/bunit.testassets/BlazorE2E/RoleQueryCounter.razor b/tests/bunit.testassets/BlazorE2E/RoleQueryCounter.razor
new file mode 100644
index 000000000..849b7d890
--- /dev/null
+++ b/tests/bunit.testassets/BlazorE2E/RoleQueryCounter.razor
@@ -0,0 +1,9 @@
+@* Testing we get back the re-rendered element for role-based queries *@
+<h2>Re-rendered heading</h2>
+<input type="text" value="@_count" aria-label="Re-rendered input" />
+<button id="increment-button" @onclick="IncrementCount">Click</button>
+
+@code {
+	private int _count;
+	public void IncrementCount() => _count++;
+}
diff --git a/tests/bunit.web.query.tests/Roles/RoleQueryExtensionsTest.cs b/tests/bunit.web.query.tests/Roles/RoleQueryExtensionsTest.cs
new file mode 100644
index 000000000..504843e19
--- /dev/null
+++ b/tests/bunit.web.query.tests/Roles/RoleQueryExtensionsTest.cs
@@ -0,0 +1,405 @@
+using Bunit.TestAssets.BlazorE2E;
+
+namespace Bunit.Roles;
+
+public class RoleQueryExtensionsTest : BunitContext
+{
+	[Fact(DisplayName = "should detect roles")]
+	public void Should_detect_roles()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<button>Hello</button>
+				<select multiple="" size="2"></select>
+				<select></select>
+				<h3>Heading</h3>
+				<details><summary>Hello</summary></details>
+				<div role="dialog">I am a dialog</div>
+				"""));
+
+		var buttons = cut.FindAllByRole(AriaRole.Button);
+		buttons.Count.ShouldBe(1);
+		buttons[0].OuterHtml.ShouldBe("<button>Hello</button>");
+
+		var listboxes = cut.FindAllByRole(AriaRole.Listbox);
+		listboxes.Count.ShouldBe(1);
+		listboxes[0].NodeName.ShouldBe("SELECT");
+
+		var comboboxes = cut.FindAllByRole(AriaRole.Combobox);
+		comboboxes.Count.ShouldBe(1);
+		comboboxes[0].NodeName.ShouldBe("SELECT");
+
+		var headings = cut.FindAllByRole(AriaRole.Heading);
+		headings.Count.ShouldBe(1);
+		headings[0].OuterHtml.ShouldBe("<h3>Heading</h3>");
+
+		var groups = cut.FindAllByRole(AriaRole.Group);
+		groups.Count.ShouldBe(1);
+		groups[0].NodeName.ShouldBe("DETAILS");
+
+		var dialogs = cut.FindAllByRole(AriaRole.Dialog);
+		dialogs.Count.ShouldBe(1);
+		dialogs[0].OuterHtml.ShouldBe("""<div role="dialog">I am a dialog</div>""");
+
+		var menuitems = cut.FindAllByRole(AriaRole.Menuitem);
+		menuitems.Count.ShouldBe(0);
+	}
+
+	[Fact(DisplayName = "should support explicit role overriding implicit")]
+	public void Should_support_explicit_role_overriding_implicit()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<div role="button">Click</div>
+				<button role="tab">Tab</button>
+				"""));
+
+		var buttons = cut.FindAllByRole(AriaRole.Button);
+		buttons.Count.ShouldBe(1);
+		buttons[0].OuterHtml.ShouldBe("""<div role="button">Click</div>""");
+
+		var tabs = cut.FindAllByRole(AriaRole.Tab);
+		tabs.Count.ShouldBe(1);
+		tabs[0].OuterHtml.ShouldBe("""<button role="tab">Tab</button>""");
+	}
+
+	[Fact(DisplayName = "should throw when no match")]
+	public void Should_throw_when_no_match()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""<div>No roles here</div>"""));
+
+		var exception = Should.Throw<RoleNotFoundException>(() => cut.FindByRole(AriaRole.Button));
+		exception.Role.ShouldBe(AriaRole.Button);
+		exception.Message.ShouldContain("button");
+	}
+
+	[Fact(DisplayName = "should return empty collection when no match")]
+	public void Should_return_empty_collection_when_no_match()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""<div>No roles here</div>"""));
+
+		var elements = cut.FindAllByRole(AriaRole.Button);
+		elements.ShouldBeEmpty();
+	}
+
+	[Fact(DisplayName = "should support name")]
+	public void Should_support_name()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<div role="button" aria-label=" Hello "></div>
+				<div role="button" aria-label="Hallo"></div>
+				"""));
+
+		// Exact name match with whitespace trimming — Playwright trims accessible names
+		var helloButtons = cut.FindAllByRole(AriaRole.Button, o => o.Name = "Hello");
+		helloButtons.Count.ShouldBe(1);
+		helloButtons[0].GetAttribute("aria-label").ShouldBe(" Hello ");
+
+		// Case-insensitive name match
+		var caseInsensitive = cut.FindAllByRole(AriaRole.Button, o =>
+		{
+			o.Name = "hello";
+			o.NameComparisonType = StringComparison.OrdinalIgnoreCase;
+		});
+		caseInsensitive.Count.ShouldBe(1);
+		caseInsensitive[0].GetAttribute("aria-label").ShouldBe(" Hello ");
+
+		// Substring match with Exact=false
+		var substringMatch = cut.FindAllByRole(AriaRole.Button, o =>
+		{
+			o.Name = "all";
+			o.Exact = false;
+		});
+		substringMatch.Count.ShouldBe(1);
+		substringMatch[0].GetAttribute("aria-label").ShouldBe("Hallo");
+
+		// All buttons returned without name filter
+		var allButtons = cut.FindAllByRole(AriaRole.Button);
+		allButtons.Count.ShouldBe(2);
+	}
+
+	[Fact(DisplayName = "should support output accessible name")]
+	public void Should_support_output_accessible_name()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""<label>Output1<output>output</output></label>"""));
+
+		var result = cut.FindByRole(AriaRole.Status, o => o.Name = "Output1");
+		result.NodeName.ShouldBe("OUTPUT");
+	}
+
+	[Fact(DisplayName = "should support native controls name")]
+	public void Should_support_native_controls_name()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<label for="text1">TEXT1</label><input id="text1" type="text" />
+				<input id="text2" type="text" title="TEXT2" />
+				<input id="text3" type="text" placeholder="TEXT3" />
+
+				<button id="button3">BUTTON3</button>
+				<button id="button4" title="BUTTON4"></button>
+
+				<input id="image2" type="image" alt="IMAGE2" />
+				"""));
+
+		cut.FindByRole(AriaRole.Textbox, o => o.Name = "TEXT1").Id.ShouldBe("text1");
+		cut.FindByRole(AriaRole.Textbox, o => o.Name = "TEXT2").Id.ShouldBe("text2");
+		cut.FindByRole(AriaRole.Textbox, o => o.Name = "TEXT3").Id.ShouldBe("text3");
+		cut.FindByRole(AriaRole.Button, o => o.Name = "BUTTON3").Id.ShouldBe("button3");
+		cut.FindByRole(AriaRole.Button, o => o.Name = "BUTTON4").Id.ShouldBe("button4");
+		cut.FindByRole(AriaRole.Button, o => o.Name = "IMAGE2").Id.ShouldBe("image2");
+	}
+
+	[Fact(DisplayName = "should support native controls labelled-by")]
+	public void Should_support_native_controls_labelled_by()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<label id="for-text1">TEXT1</label><input aria-labelledby="for-text1" id="text1" type="text" />
+				<label id="for-button1">BUTTON1</label><button aria-labelledby="for-button1" id="button1">MORE1</button>
+				<label id="for-button2">BUTTON2</label><button aria-labelledby="for-button2 button2" id="button2">MORE2</button>
+				"""));
+
+		cut.FindByRole(AriaRole.Textbox, o => o.Name = "TEXT1").Id.ShouldBe("text1");
+		cut.FindByRole(AriaRole.Button, o => o.Name = "BUTTON1").Id.ShouldBe("button1");
+		cut.FindByRole(AriaRole.Button, o => o.Name = "BUTTON2 MORE2").Id.ShouldBe("button2");
+	}
+
+	[Fact(DisplayName = "should support level")]
+	public void Should_support_level()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<h1>Hello</h1>
+				<h3>Hi</h3>
+				<div role="heading" aria-level="5">Bye</div>
+				"""));
+
+		var level1 = cut.FindAllByRole(AriaRole.Heading, o => o.Level = 1);
+		level1.Count.ShouldBe(1);
+		level1[0].OuterHtml.ShouldBe("<h1>Hello</h1>");
+
+		var level3 = cut.FindAllByRole(AriaRole.Heading, o => o.Level = 3);
+		level3.Count.ShouldBe(1);
+		level3[0].OuterHtml.ShouldBe("<h3>Hi</h3>");
+
+		var level5 = cut.FindAllByRole(AriaRole.Heading, o => o.Level = 5);
+		level5.Count.ShouldBe(1);
+		level5[0].OuterHtml.ShouldBe("""<div role="heading" aria-level="5">Bye</div>""");
+	}
+
+	[Fact(DisplayName = "should support selected")]
+	public void Should_support_selected()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<select>
+					<option>Hi</option>
+					<option selected>Hello</option>
+				</select>
+				<div>
+					<div role="option" aria-selected="true">Hi</div>
+					<div role="option" aria-selected="false">Hello</div>
+				</div>
+				"""));
+
+		var selectedTrue = cut.FindAllByRole(AriaRole.Option, o => o.Selected = true);
+		selectedTrue.Count.ShouldBe(2);
+		selectedTrue[0].TextContent.ShouldBe("Hello");
+		selectedTrue[1].TextContent.ShouldBe("Hi");
+
+		var selectedFalse = cut.FindAllByRole(AriaRole.Option, o => o.Selected = false);
+		selectedFalse.Count.ShouldBe(2);
+		selectedFalse[0].TextContent.ShouldBe("Hi");
+		selectedFalse[1].TextContent.ShouldBe("Hello");
+	}
+
+	[Fact(DisplayName = "should support checked")]
+	public void Should_support_checked()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<input type="checkbox" />
+				<input type="checkbox" checked />
+				<div role="checkbox" aria-checked="true">Hi</div>
+				<div role="checkbox" aria-checked="false">Hello</div>
+				<div role="checkbox">Unknown</div>
+				"""));
+
+		var checkedTrue = cut.FindAllByRole(AriaRole.Checkbox, o => o.Checked = true);
+		checkedTrue.Count.ShouldBe(2);
+
+		var checkedFalse = cut.FindAllByRole(AriaRole.Checkbox, o => o.Checked = false);
+		checkedFalse.Count.ShouldBe(3);
+
+		var all = cut.FindAllByRole(AriaRole.Checkbox);
+		all.Count.ShouldBe(5);
+	}
+
+	[Fact(DisplayName = "should support pressed")]
+	public void Should_support_pressed()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<button>Hi</button>
+				<button aria-pressed="true">Hello</button>
+				<button aria-pressed="false">Bye</button>
+				<button aria-pressed="mixed">Mixed</button>
+				"""));
+
+		var pressedTrue = cut.FindAllByRole(AriaRole.Button, o => o.Pressed = true);
+		pressedTrue.Count.ShouldBe(1);
+		pressedTrue[0].TextContent.ShouldBe("Hello");
+
+		var pressedFalse = cut.FindAllByRole(AriaRole.Button, o => o.Pressed = false);
+		pressedFalse.Count.ShouldBe(3);
+
+		var allButtons = cut.FindAllByRole(AriaRole.Button);
+		allButtons.Count.ShouldBe(4);
+	}
+
+	[Fact(DisplayName = "should support expanded")]
+	public void Should_support_expanded()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<div role="treeitem">Hi</div>
+				<div role="treeitem" aria-expanded="true">Hello</div>
+				<div role="treeitem" aria-expanded="false">Bye</div>
+				"""));
+
+		var all = cut.FindAllByRole(AriaRole.Treeitem);
+		all.Count.ShouldBe(3);
+
+		var expandedTrue = cut.FindAllByRole(AriaRole.Treeitem, o => o.Expanded = true);
+		expandedTrue.Count.ShouldBe(1);
+		expandedTrue[0].TextContent.ShouldBe("Hello");
+
+		var expandedFalse = cut.FindAllByRole(AriaRole.Treeitem, o => o.Expanded = false);
+		expandedFalse.Count.ShouldBe(1);
+		expandedFalse[0].TextContent.ShouldBe("Bye");
+	}
+
+	[Fact(DisplayName = "should support disabled")]
+	public void Should_support_disabled()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<button>Hi</button>
+				<button disabled>Bye</button>
+				<button aria-disabled="true">Hello</button>
+				<button aria-disabled="false">Oh</button>
+				<fieldset disabled>
+					<button>Yay</button>
+				</fieldset>
+				<select>
+					<optgroup disabled>
+						<option>one</option>
+					</optgroup>
+					<optgroup>
+						<option>two</option>
+					</optgroup>
+					<option disabled>three</option>
+				</select>
+				"""));
+
+		var disabledButtons = cut.FindAllByRole(AriaRole.Button, o => o.Disabled = true);
+		disabledButtons.Count.ShouldBe(3);
+		disabledButtons[0].TextContent.ShouldBe("Bye");
+		disabledButtons[1].TextContent.ShouldBe("Hello");
+		disabledButtons[2].TextContent.ShouldBe("Yay");
+
+		var enabledButtons = cut.FindAllByRole(AriaRole.Button, o => o.Disabled = false);
+		enabledButtons.Count.ShouldBe(2);
+		enabledButtons[0].TextContent.ShouldBe("Hi");
+		enabledButtons[1].TextContent.ShouldBe("Oh");
+
+		var disabledOptions = cut.FindAllByRole(AriaRole.Option, o => o.Disabled = true);
+		disabledOptions.Count.ShouldBe(2);
+		disabledOptions[0].TextContent.ShouldBe("one");
+		disabledOptions[1].TextContent.ShouldBe("three");
+
+		var enabledOptions = cut.FindAllByRole(AriaRole.Option, o => o.Disabled = false);
+		enabledOptions.Count.ShouldBe(1);
+		enabledOptions[0].TextContent.ShouldBe("two");
+	}
+
+	[Fact(DisplayName = "should support disabled fieldset")]
+	public void Should_support_disabled_fieldset()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<fieldset disabled>
+					<input />
+					<button data-testid="inside-fieldset-element">x</button>
+					<legend>
+						<button data-testid="inside-legend-element">legend</button>
+					</legend>
+				</fieldset>
+
+				<fieldset disabled>
+					<legend>
+						<div>
+							<button data-testid="nested-inside-legend-element">x</button>
+						</div>
+					</legend>
+				</fieldset>
+
+				<fieldset disabled>
+					<div></div>
+					<legend>
+						<button data-testid="first-legend-element">x</button>
+					</legend>
+					<legend>
+						<button data-testid="second-legend-element">x</button>
+					</legend>
+				</fieldset>
+
+				<fieldset disabled>
+					<fieldset>
+						<button data-testid="deep-button">x</button>
+					</fieldset>
+				</fieldset>
+				"""));
+
+		// Button inside legend of disabled fieldset should be enabled
+		cut.FindAllByRole(AriaRole.Button, o => o.Disabled = false)
+			.ShouldContain(b => b.GetAttribute("data-testid") == "inside-legend-element");
+
+		// Button nested inside legend should also be enabled
+		cut.FindAllByRole(AriaRole.Button, o => o.Disabled = false)
+			.ShouldContain(b => b.GetAttribute("data-testid") == "nested-inside-legend-element");
+
+		// First legend — button should be enabled
+		cut.FindAllByRole(AriaRole.Button, o => o.Disabled = false)
+			.ShouldContain(b => b.GetAttribute("data-testid") == "first-legend-element");
+
+		// Second legend — button should be disabled
+		cut.FindAllByRole(AriaRole.Button, o => o.Disabled = true)
+			.ShouldContain(b => b.GetAttribute("data-testid") == "second-legend-element");
+
+		// Deeply nested fieldset — button should be disabled
+		cut.FindAllByRole(AriaRole.Button, o => o.Disabled = true)
+			.ShouldContain(b => b.GetAttribute("data-testid") == "deep-button");
+
+		// Button inside fieldset (not in legend) should be disabled
+		cut.FindAllByRole(AriaRole.Button, o => o.Disabled = true)
+			.ShouldContain(b => b.GetAttribute("data-testid") == "inside-fieldset-element");
+	}
+
+	[Fact(DisplayName = "should reflect latest value when element rerenders")]
+	public void Should_reflect_latest_value_when_element_rerenders()
+	{
+		var cut = Render<RoleQueryCounter>();
+
+		var input = cut.FindByRole(AriaRole.Textbox, o => o.Name = "Re-rendered input");
+		input.GetAttribute("value").ShouldBe("0");
+
+		cut.Find("#increment-button").Click();
+		input.GetAttribute("value").ShouldBe("1");
+	}
+}

From 97d0d7b1a2a8f4505f06f840372421f9f65f56bf Mon Sep 17 00:00:00 2001
From: Scott Sauber <stsauber@gmail.com>
Date: Tue, 24 Mar 2026 15:45:53 -0700
Subject: [PATCH 2/3] docs: add docs for findbyrole

---
 CHANGELOG.md                                 | 4 ++++
 docs/site/docs/verification/verify-markup.md | 5 +++--
 src/bunit.web.query/bunit.web.query.csproj   | 2 +-
 3 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6aad902f8..af4a9acdf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,10 @@ All notable changes to **bUnit** will be documented in this file. The project ad
 
 ## [Unreleased]
 
+### Added
+
+- `FindByRole` and `FindAllByRole` to `bunit.web.query` to find elements by their WAI-ARIA role, mirroring Playwright's `GetByRole` API. Supports implicit roles from semantic HTML (e.g. `<button>` → button, `<a href>` → link, `<h1>` → heading), explicit `role` attributes, and filtering by accessible name, level, checked, pressed, selected, expanded, and disabled states.
+
 ## [2.6.2] - 2026-02-27
 
 ### Added
diff --git a/docs/site/docs/verification/verify-markup.md b/docs/site/docs/verification/verify-markup.md
index 5628fa2b3..67ced1a1f 100644
--- a/docs/site/docs/verification/verify-markup.md
+++ b/docs/site/docs/verification/verify-markup.md
@@ -9,7 +9,7 @@ Generally, the strategy for verifying markup produced by components depends on w
 
 With a **reusable component library**, the markup produced may be considered part of the externally observable behavior of the component, and that should thus be verified, since users of the component may depend on the markup having a specific structure. Consider using `MarkupMatches` and semantic comparison described below to get the best protection against regressions and good maintainability.
 
-When **building components for a Blazor app**, the externally observable behavior of components are how they visibly look and behave from an end-users point of view, e.g. what the user sees and interact with in a browser. In this scenario, consider use `FindByLabelText` and related methods described below to inspect and assert against individual elements look and feel, for a good balance between protection against regressions and maintainability. Learn more about this testing approach at https://testing-library.com.
+When **building components for a Blazor app**, the externally observable behavior of components are how they visibly look and behave from an end-users point of view, e.g. what the user sees and interact with in a browser. In this scenario, consider using `FindByRole`, `FindByLabelText`, and related methods described below to inspect and assert against individual elements look and feel, for a good balance between protection against regressions and maintainability. Learn more about this testing approach at https://testing-library.com.
 
 This page covers the following **verification approaches:**
 
@@ -35,7 +35,8 @@ The rendered markup from a component is available as a DOM node through the <xre
 
 bUnit supports multiple different ways of searching and querying the rendered HTML elements:
 
-- `FindByLabelText(string labelText)` that takes a text string used to label an input element and returns an `IElement` as output, or throws an exception if none are found (this is included in the experimental library [bunit.web.query](https://www.nuget.org/packages/bunit.web.query)). Use this method when possible compared to the generic `Find` and `FindAll` methods.
+- `FindByRole(AriaRole role)` that finds elements by their WAI-ARIA role, either implicit (e.g. `<button>` has role "button") or explicit (via the `role` attribute). Supports filtering by accessible name, heading level, and states like checked, pressed, selected, expanded, and disabled. Throws an exception if none are found. `FindAllByRole` returns all matches. This is the recommended query method for accessing non-form fields, following the [testing-library.com](https://testing-library.com/docs/queries/byrole/) approach. (Included in the library [bunit.web.query](https://www.nuget.org/packages/bunit.web.query).)
+- `FindByLabelText(string labelText)` that takes a text string to retrieve an element by its label and returns an `IElement` as output, or throws an exception if none are found which is an accessibility violation (this is included in the library [bunit.web.query](https://www.nuget.org/packages/bunit.web.query)). This is recommended for accessing form elements.
 - [`Find(string cssSelector)`](xref:Bunit.RenderedComponentExtensions.Find``1(Bunit.IRenderedComponent{``0},System.String)) takes a "CSS selector" as input and returns an `IElement` as output, or throws an exception if none are found.
 - [`FindAll(string cssSelector)`](xref:Bunit.RenderedComponentExtensions.FindAll``1(Bunit.IRenderedComponent{``0},System.String)) takes a "CSS selector" as input and returns a list of `IElement` elements.
 
diff --git a/src/bunit.web.query/bunit.web.query.csproj b/src/bunit.web.query/bunit.web.query.csproj
index c0e9bc642..7188d15c8 100644
--- a/src/bunit.web.query/bunit.web.query.csproj
+++ b/src/bunit.web.query/bunit.web.query.csproj
@@ -10,7 +10,7 @@
 		<PackageId>bunit.web.query</PackageId>
 		<Title>bunit.web.query</Title>
 		<Description>
-			bunit.web.query is an experimental package that provides an bUnit version of the https://testing-library.com/ APIs.
+			bunit.web.query is a package that provides an bUnit version of the https://testing-library.com/ APIs.
 		</Description>
 	</PropertyGroup>
 

From c18d267f27b1a270300adce44bf1d5b99762daea Mon Sep 17 00:00:00 2001
From: Scott Sauber <stsauber@gmail.com>
Date: Tue, 24 Mar 2026 16:14:55 -0700
Subject: [PATCH 3/3] fix: fix build

---
 CHANGELOG.md                                  |   2 +-
 src/bunit.web.query/Roles/AriaRole.cs         | 166 ++++++++++-
 .../Roles/ImplicitRoleMapping.cs              |   2 +-
 .../Roles/RoleNotFoundException.cs            |  10 +-
 .../Roles/RoleQueryExtensions.cs              | 183 +++++++------
 .../Roles/RoleQueryExtensionsTest.cs          | 258 ++++++++++++++++++
 6 files changed, 522 insertions(+), 99 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index af4a9acdf..0f4d2ed8e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,7 @@ All notable changes to **bUnit** will be documented in this file. The project ad
 
 ### Added
 
-- `FindByRole` and `FindAllByRole` to `bunit.web.query` to find elements by their WAI-ARIA role, mirroring Playwright's `GetByRole` API. Supports implicit roles from semantic HTML (e.g. `<button>` → button, `<a href>` → link, `<h1>` → heading), explicit `role` attributes, and filtering by accessible name, level, checked, pressed, selected, expanded, and disabled states.
+- `FindByRole` and `FindAllByRole` to `bunit.web.query` to find elements by their WAI-ARIA role, mirroring Playwright's `GetByRole` API. Supports implicit roles from semantic HTML (e.g. button, anchor with href, heading elements), explicit `role` attributes, and filtering by accessible name, level, checked, pressed, selected, expanded, and disabled states.
 
 ## [2.6.2] - 2026-02-27
 
diff --git a/src/bunit.web.query/Roles/AriaRole.cs b/src/bunit.web.query/Roles/AriaRole.cs
index a854f923a..834a9e353 100644
--- a/src/bunit.web.query/Roles/AriaRole.cs
+++ b/src/bunit.web.query/Roles/AriaRole.cs
@@ -2,92 +2,256 @@ namespace Bunit;
 
 /// <summary>
 /// Represents WAI-ARIA roles used to identify the type of an element.
-/// Mirrors Playwright.NET's AriaRole enum for familiarity.
 /// </summary>
 public enum AriaRole
 {
+	/// <summary>Represents the WAI-ARIA "alert" role.</summary>
 	Alert,
+
+	/// <summary>Represents the WAI-ARIA "alertdialog" role.</summary>
 	AlertDialog,
+
+	/// <summary>Represents the WAI-ARIA "application" role.</summary>
 	Application,
+
+	/// <summary>Represents the WAI-ARIA "article" role.</summary>
 	Article,
+
+	/// <summary>Represents the WAI-ARIA "banner" role.</summary>
 	Banner,
+
+	/// <summary>Represents the WAI-ARIA "blockquote" role.</summary>
 	Blockquote,
+
+	/// <summary>Represents the WAI-ARIA "button" role.</summary>
 	Button,
+
+	/// <summary>Represents the WAI-ARIA "caption" role.</summary>
 	Caption,
+
+	/// <summary>Represents the WAI-ARIA "cell" role.</summary>
 	Cell,
+
+	/// <summary>Represents the WAI-ARIA "checkbox" role.</summary>
 	Checkbox,
+
+	/// <summary>Represents the WAI-ARIA "code" role.</summary>
 	Code,
+
+	/// <summary>Represents the WAI-ARIA "columnheader" role.</summary>
 	ColumnHeader,
+
+	/// <summary>Represents the WAI-ARIA "combobox" role.</summary>
 	Combobox,
+
+	/// <summary>Represents the WAI-ARIA "complementary" role.</summary>
 	Complementary,
+
+	/// <summary>Represents the WAI-ARIA "contentinfo" role.</summary>
 	ContentInfo,
+
+	/// <summary>Represents the WAI-ARIA "definition" role.</summary>
 	Definition,
+
+	/// <summary>Represents the WAI-ARIA "deletion" role.</summary>
 	Deletion,
+
+	/// <summary>Represents the WAI-ARIA "dialog" role.</summary>
 	Dialog,
+
+	/// <summary>Represents the WAI-ARIA "directory" role.</summary>
 	Directory,
+
+	/// <summary>Represents the WAI-ARIA "document" role.</summary>
 	Document,
+
+	/// <summary>Represents the WAI-ARIA "emphasis" role.</summary>
 	Emphasis,
+
+	/// <summary>Represents the WAI-ARIA "feed" role.</summary>
 	Feed,
+
+	/// <summary>Represents the WAI-ARIA "figure" role.</summary>
 	Figure,
+
+	/// <summary>Represents the WAI-ARIA "form" role.</summary>
 	Form,
+
+	/// <summary>Represents the WAI-ARIA "generic" role.</summary>
 	Generic,
+
+	/// <summary>Represents the WAI-ARIA "grid" role.</summary>
 	Grid,
+
+	/// <summary>Represents the WAI-ARIA "gridcell" role.</summary>
 	GridCell,
+
+	/// <summary>Represents the WAI-ARIA "group" role.</summary>
 	Group,
+
+	/// <summary>Represents the WAI-ARIA "heading" role.</summary>
 	Heading,
+
+	/// <summary>Represents the WAI-ARIA "img" role.</summary>
 	Img,
+
+	/// <summary>Represents the WAI-ARIA "insertion" role.</summary>
 	Insertion,
+
+	/// <summary>Represents the WAI-ARIA "link" role.</summary>
 	Link,
+
+	/// <summary>Represents the WAI-ARIA "list" role.</summary>
 	List,
+
+	/// <summary>Represents the WAI-ARIA "listbox" role.</summary>
 	Listbox,
+
+	/// <summary>Represents the WAI-ARIA "listitem" role.</summary>
 	Listitem,
+
+	/// <summary>Represents the WAI-ARIA "log" role.</summary>
 	Log,
+
+	/// <summary>Represents the WAI-ARIA "main" role.</summary>
 	Main,
+
+	/// <summary>Represents the WAI-ARIA "mark" role.</summary>
 	Mark,
+
+	/// <summary>Represents the WAI-ARIA "marquee" role.</summary>
 	Marquee,
+
+	/// <summary>Represents the WAI-ARIA "math" role.</summary>
 	Math,
+
+	/// <summary>Represents the WAI-ARIA "menu" role.</summary>
 	Menu,
+
+	/// <summary>Represents the WAI-ARIA "menubar" role.</summary>
 	Menubar,
+
+	/// <summary>Represents the WAI-ARIA "menuitem" role.</summary>
 	Menuitem,
+
+	/// <summary>Represents the WAI-ARIA "menuitemcheckbox" role.</summary>
 	Menuitemcheckbox,
+
+	/// <summary>Represents the WAI-ARIA "menuitemradio" role.</summary>
 	Menuitemradio,
+
+	/// <summary>Represents the WAI-ARIA "meter" role.</summary>
 	Meter,
+
+	/// <summary>Represents the WAI-ARIA "navigation" role.</summary>
 	Navigation,
+
+	/// <summary>Represents the WAI-ARIA "none" role.</summary>
 	None,
+
+	/// <summary>Represents the WAI-ARIA "note" role.</summary>
 	Note,
+
+	/// <summary>Represents the WAI-ARIA "option" role.</summary>
 	Option,
+
+	/// <summary>Represents the WAI-ARIA "paragraph" role.</summary>
 	Paragraph,
+
+	/// <summary>Represents the WAI-ARIA "presentation" role.</summary>
 	Presentation,
+
+	/// <summary>Represents the WAI-ARIA "progressbar" role.</summary>
 	Progressbar,
+
+	/// <summary>Represents the WAI-ARIA "radio" role.</summary>
 	Radio,
+
+	/// <summary>Represents the WAI-ARIA "radiogroup" role.</summary>
 	Radiogroup,
+
+	/// <summary>Represents the WAI-ARIA "region" role.</summary>
 	Region,
+
+	/// <summary>Represents the WAI-ARIA "row" role.</summary>
 	Row,
+
+	/// <summary>Represents the WAI-ARIA "rowgroup" role.</summary>
 	Rowgroup,
+
+	/// <summary>Represents the WAI-ARIA "rowheader" role.</summary>
 	Rowheader,
+
+	/// <summary>Represents the WAI-ARIA "scrollbar" role.</summary>
 	Scrollbar,
+
+	/// <summary>Represents the WAI-ARIA "search" role.</summary>
 	Search,
+
+	/// <summary>Represents the WAI-ARIA "searchbox" role.</summary>
 	Searchbox,
+
+	/// <summary>Represents the WAI-ARIA "separator" role.</summary>
 	Separator,
+
+	/// <summary>Represents the WAI-ARIA "slider" role.</summary>
 	Slider,
+
+	/// <summary>Represents the WAI-ARIA "spinbutton" role.</summary>
 	Spinbutton,
+
+	/// <summary>Represents the WAI-ARIA "status" role.</summary>
 	Status,
+
+	/// <summary>Represents the WAI-ARIA "strong" role.</summary>
 	Strong,
+
+	/// <summary>Represents the WAI-ARIA "subscript" role.</summary>
 	Subscript,
+
+	/// <summary>Represents the WAI-ARIA "superscript" role.</summary>
 	Superscript,
+
+	/// <summary>Represents the WAI-ARIA "switch" role.</summary>
 	Switch,
+
+	/// <summary>Represents the WAI-ARIA "tab" role.</summary>
 	Tab,
+
+	/// <summary>Represents the WAI-ARIA "table" role.</summary>
 	Table,
+
+	/// <summary>Represents the WAI-ARIA "tablist" role.</summary>
 	Tablist,
+
+	/// <summary>Represents the WAI-ARIA "tabpanel" role.</summary>
 	Tabpanel,
+
+	/// <summary>Represents the WAI-ARIA "term" role.</summary>
 	Term,
+
+	/// <summary>Represents the WAI-ARIA "textbox" role.</summary>
 	Textbox,
+
+	/// <summary>Represents the WAI-ARIA "time" role.</summary>
 	Time,
+
+	/// <summary>Represents the WAI-ARIA "timer" role.</summary>
 	Timer,
+
+	/// <summary>Represents the WAI-ARIA "toolbar" role.</summary>
 	Toolbar,
+
+	/// <summary>Represents the WAI-ARIA "tooltip" role.</summary>
 	Tooltip,
+
+	/// <summary>Represents the WAI-ARIA "tree" role.</summary>
 	Tree,
+
+	/// <summary>Represents the WAI-ARIA "treegrid" role.</summary>
 	Treegrid,
+
+	/// <summary>Represents the WAI-ARIA "treeitem" role.</summary>
 	Treeitem,
 }
 
diff --git a/src/bunit.web.query/Roles/ImplicitRoleMapping.cs b/src/bunit.web.query/Roles/ImplicitRoleMapping.cs
index 79ffccfc5..f90e00cfe 100644
--- a/src/bunit.web.query/Roles/ImplicitRoleMapping.cs
+++ b/src/bunit.web.query/Roles/ImplicitRoleMapping.cs
@@ -84,7 +84,7 @@ internal static class ImplicitRoleMapping
 	private static AriaRole? GetImgRole(IElement element)
 	{
 		var alt = element.GetAttribute("alt");
-		return alt == string.Empty ? AriaRole.Presentation : AriaRole.Img;
+		return alt is not null && alt.Length == 0 ? AriaRole.Presentation : AriaRole.Img;
 	}
 
 	private static bool HasAccessibleName(IElement element)
diff --git a/src/bunit.web.query/Roles/RoleNotFoundException.cs b/src/bunit.web.query/Roles/RoleNotFoundException.cs
index ae92c1bd6..6a4abe8f5 100644
--- a/src/bunit.web.query/Roles/RoleNotFoundException.cs
+++ b/src/bunit.web.query/Roles/RoleNotFoundException.cs
@@ -35,15 +35,15 @@ private static string BuildMessage(AriaRole role, ByRoleOptions options)
 		if (options.Level.HasValue)
 			filters.Add($"level: {options.Level.Value}");
 		if (options.Checked.HasValue)
-			filters.Add($"checked: {(options.Checked.Value == true ? "true" : "false")}");
+			filters.Add($"checked: {(options.Checked.Value ? "true" : "false")}");
 		if (options.Pressed.HasValue)
-			filters.Add($"pressed: {(options.Pressed.Value == true ? "true" : "false")}");
+			filters.Add($"pressed: {(options.Pressed.Value ? "true" : "false")}");
 		if (options.Selected.HasValue)
-			filters.Add($"selected: {(options.Selected.Value == true ? "true" : "false")}");
+			filters.Add($"selected: {(options.Selected.Value ? "true" : "false")}");
 		if (options.Expanded.HasValue)
-			filters.Add($"expanded: {(options.Expanded.Value == true ? "true" : "false")}");
+			filters.Add($"expanded: {(options.Expanded.Value ? "true" : "false")}");
 		if (options.Disabled.HasValue)
-			filters.Add($"disabled: {(options.Disabled.Value == true ? "true" : "false")}");
+			filters.Add($"disabled: {(options.Disabled.Value ? "true" : "false")}");
 
 		if (filters.Count > 0)
 			message += $" ({string.Join(", ", filters)})";
diff --git a/src/bunit.web.query/Roles/RoleQueryExtensions.cs b/src/bunit.web.query/Roles/RoleQueryExtensions.cs
index a26d6ded6..8da434518 100644
--- a/src/bunit.web.query/Roles/RoleQueryExtensions.cs
+++ b/src/bunit.web.query/Roles/RoleQueryExtensions.cs
@@ -17,6 +17,8 @@ public static class RoleQueryExtensions
 	/// <param name="configureOptions">Method used to override the default behavior of FindByRole.</param>
 	public static IElement FindByRole(this IRenderedComponent<IComponent> renderedComponent, AriaRole role, Action<ByRoleOptions>? configureOptions = null)
 	{
+		ArgumentNullException.ThrowIfNull(renderedComponent);
+
 		var options = ByRoleOptions.Default;
 		if (configureOptions is not null)
 		{
@@ -36,6 +38,8 @@ public static IElement FindByRole(this IRenderedComponent<IComponent> renderedCo
 	/// <returns>A read-only collection of elements matching the role. Returns an empty collection if no matches are found.</returns>
 	public static IReadOnlyList<IElement> FindAllByRole(this IRenderedComponent<IComponent> renderedComponent, AriaRole role, Action<ByRoleOptions>? configureOptions = null)
 	{
+		ArgumentNullException.ThrowIfNull(renderedComponent);
+
 		var options = ByRoleOptions.Default;
 		if (configureOptions is not null)
 		{
@@ -48,7 +52,8 @@ public static IReadOnlyList<IElement> FindAllByRole(this IRenderedComponent<ICom
 
 	internal static IElement? FindByRoleInternal(this IRenderedComponent<IComponent> renderedComponent, AriaRole role, ByRoleOptions options)
 	{
-		return FindAllByRoleInternal(renderedComponent, role, options).FirstOrDefault();
+		var results = FindAllByRoleInternal(renderedComponent, role, options);
+		return results.Count > 0 ? results[0] : null;
 	}
 
 	internal static IReadOnlyList<IElement> FindAllByRoleInternal(this IRenderedComponent<IComponent> renderedComponent, AriaRole role, ByRoleOptions options)
@@ -149,7 +154,7 @@ private static bool MatchesOptions(IElement element, ByRoleOptions options, INod
 		if (!string.IsNullOrEmpty(explicitRole))
 		{
 			// role attribute can have space-separated values; take the first token
-			var firstToken = explicitRole.Split(' ', StringSplitOptions.RemoveEmptyEntries)[0].ToLowerInvariant();
+			var firstToken = explicitRole.Split(' ', StringSplitOptions.RemoveEmptyEntries)[0].ToUpperInvariant();
 			return ParseRoleString(firstToken);
 		}
 
@@ -158,89 +163,89 @@ private static bool MatchesOptions(IElement element, ByRoleOptions options, INod
 
 	private static AriaRole? ParseRoleString(string roleString) => roleString switch
 	{
-		"alert" => AriaRole.Alert,
-		"alertdialog" => AriaRole.AlertDialog,
-		"application" => AriaRole.Application,
-		"article" => AriaRole.Article,
-		"banner" => AriaRole.Banner,
-		"blockquote" => AriaRole.Blockquote,
-		"button" => AriaRole.Button,
-		"caption" => AriaRole.Caption,
-		"cell" => AriaRole.Cell,
-		"checkbox" => AriaRole.Checkbox,
-		"code" => AriaRole.Code,
-		"columnheader" => AriaRole.ColumnHeader,
-		"combobox" => AriaRole.Combobox,
-		"complementary" => AriaRole.Complementary,
-		"contentinfo" => AriaRole.ContentInfo,
-		"definition" => AriaRole.Definition,
-		"deletion" => AriaRole.Deletion,
-		"dialog" => AriaRole.Dialog,
-		"directory" => AriaRole.Directory,
-		"document" => AriaRole.Document,
-		"emphasis" => AriaRole.Emphasis,
-		"feed" => AriaRole.Feed,
-		"figure" => AriaRole.Figure,
-		"form" => AriaRole.Form,
-		"generic" => AriaRole.Generic,
-		"grid" => AriaRole.Grid,
-		"gridcell" => AriaRole.GridCell,
-		"group" => AriaRole.Group,
-		"heading" => AriaRole.Heading,
-		"img" => AriaRole.Img,
-		"insertion" => AriaRole.Insertion,
-		"link" => AriaRole.Link,
-		"list" => AriaRole.List,
-		"listbox" => AriaRole.Listbox,
-		"listitem" => AriaRole.Listitem,
-		"log" => AriaRole.Log,
-		"main" => AriaRole.Main,
-		"mark" => AriaRole.Mark,
-		"marquee" => AriaRole.Marquee,
-		"math" => AriaRole.Math,
-		"menu" => AriaRole.Menu,
-		"menubar" => AriaRole.Menubar,
-		"menuitem" => AriaRole.Menuitem,
-		"menuitemcheckbox" => AriaRole.Menuitemcheckbox,
-		"menuitemradio" => AriaRole.Menuitemradio,
-		"meter" => AriaRole.Meter,
-		"navigation" => AriaRole.Navigation,
-		"none" => AriaRole.None,
-		"note" => AriaRole.Note,
-		"option" => AriaRole.Option,
-		"paragraph" => AriaRole.Paragraph,
-		"presentation" => AriaRole.Presentation,
-		"progressbar" => AriaRole.Progressbar,
-		"radio" => AriaRole.Radio,
-		"radiogroup" => AriaRole.Radiogroup,
-		"region" => AriaRole.Region,
-		"row" => AriaRole.Row,
-		"rowgroup" => AriaRole.Rowgroup,
-		"rowheader" => AriaRole.Rowheader,
-		"scrollbar" => AriaRole.Scrollbar,
-		"search" => AriaRole.Search,
-		"searchbox" => AriaRole.Searchbox,
-		"separator" => AriaRole.Separator,
-		"slider" => AriaRole.Slider,
-		"spinbutton" => AriaRole.Spinbutton,
-		"status" => AriaRole.Status,
-		"strong" => AriaRole.Strong,
-		"subscript" => AriaRole.Subscript,
-		"superscript" => AriaRole.Superscript,
-		"switch" => AriaRole.Switch,
-		"tab" => AriaRole.Tab,
-		"table" => AriaRole.Table,
-		"tablist" => AriaRole.Tablist,
-		"tabpanel" => AriaRole.Tabpanel,
-		"term" => AriaRole.Term,
-		"textbox" => AriaRole.Textbox,
-		"time" => AriaRole.Time,
-		"timer" => AriaRole.Timer,
-		"toolbar" => AriaRole.Toolbar,
-		"tooltip" => AriaRole.Tooltip,
-		"tree" => AriaRole.Tree,
-		"treegrid" => AriaRole.Treegrid,
-		"treeitem" => AriaRole.Treeitem,
+		"ALERT" => AriaRole.Alert,
+		"ALERTDIALOG" => AriaRole.AlertDialog,
+		"APPLICATION" => AriaRole.Application,
+		"ARTICLE" => AriaRole.Article,
+		"BANNER" => AriaRole.Banner,
+		"BLOCKQUOTE" => AriaRole.Blockquote,
+		"BUTTON" => AriaRole.Button,
+		"CAPTION" => AriaRole.Caption,
+		"CELL" => AriaRole.Cell,
+		"CHECKBOX" => AriaRole.Checkbox,
+		"CODE" => AriaRole.Code,
+		"COLUMNHEADER" => AriaRole.ColumnHeader,
+		"COMBOBOX" => AriaRole.Combobox,
+		"COMPLEMENTARY" => AriaRole.Complementary,
+		"CONTENTINFO" => AriaRole.ContentInfo,
+		"DEFINITION" => AriaRole.Definition,
+		"DELETION" => AriaRole.Deletion,
+		"DIALOG" => AriaRole.Dialog,
+		"DIRECTORY" => AriaRole.Directory,
+		"DOCUMENT" => AriaRole.Document,
+		"EMPHASIS" => AriaRole.Emphasis,
+		"FEED" => AriaRole.Feed,
+		"FIGURE" => AriaRole.Figure,
+		"FORM" => AriaRole.Form,
+		"GENERIC" => AriaRole.Generic,
+		"GRID" => AriaRole.Grid,
+		"GRIDCELL" => AriaRole.GridCell,
+		"GROUP" => AriaRole.Group,
+		"HEADING" => AriaRole.Heading,
+		"IMG" => AriaRole.Img,
+		"INSERTION" => AriaRole.Insertion,
+		"LINK" => AriaRole.Link,
+		"LIST" => AriaRole.List,
+		"LISTBOX" => AriaRole.Listbox,
+		"LISTITEM" => AriaRole.Listitem,
+		"LOG" => AriaRole.Log,
+		"MAIN" => AriaRole.Main,
+		"MARK" => AriaRole.Mark,
+		"MARQUEE" => AriaRole.Marquee,
+		"MATH" => AriaRole.Math,
+		"MENU" => AriaRole.Menu,
+		"MENUBAR" => AriaRole.Menubar,
+		"MENUITEM" => AriaRole.Menuitem,
+		"MENUITEMCHECKBOX" => AriaRole.Menuitemcheckbox,
+		"MENUITEMRADIO" => AriaRole.Menuitemradio,
+		"METER" => AriaRole.Meter,
+		"NAVIGATION" => AriaRole.Navigation,
+		"NONE" => AriaRole.None,
+		"NOTE" => AriaRole.Note,
+		"OPTION" => AriaRole.Option,
+		"PARAGRAPH" => AriaRole.Paragraph,
+		"PRESENTATION" => AriaRole.Presentation,
+		"PROGRESSBAR" => AriaRole.Progressbar,
+		"RADIO" => AriaRole.Radio,
+		"RADIOGROUP" => AriaRole.Radiogroup,
+		"REGION" => AriaRole.Region,
+		"ROW" => AriaRole.Row,
+		"ROWGROUP" => AriaRole.Rowgroup,
+		"ROWHEADER" => AriaRole.Rowheader,
+		"SCROLLBAR" => AriaRole.Scrollbar,
+		"SEARCH" => AriaRole.Search,
+		"SEARCHBOX" => AriaRole.Searchbox,
+		"SEPARATOR" => AriaRole.Separator,
+		"SLIDER" => AriaRole.Slider,
+		"SPINBUTTON" => AriaRole.Spinbutton,
+		"STATUS" => AriaRole.Status,
+		"STRONG" => AriaRole.Strong,
+		"SUBSCRIPT" => AriaRole.Subscript,
+		"SUPERSCRIPT" => AriaRole.Superscript,
+		"SWITCH" => AriaRole.Switch,
+		"TAB" => AriaRole.Tab,
+		"TABLE" => AriaRole.Table,
+		"TABLIST" => AriaRole.Tablist,
+		"TABPANEL" => AriaRole.Tabpanel,
+		"TERM" => AriaRole.Term,
+		"TEXTBOX" => AriaRole.Textbox,
+		"TIME" => AriaRole.Time,
+		"TIMER" => AriaRole.Timer,
+		"TOOLBAR" => AriaRole.Toolbar,
+		"TOOLTIP" => AriaRole.Tooltip,
+		"TREE" => AriaRole.Tree,
+		"TREEGRID" => AriaRole.Treegrid,
+		"TREEITEM" => AriaRole.Treeitem,
 		_ => null,
 	};
 
@@ -317,12 +322,8 @@ private static bool IsDisabledByFieldset(IElement element)
 		var parent = element.ParentElement;
 		while (parent is not null)
 		{
-			if (parent.NodeName == "FIELDSET" && parent.HasAttribute("disabled"))
-			{
-				// Exception: elements in the first <legend> of a disabled fieldset are NOT disabled
-				if (!IsInFirstLegend(element, parent))
-					return true;
-			}
+			if (parent.NodeName == "FIELDSET" && parent.HasAttribute("disabled") && !IsInFirstLegend(element, parent))
+				return true;
 
 			parent = parent.ParentElement;
 		}
diff --git a/tests/bunit.web.query.tests/Roles/RoleQueryExtensionsTest.cs b/tests/bunit.web.query.tests/Roles/RoleQueryExtensionsTest.cs
index 504843e19..423143af7 100644
--- a/tests/bunit.web.query.tests/Roles/RoleQueryExtensionsTest.cs
+++ b/tests/bunit.web.query.tests/Roles/RoleQueryExtensionsTest.cs
@@ -391,6 +391,264 @@ public void Should_support_disabled_fieldset()
 			.ShouldContain(b => b.GetAttribute("data-testid") == "inside-fieldset-element");
 	}
 
+	[Fact(DisplayName = "should throw ArgumentNullException when renderedComponent is null")]
+	public void Should_throw_when_rendered_component_is_null()
+	{
+		IRenderedComponent<IComponent>? nullComponent = null;
+
+		Should.Throw<ArgumentNullException>(() => nullComponent!.FindByRole(AriaRole.Button));
+		Should.Throw<ArgumentNullException>(() => nullComponent!.FindAllByRole(AriaRole.Button));
+	}
+
+	[Fact(DisplayName = "should support case-insensitive explicit roles")]
+	public void Should_support_case_insensitive_explicit_roles()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<div role="BUTTON">Upper</div>
+				<div role="Button">Mixed</div>
+				<div role="button">Lower</div>
+				"""));
+
+		var buttons = cut.FindAllByRole(AriaRole.Button);
+		buttons.Count.ShouldBe(3);
+	}
+
+	[Fact(DisplayName = "should map img with empty alt to presentation role")]
+	public void Should_map_img_with_empty_alt_to_presentation()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<img alt="" />
+				<img alt="A photo" />
+				<img />
+				"""));
+
+		var presentations = cut.FindAllByRole(AriaRole.Presentation);
+		presentations.Count.ShouldBe(1);
+		presentations[0].GetAttribute("alt").ShouldBe(string.Empty);
+
+		var images = cut.FindAllByRole(AriaRole.Img);
+		images.Count.ShouldBe(2);
+	}
+
+	[Fact(DisplayName = "should map anchor with href to link and without to generic")]
+	public void Should_map_anchor_with_and_without_href()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<a href="/home">Home</a>
+				<a>No link</a>
+				"""));
+
+		var links = cut.FindAllByRole(AriaRole.Link);
+		links.Count.ShouldBe(1);
+		links[0].TextContent.ShouldBe("Home");
+
+		var generics = cut.FindAllByRole(AriaRole.Generic);
+		generics.ShouldContain(e => e.TextContent == "No link");
+	}
+
+	[Fact(DisplayName = "should map input types to correct roles")]
+	public void Should_map_input_types_to_correct_roles()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<input type="text" />
+				<input type="email" />
+				<input type="tel" />
+				<input type="url" />
+				<input type="password" />
+				<input />
+				<input type="checkbox" />
+				<input type="radio" />
+				<input type="range" />
+				<input type="number" />
+				<input type="search" />
+				<input type="button" />
+				<input type="submit" />
+				<input type="reset" />
+				<input type="image" alt="img" />
+				<input type="hidden" />
+				"""));
+
+		// text, email, tel, url, password, and default (no type) all map to Textbox
+		cut.FindAllByRole(AriaRole.Textbox).Count.ShouldBe(6);
+
+		cut.FindAllByRole(AriaRole.Checkbox).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Radio).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Slider).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Spinbutton).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Searchbox).Count.ShouldBe(1);
+
+		// button, submit, reset, image all map to Button
+		cut.FindAllByRole(AriaRole.Button).Count.ShouldBe(4);
+	}
+
+	[Fact(DisplayName = "should not map hidden input to any role")]
+	public void Should_not_map_hidden_input_to_any_role()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""<input type="hidden" />"""));
+
+		cut.FindAllByRole(AriaRole.Textbox).ShouldBeEmpty();
+	}
+
+	[Fact(DisplayName = "should map form with accessible name to form role")]
+	public void Should_map_form_with_accessible_name_to_form_role()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<form aria-label="Search">Search form</form>
+				<form>Unlabelled form</form>
+				"""));
+
+		var forms = cut.FindAllByRole(AriaRole.Form);
+		forms.Count.ShouldBe(1);
+		forms[0].TextContent.ShouldBe("Search form");
+	}
+
+	[Fact(DisplayName = "should map section with accessible name to region role")]
+	public void Should_map_section_with_accessible_name_to_region_role()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<section aria-label="Main content">Content</section>
+				<section>Unlabelled</section>
+				"""));
+
+		var regions = cut.FindAllByRole(AriaRole.Region);
+		regions.Count.ShouldBe(1);
+		regions[0].TextContent.ShouldBe("Content");
+	}
+
+	[Fact(DisplayName = "should map semantic HTML elements to implicit roles")]
+	public void Should_map_semantic_html_elements()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<nav>Nav</nav>
+				<article>Article</article>
+				<aside>Aside</aside>
+				<footer>Footer</footer>
+				<header>Header</header>
+				<hr />
+				<figure>Figure</figure>
+				<main>Main</main>
+				<li>ListItem</li>
+				"""));
+
+		cut.FindAllByRole(AriaRole.Navigation).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Article).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Complementary).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.ContentInfo).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Banner).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Separator).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Figure).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Main).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Listitem).Count.ShouldBe(1);
+	}
+
+	[Fact(DisplayName = "should map list elements to list role")]
+	public void Should_map_list_elements_to_list_role()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<ul><li>a</li></ul>
+				<ol><li>b</li></ol>
+				<menu><li>c</li></menu>
+				"""));
+
+		cut.FindAllByRole(AriaRole.List).Count.ShouldBe(3);
+	}
+
+	[Fact(DisplayName = "should map table elements to correct roles")]
+	public void Should_map_table_elements_to_correct_roles()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<table>
+					<thead><tr><th>Header</th></tr></thead>
+					<tbody><tr><td>Cell</td></tr></tbody>
+					<tfoot><tr><td>Footer</td></tr></tfoot>
+				</table>
+				"""));
+
+		cut.FindAllByRole(AriaRole.Table).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Rowgroup).Count.ShouldBe(3);
+		cut.FindAllByRole(AriaRole.Row).Count.ShouldBe(3);
+		cut.FindAllByRole(AriaRole.ColumnHeader).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Cell).Count.ShouldBe(2);
+	}
+
+	[Fact(DisplayName = "should map meter, progress, textarea, and datalist")]
+	public void Should_map_additional_elements()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<meter value="0.5">50%</meter>
+				<progress value="0.5">50%</progress>
+				<textarea></textarea>
+				<datalist><option>One</option></datalist>
+				"""));
+
+		cut.FindAllByRole(AriaRole.Meter).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Progressbar).Count.ShouldBe(1);
+		cut.FindAllByRole(AriaRole.Textbox).Count.ShouldBe(1);
+	}
+
+	[Fact(DisplayName = "should use first token of space-separated role attribute")]
+	public void Should_use_first_token_of_space_separated_role()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<div role="button link">Multi-role</div>
+				"""));
+
+		var buttons = cut.FindAllByRole(AriaRole.Button);
+		buttons.Count.ShouldBe(1);
+		buttons[0].TextContent.ShouldBe("Multi-role");
+
+		// Should NOT match the second token
+		cut.FindAllByRole(AriaRole.Link).ShouldBeEmpty();
+	}
+
+	[Fact(DisplayName = "should support native details open as expanded")]
+	public void Should_support_native_details_open_as_expanded()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""
+				<details><summary>Closed</summary></details>
+				<details open><summary>Open</summary></details>
+				"""));
+
+		var expanded = cut.FindAllByRole(AriaRole.Group, o => o.Expanded = true);
+		expanded.Count.ShouldBe(1);
+
+		var collapsed = cut.FindAllByRole(AriaRole.Group, o => o.Expanded = false);
+		collapsed.Count.ShouldBe(1);
+	}
+
+	[Fact(DisplayName = "should include filter details in RoleNotFoundException message")]
+	public void Should_include_filter_details_in_exception_message()
+	{
+		var cut = Render<Wrapper>(ps =>
+			ps.AddChildContent("""<div>Nothing</div>"""));
+
+		var exception = Should.Throw<RoleNotFoundException>(() =>
+			cut.FindByRole(AriaRole.Checkbox, o =>
+			{
+				o.Name = "Accept";
+				o.Checked = true;
+				o.Disabled = false;
+			}));
+
+		exception.Message.ShouldContain("checkbox");
+		exception.Message.ShouldContain("name: 'Accept'");
+		exception.Message.ShouldContain("checked: true");
+		exception.Message.ShouldContain("disabled: false");
+	}
+
 	[Fact(DisplayName = "should reflect latest value when element rerenders")]
 	public void Should_reflect_latest_value_when_element_rerenders()
 	{