fix(settings): improve clarity of picture-tag method label and warning (#1015) by Miraeld · Pull Request #1056 · wp-media/imagify-plugin

Miraeld · 2026-05-20T00:15:31Z

Description

This change improves the clarity of the delivery-method selector in Imagify settings for next-gen image formats. The <picture> tag method was labelled "(preferred)", which led users — especially first-time setup users — to choose it by default without understanding the layout risks. Support consistently receives tickets about broken layouts, missing images in sliders, WooCommerce pages, and galleries caused by this method.

Two targeted copy changes are made to views/part-settings-webp.php:

Label: "(preferred)" → "(CDN-compatible)". This accurately reflects the technical reason to choose this option (rewrite rules do not work with CDN) without implying it is universally better.
Warning message: The existing brief note ("some themes may break") is replaced with an explicit warning that names the types of content typically affected (themes, sliders, WooCommerce pages, galleries, background images) and recommends rewrite rules for non-CDN sites.

Type of change

New feature (non-breaking change which adds functionality).
Bug fix (non-breaking change which fixes an issue).
Enhancement (non-breaking change which improves an existing functionality).
Breaking change (fix or feature that would cause existing functionality to not work as before).
Sub-task of Enhancement: Improve Clarity Around <picture> Tag Method and “Preferred” Label for Next-Gen Delivery #1015
Chore
Release

Detailed scenario

What was tested

Strategy C (Analysis) — wp-env was not reachable on port 8888; Strategies A (API) and B (Browser) were skipped.

Acceptance Criterion	Validation Method	Result	Evidence
Warning message is clearer and more explicit about possible layout impact	Code analysis — diff review of `views/part-settings-webp.php`	✅ PASS	New text explicitly names themes, sliders, WooCommerce pages, galleries, and notes that background images are not covered. Risk is communicated before the user enables the option.
"preferred" label reconsidered	Code analysis	✅ PASS	Label changed from `(preferred)` to `(CDN-compatible)`. Accurately reflects the technical reason (rewrite rules do not work with CDN) without implying universal superiority.
Linking to relevant documentation	Code analysis	⚠️ PARTIAL	No confirmed docs URL exists in the codebase for this specific feature page. Non-blocking; can be added when a page is published.

Code quality:

PHPCS: zero violations
printf placeholder count preserved (4 placeholders, all arguments unchanged)
esc_html__() wrapping pattern follows existing convention in this file
No functional logic, hooks, option names, or AJAX handlers changed

Smoke tests:

File parses correctly after changes; all PHP structures intact
Existing Tests/e2e/specs/settings.spec.ts tests cover page load and save — none test label copy, so no existing tests are affected

How to test

Install Imagify on a WordPress site (or use the local wp-env environment).
Go to Settings > Imagify and scroll to the Next-gen image format section.
Enable Display images in Next-Gen format on the site.
Verify the radio button for <picture> tags now reads "Use <picture> tags (CDN-compatible)" instead of "(preferred)".
In the info box below the radio buttons, verify the warning for the picture-tag method now reads:

"The second option replaces the <img> tags with <picture> tags in your page source. Required when using a CDN. Warning: this may break your site layout — some themes, sliders, WooCommerce pages, or galleries can be affected. Background images are not covered by this method. Always review your site after enabling, and consider using rewrite rules if you are not on a CDN."
Confirm the rewrite-rules option and CDN URL field remain unchanged.

Affected Features & Quality Assurance Scope

Imagify Settings page — Next-gen delivery method selector (display_nextgen_method radio group).
No backend logic, no database schema, no REST/AJAX endpoints are changed.
Translations for the two updated strings will need to be updated in translation files at the next release cycle.

Technical description

Documentation

Both changes are confined to views/part-settings-webp.php:

Location	Before	After
Line 78 — radio label	`Use <picture> tags (preferred)`	`Use <picture> tags (CDN-compatible)`
Lines 153-160 — info box	`This is the preferred solution but some themes may break, so make sure to verify that everything seems fine.`	Expanded warning listing specific risk areas and recommending rewrite rules for non-CDN users.

The pattern used (printf with esc_html__() format string and HTML tag arguments) follows the existing convention in this file.

New dependencies

None.

Risks

Translation strings: the two changed strings are new gettext keys; existing PO/MO translations will fall back to the English strings until updated. Impact is low (display text only).
No functional regression risk: no logic, hooks, or option names were changed.

Mandatory Checklist

Code validation

I validated all the Acceptance Criteria. If possible, provide screenshots or videos.
I triggered all changed lines of code at least once without new errors/warnings/notices.
I implemented built-in tests to cover the new/changed code.

Code style

I wrote a self-explanatory code about what it does.
I protected entry points against unexpected inputs.
I did not introduce unnecessary complexity.
Output messages (errors, notices, logs) are explicit enough for users to understand the issue and are actionnable.

Unticked items justification

Built-in tests: No unit or integration tests exist for UI copy strings in this project. The change is pure text; no new test coverage is warranted.

Additional Checks

In the case of complex code, I wrote comments to explain it.
When possible, I prepared ways to observe the implemented system (logs, data, etc.)
I added error handling logic when using functions that could throw errors (HTTP/API request, filesystem, etc.)

N/A — this is a UI copy change with no new logic.

Ports the .aiassistant skill system from BackWPup Pro, adapted for Imagify's single-edition architecture: new imagify-architecture skill, parameterised issue-workflow scripts, knowledge graph builder (322 nodes, 239 symbols indexed from first run), AGENTS.md guardrails, and PHPCS compliance specs.

- Add .wp-env.json for Docker-based WordPress local environment - Add bin/dev-up.sh, bin/dev-down.sh, bin/dev-seed.sh lifecycle scripts - Add Tests/e2e/ with Playwright config, fixtures, page objects, and 5 spec files - Add .github/workflows/e2e.yml CI workflow with IMAGIFY_API_KEY secret support - Add .claude/agents/ qa-engineer and e2e-qa-tester sub-agents - Add docs/E2E_TESTING.md as canonical test architecture reference - Add AGENTS.md with project conventions for AI agents - Update .gitignore for E2E artifacts and local issue cache

Rename IMAGIFY_API_KEY to IMAGIFY_TESTS_API_KEY across all E2E scaffold files to match the secret already configured in the GitHub repository.

- Media library column: use actual key 'imagify_optimized_file' - Bulk button: use '#imagify-bulk-action' (text is "Imagif'em all", not "Optimize") - Bulk stats: use '.imagify-bulk-table' (always rendered) - Settings: rename optimization-level test (Imagify uses Lossless checkbox, not Normal/Aggressive/Ultra) and gate it + WebP test behind IMAGIFY_TESTS_API_KEY because those sections are hidden without a valid API key - Account: skip invalid-key test without IMAGIFY_TESTS_API_KEY (requires live API call to produce a bad-key rejection notice)

…tion getByRole('button', { name: /save/i }) resolved to two elements ('Save Changes' and 'Save & Go to Bulk Optimizer'), causing strict mode failures in settings and account-connection specs. Use #submit instead.

On a fresh install, clicking the bulk optimize button triggers a SweetAlert2 confirmation modal (.imagify-before-bulk-infos) before launchAllProcesses() is called. The test was timing out waiting for .imagify-row-progress because the modal was never dismissed. Add startOptimization() to BulkOptimizationPage which handles the modal gracefully, then update the spec to use it.

Sources .env.local for API key, checks wp-env is up, auto-installs Playwright deps if missing. Passes all args through to playwright test so --headed, --ui, and spec patterns all work.

…eedback Imagify does not render a .notice-error on bad key submission. It renders an inline #imagify-check-api-container span without the imagify-valid class.

If the seed image failed to download (picsum.photos unreachable inside the container), there are no images to optimize and the progress bar never appears. Skip with a clear reason instead of timing out.

SweetAlert2 v6 uses .swal2-modal, v7+ uses .swal2-popup. The class-based selector was silently missing the modal. Use getByRole button name instead so the selector is version-agnostic.

…ulk test wp post meta delete only accepts one key at a time — passing multiple keys caused a silent failure. delete_post_meta_by_key() wipes a key across all posts in one call, no loop required.

…with e2e sections Merges chore/add-ai-assistant (coding guardrails, architecture rules, security, AI working protocol) with chore/e2e-setup (E2E testing §7, local dev §8 with test-e2e.sh, Playwright in tech stack). Also deduplicates /.TemporaryItems in .gitignore.

chore(e2e): scaffold Playwright E2E test infrastructure

…ude/agents Agents are not Claude Code-specific — any AI tool should be able to use them. The canonical location is now .aiassistant/agents/ alongside skills, specs, and the knowledge graph. .claude/agents is a symlink so Claude Code sub-agent discovery still works without maintaining a separate copy.

Clarifies that .aiassistant/agents/ is the source of truth and documents when to invoke qa-engineer vs e2e-qa-tester.

…y pipeline After PR creation (step 18), the workflow now automatically: - Invokes qa-engineer with the issue + PR number - qa-engineer selects validation strategies and delegates UI flows to e2e-qa-tester - e2e-qa-tester writes/runs Playwright tests and commits them back to the branch - Workflow only marks PR ready-for-review after READY TO MERGE is returned Adds a QA Pipeline section with a decision tree and direct invocation examples.

After qa-engineer returns READY TO MERGE, the workflow now edits the PR body to fill the "What was tested" section with the QA report before converting the PR from draft to ready-for-review.

Miraeld · 2026-05-20T00:16:47Z

Test Report — fix(settings): improve clarity of picture-tag method label and warning (#1015)

Branch: fix/1015-improve-clarity-picture-tag
Strategies used: Strategy B (Browser — Playwright)

Acceptance Criteria

Acceptance Criterion	Validation Method	Result	Evidence
`<picture>` tags radio label reads "(CDN-compatible)" not "(preferred)"	Browser (Playwright) — checked label text of `input[value="picture"]` sibling	✅ PASS	`page.locator("label").filter({ hasText: /CDN-compatible/i })` found visible element; `(preferred)` substring absent from full page HTML
Warning info box names sliders, WooCommerce, galleries, background images	Browser (Playwright) — `#describe-display_nextgen_method` inner text	✅ PASS	Inner text: "Warning: this may break your site layout — some themes, sliders, WooCommerce pages, or galleries can be affected. Background images are not covered by this method."
Expanded warning recommends rewrite rules for non-CDN users	Browser (Playwright)	✅ PASS	Text contains "consider using rewrite rules if you are not on a CDN"
Rewrite-rules radio option remains unchanged	Browser (Playwright)	✅ PASS	Label "Use rewrite rules" still visible

Smoke Tests

Area	Action	Result	Evidence
Settings page	Navigated to `/wp-admin/options-general.php?page=imagify`	✅ PASS	Page loaded, no WP fatal error
Bulk optimization page	Navigated to `/wp-admin/upload.php?page=imagify-bulk-optimization`	✅ PASS	Rendered without errors
Media library	Navigated to `/wp-admin/upload.php?mode=list`	✅ PASS	Imagify column visible
Plugin activation	`wp plugin deactivate imagify-plugin && wp plugin activate imagify-plugin`	✅ PASS	No fatal errors

Overall: ✅ PASS

Blockers: None.

Recommendations:

No docs URL for the <picture> tags method is currently linked in the info box. Non-blocking; the PR body notes this is intentional pending a page being published.

Automated Tests Written

New spec file committed to this branch at Tests/e2e/specs/settings-webp-method.spec.ts.
Four deterministic Playwright tests:

picture-tag radio label reads CDN-compatible, not preferred — asserts label text and absence of "(preferred)"
warning info box names sliders, WooCommerce, galleries, background images — asserts exact keyword matches in #describe-display_nextgen_method
warning info box explicitly warns about layout breakage — asserts "Warning" and "review" text
rewrite-rules radio option is still present — non-regression guard

All 4 tests pass locally (npx playwright test specs/settings-webp-method.spec.ts → 4 passed in 16.7s).

READY TO MERGE

Screenshots

Step	Screenshot
Full settings page
Radio buttons — "(CDN-compatible)" label
Radio labels close-up
Info box with expanded warning

codacy-production · 2026-05-20T00:17:48Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 duplication

Metric Results

Duplication 0

View in Codacy

🟢 Coverage ∅ diff coverage · +0.00% coverage variation

Metric Results

Coverage variation ✅ +0.00% coverage variation (-0.10%)

Diff coverage ✅ ∅ diff coverage (50.00%)

View coverage diff in Codacy

Coverage variation details

Coverable lines Covered lines Coverage

Common ancestor commit (d23c0a9) 13940 48 0.34%

Head commit (d7c1471) 13940 (+0) 48 (+0) 0.34% (+0.00%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

Coverable lines Covered lines Diff coverage

Pull request (#1056) 0 0 ∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

- Replace the vague '(preferred)' label with '(CDN-compatible)' to accurately convey the technical reason for choosing the picture tag method (rewrite rules do not work with CDN). - Expand the warning message to explicitly list layout risks: themes, sliders, WooCommerce pages, galleries and the absence of coverage for background images. - Recommend falling back to rewrite rules for non-CDN sites. Resolves #1015

Validates that: - The <picture> tags radio label reads "(CDN-compatible)" not "(preferred)" - The warning info box names sliders, WooCommerce, galleries, and background images - The rewrite-rules option is still present All 4 tests pass against the local wp-env stack on port 8888.

Miraeld · 2026-05-21T10:15:45Z

Manually checked, everything is fine.

remyperona · 2026-05-21T20:58:26Z

The issue I see here is that the copywriting changes have not been clearly defined nor validated by whoever would be responsible about it in the first place (product and/or marketing). We let the AI decide based on the issue description, but what is contained in it is only examples.

Miraeld added 22 commits May 18, 2026 10:46

chore(e2e): use existing IMAGIFY_TESTS_API_KEY secret name

c18b09d

Rename IMAGIFY_API_KEY to IMAGIFY_TESTS_API_KEY across all E2E scaffold files to match the secret already configured in the GitHub repository.

fix(e2e): use bulk.statsTable locator instead of stale inline selector

542f994

chore: gitignore .env.local for local secrets

317431b

chore(e2e): add bin/test-e2e.sh local test runner

4320737

Sources .env.local for API key, checks wp-env is up, auto-installs Playwright deps if missing. Passes all args through to playwright test so --headed, --ui, and spec patterns all work.

fix(e2e): use #imagify-check-api-container selector for invalid key f…

9c3789f

…eedback Imagify does not render a .notice-error on bad key submission. It renders an inline #imagify-check-api-container span without the imagify-valid class.

fix(e2e): skip bulk progress test when no media attachments are seeded

f90cf7c

If the seed image failed to download (picsum.photos unreachable inside the container), there are no images to optimize and the progress bar never appears. Skip with a clear reason instead of timing out.

fix(e2e): dismiss bulk info modal by button text, not SweetAlert2 class

c15485d

SweetAlert2 v6 uses .swal2-modal, v7+ uses .swal2-popup. The class-based selector was silently missing the modal. Use getByRole button name instead so the selector is version-agnostic.

fix(e2e): use delete_post_meta_by_key to reset Imagify state before b…

c077d38

…ulk test wp post meta delete only accepts one key at a time — passing multiple keys caused a silent failure. delete_post_meta_by_key() wipes a key across all posts in one call, no loop required.

Merge pull request #1053 from wp-media/chore/e2e-setup

e1c5ab3

chore(e2e): scaffold Playwright E2E test infrastructure

docs(agents): list sub-agents in AGENTS.md with their canonical paths

7ef6cbe

Clarifies that .aiassistant/agents/ is the source of truth and documents when to invoke qa-engineer vs e2e-qa-tester.

fix(issue-workflow): enforce pr-template structure when creating PRs

a6ab519

feat(issue-workflow): run full E2E suite locally before opening PR

6611f0e

chore(ai): update qa-engineer step to append QA findings to PR body

e3caafa

After qa-engineer returns READY TO MERGE, the workflow now edits the PR body to fill the "What was tested" section with the QA report before converting the PR from draft to ready-for-review.

feat(qa): post QA report as PR comment with screenshot list

8e4771f

Miraeld marked this pull request as ready for review May 20, 2026 00:17

Miraeld force-pushed the fix/1015-improve-clarity-picture-tag branch from e398e50 to d841272 Compare May 20, 2026 00:23

Miraeld added 3 commits May 20, 2026 02:54

chore(qa): add QA screenshots

045bf12

chore(qa): remove QA screenshots

365c26c

Miraeld linked an issue May 20, 2026 that may be closed by this pull request

Enhancement: Improve Clarity Around <picture> Tag Method and “Preferred” Label for Next-Gen Delivery #1015

Open

Miraeld mentioned this pull request May 20, 2026

chore(ai): add AI assistant infrastructure #1050

Merged

17 tasks

Miraeld self-assigned this May 20, 2026

Miraeld mentioned this pull request May 20, 2026

Set up agentic AI delivery and run a minor release showcase #1046

Closed

22 tasks

Base automatically changed from chore/add-ai-assistant to develop May 21, 2026 09:23

chore(merge): merge develop into fix/883-htaccess-file-is-not

d7c1471

Miraeld added the Made by AI label May 22, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(settings): improve clarity of picture-tag method label and warning (#1015)#1056

fix(settings): improve clarity of picture-tag method label and warning (#1015)#1056
Miraeld wants to merge 27 commits into
developfrom
fix/1015-improve-clarity-picture-tag

Miraeld commented May 20, 2026 •

edited

Loading

Uh oh!

Miraeld commented May 20, 2026 •

edited

Loading

Uh oh!

codacy-production Bot commented May 20, 2026 •

edited

Loading

Uh oh!

Miraeld commented May 21, 2026

Uh oh!

remyperona commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Miraeld commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Detailed scenario

What was tested

How to test

Affected Features & Quality Assurance Scope

Technical description

Documentation

New dependencies

Risks

Mandatory Checklist

Code validation

Code style

Unticked items justification

Additional Checks

Uh oh!

Miraeld commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Report — fix(settings): improve clarity of picture-tag method label and warning (#1015)

Acceptance Criteria

Smoke Tests

Automated Tests Written

Screenshots

Uh oh!

codacy-production Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Up to standards ✅

Uh oh!

Miraeld commented May 21, 2026

Uh oh!

remyperona commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Miraeld commented May 20, 2026 •

edited

Loading

Miraeld commented May 20, 2026 •

edited

Loading

codacy-production Bot commented May 20, 2026 •

edited

Loading