Testing the axe rule aria-command-name

Test cases for the axe-core rule aria-command-name (axe-core 4.14). The rule checks that elements with role="button", role="link" or role="menuitem" have an accessible name.

The element passes if any one of these checks passes:

Native elements like <button> and <a href> are left to other rules (button-name and link-name), even when they have one of these roles.

Every example is live in the page, so you can run the axe extension straight over it. The expected results were checked by running axe-core 4.14.1 over this page. Look in both the axe issues list and the needs review list.

Number of test cases by expected result
Expected resultCases
Fail16
Flagged by a different rule instead5
Passes, but broken (axe misses it)7
Pass (valid control cases)9
Changes after interaction2

Sections

No accessible name

These all fail. Each one is announced as just "button", "link" or "menu item".

A1 Empty element

<div role="button" tabindex="0"></div>

Expected result: fail

A2 Empty aria-label

<div role="button" tabindex="0" aria-label=""></div>

Expected result: fail

A3 aria-label with only spaces

<div role="button" tabindex="0" aria-label="   "></div>

Expected result: fail

A4 Only a non-breaking space

 
<div role="button" tabindex="0">&nbsp;</div>

Expected result: fail

A5 Only an aria-hidden icon

The visible "X" is hidden from screen readers, so nothing is left.

<div role="button" tabindex="0"><span aria-hidden="true">X</span></div>

Expected result: fail

A6 Only an aria-hidden SVG

<div role="button" tabindex="0">
  <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M3 3 L13 13 M13 3 L3 13" stroke="currentColor" stroke-width="2"/></svg>
</div>

Expected result: fail

A7 Only an image with empty alt

The image is marked as decorative, so it adds nothing to the name.

<div role="button" tabindex="0">
  <img src="data:image/gif;base64,R0lGODlhAQABAAAAACw=" alt="" width="16" height="16">
</div>

Expected result: fail

A8 Text hidden with visibility: hidden

Hidden from everyone, so it isn't part of the name.

Save
<div role="button" tabindex="0"><span style="visibility: hidden;">Save</span></div>

Expected result: fail

A9 Text hidden with display: none

Save
<div role="button" tabindex="0"><span style="display: none;">Save</span></div>

Expected result: fail

A10 aria-labelledby points to a missing ID

On the aria-valid-attr-value page, a missing aria-labelledby ID was only needs review. Here it's a straight fail, because the element ends up with no name.

<div role="menu" aria-label="File">
  <div role="menuitem" tabindex="-1" aria-labelledby="a10-label"></div>
</div>

Expected result: fail

A11 aria-labelledby points to an empty element

<span id="a11-label"></span>
<div role="link" tabindex="0" aria-labelledby="a11-label"></div>

Expected result: fail

A12 aria-labelledby points to aria-hidden text

The referenced element exists, but its only text is hidden from screen readers.

<span id="a12-label"><span aria-hidden="true">Edit</span></span>
<div role="button" tabindex="0" aria-labelledby="a12-label"></div>

Expected result: fail

A13 Only aria-describedby

A description isn't a name.

Opens the help centre
<div role="link" tabindex="0" aria-describedby="a13-desc"></div>
<span id="a13-desc">Opens the help centre</span>

Expected result: fail

A14 Only aria-description

Same again, using aria-description.

<div role="button" tabindex="0" aria-description="Delete this item"></div>

Expected result: fail

A15 An a element without href

Without href, an <a> isn't a link, so it falls to this rule rather than link-name.

<a role="button" tabindex="0"></a>

Expected result: fail

A16 Empty menu item

<div role="menu" aria-label="Edit">
  <div role="menuitem" tabindex="-1"></div>
</div>

Expected result: fail

Ways to give a name

Control cases. All of these pass.

B1 Text content

Save
<div role="button" tabindex="0">Save</div>

Expected result: pass (valid)

B2 aria-label

<div role="button" tabindex="0" aria-label="Close">
  <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M3 3 L13 13 M13 3 L3 13" stroke="currentColor" stroke-width="2"/></svg>
</div>

Expected result: pass (valid)

B3 Visually hidden text

The text is hidden visually, but screen readers still get it. This is why the check called has-visible-text is a bit misleading.

Close
<div role="button" tabindex="0">
  <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M3 3 L13 13 M13 3 L3 13" stroke="currentColor" stroke-width="2"/></svg>
  <span style="position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap;">Close</span>
</div>

Expected result: pass (valid)

B4 Image with alt text

Print
<div role="button" tabindex="0">
  <img src="data:image/gif;base64,R0lGODlhAQABAAAAACw=" alt="Print" width="16" height="16">
</div>

Expected result: pass (valid)

B5 SVG with a title

