Alt Text
Test image alt attributes
WCAG 1.1.1 - Non-text Content (Level A)
All non-text content must have a text alternative that serves the equivalent purpose, except for decorative images which should have null alt text.
Mode:
Image Examples
Alt text comparison
[Image Placeholder]
Hero image on travel website
alt=""
Missing alt text entirely
[Image Placeholder]
Product image in e-commerce
alt="image1.jpg"
Filename is not descriptive
[Image Placeholder]
Data visualization
alt="Chart"
Too generic - doesn't convey the data
[Image Placeholder]
Decorative separator
alt="decorative divider"
Decorative images should have alt=""
Alt Text Guidelines
Do's and don'ts
✅ Good Alt Text
- • Descriptive: "Golden retriever playing fetch on beach"
- • Contextual: "CEO Jane Smith presenting Q4 results"
- • Functional: "Search button" for icon buttons
- • Data-rich: Chart data summarized in alt text
- • Empty for decorative: alt="" for dividers, backgrounds
❌ Bad Alt Text
- • Filenames: "IMG_2847.jpg", "photo-1.png"
- • Redundant: "Image of...", "Picture of..."
- • Too generic: "Photo", "Image", "Chart"
- • Too long: Entire paragraphs (use longdesc)
- • Missing: No alt attribute at all
Alt Text Decision Tree
When to use what
Is the image purely decorative?
├── YES → alt="" (empty string)
└── NO → Does it contain text?
├── YES → Include that text in alt
└── NO → Is it a link or button?
├── YES → Describe the action/destination
└── NO → Is it a complex image (chart, diagram)?
├── YES → Summarize + provide detailed description elsewhere
└── NO → Describe the content and purpose conciselyAutomation Tips
Testing hints
Playwright + axe-core
import AxeBuilder from '@axe-core/playwright';
// Check for missing alt text
const results = await new AxeBuilder({ page })
.withRules([
'image-alt', // All images have alt
'image-redundant-alt', // No "image of"
'input-image-alt', // Input type="image"
'role-img-alt' // role="img" elements
])
.analyze();
// Find images with poor alt text
const images = await page.$$('img');
for (const img of images) {
const alt = await img.getAttribute('alt');
const src = await img.getAttribute('src');
// Check for common issues
if (alt === null) {
console.log('Missing alt:', src);
} else if (/\.(jpg|png|gif)$/i.test(alt)) {
console.log('Filename as alt:', alt);
} else if (/^(image|photo|picture)/i.test(alt)) {
console.log('Redundant prefix:', alt);
}
}Manual Review Checklist
// Get all images for review
const imageData = await page.$$eval('img', imgs =>
imgs.map(img => ({
src: img.src,
alt: img.alt,
role: img.role,
isDecorative: img.alt === '' ||
img.role === 'presentation',
inLink: img.closest('a') !== null,
dimensions: {
width: img.width,
height: img.height
}
}))
);
// Flag images needing review
const needsReview = imageData.filter(img =>
!img.isDecorative &&
(!img.alt || img.alt.length < 5)
);
console.log('Images needing review:',
needsReview
);Testing Tips
Automation hints
- ✓ Use axe-core image rules:
image-alt,image-redundant-alt - ✓ Verify all images have alt:
img.getAttribute('alt') !== null - ✓ Check decorative images use alt="":
expect(img).toHaveAttribute('alt', '') - ✓ Verify alt text is not a filename (e.g., "image1.jpg")
- ✓ Test role="img" elements also have accessible names
