Alt text testing: a practical developer guide

Alt text testing checks more than whether every image has words in an alt attribute. A useful test first finds images in the rendered page, then asks what each image does in context: communicate information, perform an action, repeat nearby content, or decorate the layout. Automated checks can catch missing markup, but a person must decide whether the text preserves the image's purpose.

This guide gives developers a repeatable alt text testing workflow for source review, browser checks, manual judgment, and CI. It also separates a missing alt attribute from an intentionally empty one, because those two states have different behavior.

Alt text testing checklist

Test the deployed page and the important states that users can reach, not only the initial component source.

• Inventory rendered <img> elements, image inputs, SVG images, and CSS background images.
• Fail ordinary <img> elements that omit the alt attribute.
• Keep alt="" only when an image is decorative or redundant in that context.
• Describe the purpose of informative images, not every visible detail.
• Name the destination or action of an image-only link or button.
• Put the information from charts and complex diagrams in nearby text or data.
• Review localized pages and dynamic states after their content loads.
• Run automated checks in CI, then complete a manual context and screen-reader review.

WCAG 2.2 Success Criterion 1.1.1 requires a text alternative that serves the equivalent purpose for non-text content, with specific handling for controls, tests, sensory experiences, CAPTCHA, and decoration. The W3C's image decision tree turns that principle into practical questions for common image types.

Start alt text testing with image purpose

Do not write the alternative from the file alone. The same image may need different treatment on two pages because surrounding text and interaction change its job.

Classify each image before reviewing its markup:

• Informative: The image adds information that is not available nearby. Write a brief alternative that communicates that information.
• Decorative: The image adds no information or function. Use alt="" so assistive technology can ignore it.
• Functional: The image is the only content in a link or button. Describe the action or destination.
• Complex: A chart, map, or diagram carries more information than a short attribute can hold. Give it a concise label and provide the full result or data in nearby content.
• Redundant: Nearby text already communicates the same information. An empty alternative usually avoids hearing the same message twice.

The W3C HTML `alt` technique explains that the alternative must perform the same function as the image. That is a better test than asking whether the text describes every color, object, or layout detail.

Distinguish missing and empty alt attributes

These examples look similar in source, but they do not express the same intent:

<!-- Missing: the author did not provide an alternative-text decision. -->
<img src="release-status.png">

<!-- Empty: the author intentionally marks the image as decorative. -->
<img src="divider.svg" alt="">

For an informative image, add an alternative that carries the relevant meaning:

<img
  src="release-status.png"
  alt="Release audit: 3 blocking issues and 8 checks passed"
>

Do not repair every failure by inserting alt="". That makes an automated missing-attribute check pass while hiding meaningful content. Conversely, do not force prose onto decoration. The correct result comes from the image's purpose in the current page.

The HTML Standard's requirements for text alternatives define the alt value as replacement text when an image is unavailable. W3C's decorative image guidance recommends an empty alt value for decoration and warns that omitting the attribute can cause assistive technology to announce the filename.

Test informative, functional, and complex images

Informative images

Write the shortest text that preserves the information needed for the task. Avoid prefixes such as “image of” when the user already knows the element is an image. Include visible words when those words are not available as real text nearby.

<img
  src="mobile-overflow.png"
  alt="Checkout button clipped beyond the right edge at 375 pixels"
>

This alternative reports the finding rather than listing colors and interface chrome. If the nearby paragraph already states the same finding, use an empty alternative to avoid duplication.

Functional images

For an image-only control, test the accessible name of the control as a whole. The alternative should say what happens, not what the icon resembles:

<a href="/reports/latest">
  <img src="report.svg" alt="Open latest audit report">
</a>

If the link already contains visible text, the image can usually use alt="". The accessible name testing guide shows how link text, aria-label, aria-labelledby, and image alternatives combine into the name exposed to assistive technology.

Complex images

Do not squeeze a chart into a long attribute. Give the image a concise summary and put the result, values, or table in normal page content:

<figure>
  <img
    src="audit-trend.svg"
    alt="Blocking audit findings decreased across four releases"
  >
  <figcaption>
    Blocking findings by release: 12, 8, 5, and 2.
  </figcaption>
</figure>