Close
<div role="button" tabindex="0">
  <svg width="16" height="16" viewBox="0 0 16 16"><title>Close</title><path d="M3 3 L13 13 M13 3 L3 13" stroke="currentColor" stroke-width="2"/></svg>
</div>

Expected result: pass (valid)

B6 Child with role="img" and aria-label

X
<div role="button" tabindex="0">
  <span role="img" aria-label="Close">X</span>
</div>

Expected result: pass (valid)

B7 aria-labelledby with one empty and one good ID

Only one of the referenced elements needs text.

Share
<span id="b7-icon"></span>
<span id="b7-text">Share</span>
<div role="button" tabindex="0" aria-labelledby="b7-icon b7-text"></div>

Expected result: pass (valid)

B8 aria-labelledby pointing to hidden text

Hidden text can be used as a name through aria-labelledby. That's part of the naming rules, not an axe quirk.

<span id="b8-label" hidden>Delete item</span>
<div role="button" tabindex="0" aria-labelledby="b8-label"></div>

Expected result: pass (valid)

B9 Only a title

Passes, but the title tooltip isn't available to touch or keyboard users, so it's a weak choice.

<div role="button" tabindex="0" title="Refresh"></div>

Expected result: pass (valid)

Not tested at all

The rule only looks for an exact role="button", role="link" or role="menuitem". Anything else slips past, and no other axe rule picks these up.

C1 Uppercase role

Browsers generally treat this as a button, but axe's selector doesn't match it.

<div role="Button" tabindex="0"></div>

Expected result: passes, but it's broken (check manually)

C2 Trailing space in the role

<div role="button " tabindex="0"></div>

Expected result: passes, but it's broken (check manually)

C3 Fallback role list

Browsers use the first role they recognise, which is button.

<div role="button link" tabindex="0"></div>

Expected result: passes, but it's broken (check manually)

Flagged by a different rule instead

This rule doesn't flag these, but another one does. Worth knowing when you're reading a report.

D1 Empty link with role="button"

An <a href> is handled by link-name, even though it says it's a button.

<a href="#d1" role="button"></a>

Expected result: flagged by link-name instead

D2 Empty native button with role="menuitem"

A <button> is handled by button-name.

<div role="menu" aria-label="View">
  <button type="button" role="menuitem"></button>
</div>

Expected result: flagged by button-name instead

D3 Empty menuitemcheckbox

menuitemcheckbox and menuitemradio aren't covered by this rule.

<div role="menu" aria-label="Format">
  <div role="menuitemcheckbox" tabindex="-1" aria-checked="false"></div>
</div>

Expected result: flagged by aria-toggle-field-name instead

D4 Focusable button hidden with aria-hidden

Axe skips aria-hidden elements, so this rule never sees it. But you can still tab to it.

<div role="button" tabindex="0" aria-hidden="true"></div>

Expected result: flagged by aria-hidden-focus instead

D5 Name doesn't match the visible text

It has a name, so this rule passes. But a voice control user saying "click Send" won't hit it.

Send
<div role="button" tabindex="0" aria-label="Submit">Send</div>

Expected result: flagged by label-content-name-mismatch instead

Has a name, but it's no good

This rule only checks that a name exists, not that it makes sense. Nothing in axe flags these.

E1 A symbol as the name

Screen readers will say "times" or "multiplication sign".

×
<div role="button" tabindex="0">×</div>

Expected result: passes, but it's broken (check manually)

E2 aria-label="button"

An icon button announced as "button, button".

<div role="button" tabindex="0" aria-label="button">
  <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M3 3 L13 13 M13 3 L3 13" stroke="currentColor" stroke-width="2"/></svg>
</div>

Expected result: passes, but it's broken (check manually)

E3 Vague link text

Click here
<div role="link" tabindex="0">Click here</div>

Expected result: passes, but it's broken (check manually)

E4 Not keyboard accessible

The name is fine, but without tabindex you can't tab to it.

Read more
<div role="link">Read more</div>

Expected result: passes, but it's broken (check manually)

Changes after interaction

Axe only sees the page as it is when you run it. These pass on page load. Activate each button, then run axe again.

F1 Play button loses its name

When pressed, the script is meant to change the label to "Pause", but it sets it to an empty string.

<div role="button" tabindex="0" id="f1-button" aria-label="Play">
  <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M4 2 L13 8 L4 14 Z" fill="currentColor"/></svg>
</div>

On load: pass. After pressing: fail

F2 Menu with an empty item, hidden until opened

Axe doesn't test hidden content. The empty menu item is only found once the menu is open.

<button type="button" id="f2-button" aria-expanded="false" aria-controls="f2-menu">Options</button>
<div role="menu" id="f2-menu" aria-label="Options" hidden>
  <div role="menuitem" tabindex="-1">Rename</div>
  <div role="menuitem" tabindex="-1"></div>
</div>

On load: pass. After opening: fail