Images missing alt text

What Is This Issue

This issue checks whether all image elements (<img> tags) on a webpage include meaningful alternative (alt) text that describes the image content or purpose.

What passes

A passing implementation means that every meaningful image has descriptive alt text. This is considered passing when:

All content images have an alt attribute present
The alt text is descriptive and meaningful (not generic placeholders like “image” or “photo”)
Decorative images properly use empty alt text (alt="")
At least 80% of images have descriptive alt text (when non-descriptive alt exists)

Example

An image tag written as <img src="golden-retriever.jpg" alt="Golden retriever playing in park with red ball"> would pass. However, <img src="img1.jpg" alt="image"> (generic alt) or <img src="photo.jpg"> (missing alt) would fail.

Why Is This Important

Alt text is critical for both accessibility and SEO:

Accessibility

Alt text enables screen readers to describe images to visually impaired users. Missing or poor alt text creates barriers to accessibility and may violate WCAG guidelines (a legal requirement in many jurisdictions).

Rankings & Indexability

Search engines use alt text to understand image content and context. Descriptive alt text helps images appear in image search results and provides semantic signals for page relevance.

AI Search / AEO

As AI-powered search systems become more prevalent, they rely heavily on alt text to understand visual content and answer image-related queries.

SEO Health Score Impact

Resolving this issue improves the overall SEO health score by ensuring the site meets accessibility standards and provides clear image context to search engines. Sites with proper alt text typically see better image search visibility and improved accessibility compliance.

How XeoPix Detects This

XeoPix identifies this issue through the following logical steps:

1. HTML Parsing

The crawler fetches the page and parses the raw HTML code (without executing JavaScript).

2. Image and Alt Extraction

XeoPix identifies all <img> elements and extracts their src, alt, and other relevant attributes.

3. Alt Text Classification

Each image is classified into one of these categories:

Descriptive alt present: The alt attribute exists and contains meaningful descriptive text
Empty alt: The alt attribute exists but is empty (alt=""), appropriate for decorative images
Missing alt: The alt attribute is completely absent from the tag
Non-descriptive alt: The alt attribute exists but contains generic placeholders like “image”, “photo”, or filename-only text

4. Coverage Calculation

XeoPix calculates the percentage of images that have descriptive alt text.

5. Issue Triggering

The issue is flagged when:

Any image is missing the alt attribute entirely
Images have non-descriptive alt text and descriptive alt ratio is below 80%
Five or more images are missing alt text (considered severe)
The overall alt text compliance fails accessibility standards

How To Fix

1. Add alt text to all images

Ensure every meaningful image includes an alt attribute that describes what the image shows or represents.

2. Make alt text descriptive

Write alt text that conveys the purpose or content of the image, not just its appearance. For example, use “Woman using laptop to check email” instead of “laptop image”.

3. Use empty alt for decorative images

For purely decorative images that don’t convey meaning, use alt="" so screen readers skip them.

4. Enforce in CMS workflows

Configure your content management system to require alt text input when uploading images.

5. Validate and iterate

After making changes, re-crawl the site to confirm all images have appropriate alt text and generic placeholders have been replaced with descriptive text.

What We Store

Storage Level

Page Level

Database Table / Prisma Model

PageImageAnalysis

Stored Fields

Field	Type	Description
imageAltText	String?	Alt text of the image

Detection Dependencies

HTML Document

Examples

Example 1: Passing Implementation

Scenario: Product image with descriptive alt text

Passing state:


<img
  src="golden-retriever.jpg"
  alt="Golden retriever playing in park with red ball"
/>

Alt text describes the image content in a meaningful way.

Example 2: Failing Implementation - Missing Alt

Scenario: Image without alt attribute

Failing state:


<img src="img1.jpg" />

Missing alt attribute entirely. Screen readers cannot describe the image.

Example 3: Failing Implementation - Generic Alt

Scenario: Image with non-descriptive alt text

Failing state:


<img src="photo.jpg" alt="image" />

Alt text is present but generic. Doesn’t provide meaningful description.

Unit Test

Test File

xeopix-crawling-v2/__tests__/seo-audit-checks/imageAnalysis/issue-42-all-images-descriptive.test.js