The W3C complex images tutorial recommends a short description plus a longer text alternative when the image conveys substantial data. Test that a user can reach the same conclusion without seeing the chart.

Inspect the rendered page for alt text

Framework components, content systems, localization, and conditional rendering can change the final DOM. Inspect the page after it reaches the state you plan to ship.

Run this in browser developer tools to list rendered images and preserve the difference between missing and empty values:

[...document.images].map((image) => ({
  src: image.currentSrc || image.src,
  hasAlt: image.hasAttribute("alt"),
  alt: image.getAttribute("alt"),
  linked: Boolean(image.closest("a, button")),
  visible: Boolean(image.getClientRects().length),
}));

Filter the result in two passes. First, investigate hasAlt: false as a markup failure. Second, review every empty and non-empty value against the image's purpose. Repeat the check after opening menus, dialogs, galleries, validation states, or any view that loads images later.

Also inspect image-like content that document.images does not include:

• <input type="image"> needs an accessible name for its action.
• Inline SVG with an image role needs an accessible name.
• CSS background images cannot use an alt attribute; keep them decorative or provide equivalent content in HTML.
• Canvas output needs a designed text alternative or fallback content.

An alt text checker that only queries <img> elements is useful, but its coverage must be stated accurately.

Add automated alt text testing to CI

Use a small browser assertion for the deterministic requirement that ordinary images declare the attribute:

import { test, expect } from "@playwright/test";

test("rendered images declare alt behavior", async ({ page }) => {
  await page.goto("https://example.com/", { waitUntil: "networkidle" });

  const missing = await page.locator("img:not([alt])").evaluateAll((images) =>
    images.map((image) => ({
      src: (image as HTMLImageElement).currentSrc,
      html: image.outerHTML.slice(0, 240),
    })),
  );

  expect(missing).toEqual([]);
});

Add axe-core to cover more programmatically detectable image cases. The axe-core rule catalog includes checks for <img>, image inputs, image roles, and SVG images. Save the rule ID, impact, selector, and affected HTML in the CI artifact so a developer can reproduce the failure.

Keep the manual review in the release definition. Automation can detect absent markup and some accessible-name failures; it cannot reliably decide whether “Dashboard screenshot” communicates the information that matters on this particular page. The website accessibility checks before launch explain how automated evidence fits with keyboard and human review.

Check alt text without keyword stuffing

Alternative text helps people understand an image, and it also gives search systems context. Google's image SEO guidance says it uses alt text with computer vision and page content to understand an image. That is not a reason to paste a target keyword into every image.

Test the value as replacement content:

• Does it communicate the image's purpose in this paragraph or control?
• Does it avoid repeating the caption or adjacent sentence?
• Does it omit filenames, tracking labels, and keyword lists?
• Would the page still make sense if the image failed to load?

If the answer requires a paragraph, move that information into visible content. Useful page text serves more readers and is easier to maintain than a hidden essay inside one attribute.

Run alt text testing with Slop Audit

Run a Slop Audit against the public URL after deployment. Its browser stage counts rendered <img> elements that lack an alt attribute and records the result as image alternative-text evidence. The same bounded run also reports axe violation groups with impact, node count, and selectors when the accessibility engine completes.

Slop Audit does not decide whether every alt value is accurate, inspect every route, or certify WCAG conformance. An empty attribute passes its missing-attribute count because empty can be correct for decoration. Use the report to find missing markup and relevant automated violations, then apply the purpose review in this guide and test the affected experience with assistive technology.

For broader image delivery checks, use the website image optimization checklist. To preserve the result after launch, add the page and its important states to the website regression testing checklist.

Alt text testing release sign-off

• Every rendered ordinary image explicitly declares its alternative-text behavior.
• Empty alternatives are limited to decorative or redundant images.
• Informative alternatives preserve meaning rather than list visual details.
• Image-only controls expose their action or destination.
• Complex images have equivalent conclusions or data in page content.
• Dynamic, localized, and error states are included in the review.
• CI saves selectors and evidence for deterministic failures.
• A person reviews context and uses assistive technology on critical paths.
• The deployed URL is rescanned after fixes and monitored for regressions.

Alt text testing works best as a two-part gate: automate the markup that code can prove, then review the meaning that only page context can establish.