Images with non-descriptive filenames

What Is This Issue

This issue checks whether image filenames are descriptive and meaningful rather than generic names like img001.jpg or photo123.png.

What passes

A passing implementation means that image filenames contain meaningful words that describe the image content or context. This is considered passing when:

• Image filenames include descriptive terms (like golden-retriever-park.jpg instead of IMG_001.jpg)
• At least 70% of image filenames are descriptive (when 5+ images exist on the page)
• Generic naming patterns (like sequential numbers or random hashes) are avoided

Example

An image file named blue-running-shoes-side-view.jpg would pass. However, DSC0001.jpg (camera default), img_12345.png (generic sequence), or a8f3e2.jpg (hash-only name) would fail.

Why Is This Important

While lower impact than alt text or image compression, descriptive filenames contribute to:

Indexability

Search engines use filenames as a lightweight signal to understand image content. Descriptive names provide helpful context for image indexing.

User Experience

When users right-click to save images or when images fail to load, descriptive filenames appear in save dialogs and broken image tooltips, creating a more professional experience.

Maintainability

Descriptive filenames make media libraries easier to organize, search, and audit, especially as sites scale to thousands of images.

SEO Health Score Impact

Resolving this issue improves the overall SEO health score by ensuring all image-related signals (filenames, alt text, compression) follow best practices. While filename quality alone has modest SEO impact, it complements other image optimizations as part of a comprehensive approach.

How XeoPix Detects This

XeoPix identifies this issue through the following logical steps:

1. Image URL Extraction

The crawler collects all image URLs from the page, including <img src>, <img srcset>, and <picture> element sources.

2. Filename Extraction

For each image URL, XeoPix extracts the filename from the URL pathname (the portion after the last / and before any query string).

3. Filename Quality Evaluation

Each filename is evaluated against quality rules:

• Descriptive: Filename contains meaningful words or tokens that describe the image
• Non-descriptive: Filename uses generic patterns like sequential numbers (img001), camera defaults (DSC0001), or random hashes without semantic meaning

4. Pattern Recognition

XeoPix identifies common generic naming patterns:

• Sequential numeric patterns (image1, photo001, img123)
• Camera-generated defaults (DSC, IMG, DCIM)
• Random hash-only names where no semantic tokens exist

5. Coverage Calculation

XeoPix calculates the percentage of images that have descriptive filenames.

6. Issue Triggering

The issue is flagged as a suggestion when:

• Any image uses a generic filename pattern
• Less than 70% of filenames are descriptive (for pages with 5+ images)
• The overall filename quality suggests weak naming standards

How To Fix

1. Rename images before upload

Use meaningful, descriptive filenames that reflect the image content (e.g., red-apple-on-white-background.jpg instead of image1.jpg).

2. Avoid generic patterns

Don’t use camera defaults (IMG_001.jpg), sequential numbers (img001.jpg), or random hashes as public filenames.

3. Establish naming conventions

Create and enforce media naming standards in your CMS or upload workflow to ensure all team members follow consistent practices.

4. Preserve semantics with cache busting

If you use cache-busting techniques (like adding version hashes to filenames), preserve the descriptive portion of the filename (e.g., golden-retriever-v2.jpg instead of a8f3e2.jpg).

5. Validate improvements

After making changes, re-crawl the site to confirm the descriptive filename ratio has improved and generic naming patterns have been eliminated.

What We Store

Storage Level

Page Level

Database Table / Prisma Model

PageImageAnalysis

Stored Fields

Detection Dependencies

• HTML Document (to extract image URLs from <img>, <img srcset>, and <picture> elements)
• URL Parsing (to extract filenames from image URLs)

Examples

Example 1: Passing Implementation

Scenario: Product image with descriptive filename

Passing state:

<img src="blue-running-shoes-side-view.jpg" alt="Blue running shoes" />

Filename describes the image content clearly.

Example 2: Failing Implementation - Camera Default

Scenario: Image with camera-generated filename

Failing state:

<img src="DSC0001.jpg" alt="Photo" />

Camera default filename doesn’t describe the image content.

Example 3: Failing Implementation - Hash-Only Name

Scenario: Image with random hash filename

Failing state:

<img src="a8f3e2.jpg" alt="Image" />

Hash-only filename provides no semantic meaning for SEO or users.

Unit Test

Test File

xeopix-crawling-v2/__tests__/seo-audit-checks/imageAnalysis/issue-51-image-filenames-descriptive.test.js

Purpose

This unit test validates that the image analysis correctly detects images with non-descriptive, generic, or random filenames (e.g., image.jpg, 12345.jpg, abc123def456.jpg) which negatively impacts SEO.

Tested Function

runImageAnalysis(ctx) from toggleGroups/imageAnalysis.js

Issue Information

• Issue Number: 51
• Issue Code: image_filenames_descriptive
• Toggle Group: imageAnalysis

Test Scenarios

Positive Test Cases

Negative Test Cases

Edge Cases

Cache Validation

Payload Validation

Expected Outcome

Pass

The issue should be reported when one or more images on the page have non-descriptive filenames, including generic names (image.*, photo.*, pic.*, img.*), numeric-only names, or random-character names. The imageCount reflects the number of non-descriptive images, and sampleImages contains objects with url and filename properties.

Fail

The issue should not be reported when all images have descriptive filenames (using hyphens or underscores as word separators), when there are no images on the page, or when the image has no src attribute.

Validation

The unit test verifies:

• Correct issue detection: Generic, numeric, and random-character filenames are correctly flagged
• No false positives: Descriptive filenames with hyphens and underscores are not flagged
• Payload validation: issueCode, details.imageCount, and details.sampleImages contain the correct data; sampleImages entries include both url and filename properties
• 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, missing src attributes, and malformed URLs are handled gracefully without throwing

Related Production Files

Coverage Summary

• 6 positive test cases covering descriptive filenames (hyphens, underscores), no-image scenarios, missing src, and multiple extensions
• 6 negative test cases covering generic, numeric, random, and mixed non-descriptive filenames, lazy-loaded images, and query parameters
• 6 edge cases covering empty HTML, malformed HTML, malformed URLs, relative URL resolution, and multiple extensions
• 1 cache validation test ensuring idempotent behaviour
• 1 payload validation test verifying the filename property in sampleImages

References

• Image SEO best practices  — Google Search Central
• SEO Starter Guide  — Google Search Central
• URL API  — MDN