Purpose

This unit test validates that the image analysis correctly detects images that are missing, empty, or have non-descriptive alt attributes, which is critical for accessibility and SEO.

Tested Function

runImageAnalysis(ctx) from toggleGroups/imageAnalysis.js

Issue Information

Issue Number: 42
Issue Code: all_images_descriptive
Toggle Group: imageAnalysis

Test Scenarios

Positive Test Cases

#	Scenario	Expected Result
1	All images have descriptive `alt` text (`alt="A beautiful sunset over the mountains"`)	No issue detected
2	HTML contains no `<img>` tags	No issue detected
3	Empty HTML string	No issue detected, no crash
4	Images with `data-src` attribute and valid `alt` text	No issue detected
5	Alt text with special characters (`'quotes' & ampersands`, `< > "`)	No issue detected
6	Alt text with unicode characters (`日本語の説明`) and emoji (`Emoji 🎨 description`)	No issue detected

Negative Test Cases

#	Scenario	Expected Result
1	Image is missing the `alt` attribute entirely	Issue detected with `imageCount` = 1
2	Image has empty `alt` attribute (`alt=""`)	Issue detected with `imageCount` = 1
3	Image has whitespace-only `alt` attribute (`alt=" "`)	Issue detected with `imageCount` = 1
4	Multiple images with mixed alt text: missing, valid, empty, whitespace-only	Issue detected with `imageCount` = 3 (missing, empty, whitespace-only)
5	Images without `src` but with `data-src` and missing `alt`	Issue detected with `imageCount` = 1
6	Multiple images with mixed alt text presence (descriptive, missing, empty, descriptive, whitespace-only)	Issue detected with `imageCount` = 3

Edge Cases

#	Scenario	Expected Result
1	Empty HTML	Function does not throw; no issue detected
2	HTML with no `<img>` tags	No issue detected
3	Malformed HTML (unclosed `<img>` tag)	Function does not throw; no issue detected
4	Relative URL resolution (`/images/photo.jpg`) in sample images	Correctly resolved to absolute URL in `sampleImages`
5	Alt text with special characters (`'quotes' & ampersands`, `< > "`)	No issue detected
6	Alt text with unicode characters and emoji	No issue detected

Cache Validation

#	Scenario	Expected Result
1	Two consecutive calls with the same HTML	`result1 === result2` (same object reference); `ctx.cache['imageAnalysis']` is defined

Expected Outcome

Pass

The issue should be reported when one or more images on the page are missing the alt attribute, have an empty alt attribute, or have a whitespace-only alt attribute. The imageCount reflects the number of images with missing or non-descriptive alt text.

Fail

The issue should not be reported when all images have descriptive alt text (including text with special characters, unicode, and emoji), or when there are no images on the page.

Validation

The unit test verifies:

Correct issue detection: Images missing alt, with empty alt, or whitespace-only alt are correctly flagged
No false positives: Images with descriptive alt text (including special characters, unicode, and emoji) are not flagged
Payload validation: issueCode, details.imageCount, and details.sampleImages contain the correct data
URL resolution: Relative image URLs are resolved to absolute URLs using ctx.pageUrl
Cache behaviour: Results are cached on ctx.cache['imageAnalysis'] and subsequent calls return the same cached result
Error handling: Empty HTML, malformed HTML, and missing attributes are handled gracefully without throwing

File	Role
`toggleGroups/imageAnalysis.js`	Contains the `runImageAnalysis()` function under test
`issueCodes.js`	Defines the `ALL_IMAGES_DESCRIPTIVE` issue code constant

Coverage Summary

6 positive test cases covering valid descriptive alt text, no-image scenarios, special characters, unicode, emoji, and lazy-loaded images with alt text
6 negative test cases covering missing alt, empty alt, whitespace-only alt, and mixed scenarios with multiple images
6 edge cases covering empty HTML, malformed HTML, relative URL resolution, special characters, and unicode handling
1 cache validation test ensuring idempotent behaviour

References

Images Tutorial (Alt text) — W3C WAI
WCAG 2.2 Understanding 1.1.1 Non-text Content — W3C
Image SEO best practices — Google Search Central