Boost: Surface Error details for LCP Optimization #43647

LiamSarsfield · 2025-05-27T17:13:55Z

Note

Merge this PR after #43667 is merged.

Fixes HOG-53: Surface errors from LCP analysis in the UI

Proposed changes:

Updates the Optimize LCP module to include details on if certain pages failed LCP Analysis.

Other information:

Have you written new tests for your changes, if applicable?
Have you checked the E2E test CI results, and verified that your changes do not break them?
Have you tested your changes on WordPress.com, if applicable (if so, you'll see a generated comment below with a script to run)?

Jetpack product discussion

Does this pull request change what data or activity we track or use?

Testing instructions:

Prerequisites:

Ensure https://github.com/Automattic/boost-cloud/pull/685 is checked out within Boost Cloud
Latest trunk Jetpack Boost plugin installed and activated.
Latest Jetpack Boost Developer plugin installed and activated.
Your local Boost Cloud is connected to your local WP instance.
At least one Cornerstone Page set.
Boost Feature Flag enabled within the install (JETPACK_BOOST_ALPHA_FEATURES)
LCP Optimization feature enabled.

Happy Path

Within the Boost Developer, plugin (or otherwise), select an Image as the LCP.
Within Boost, click the Optimize button.
After Optimization, you should not see any issues reported within the UI regarding LCP Optimization.

HTTP Error

Use the below snippet to enforce a HTTP non 200 for LCP Analysis:

Force non-happy path

  	// Add hook to check for jb-disable-modules parameter on cornerstone pages
  	add_action(
  		'wp',
  		function () {
  			// Check if jb-disable-modules GET parameter is present
  		// phpcs:ignore WordPress.Security.NonceVerification.Recommended
  			if ( ! isset( $_GET['jb-disable-modules'] ) ) {
  				return;
  			}

  			// Both conditions are met, throw a 500 error and exit
  			status_header( 500 );
  			wp_die(
  				esc_html__( 'Internal Server Error: jb-disable-modules parameter detected on cornerstone page.', 'jetpack-boost' ),
  				esc_html__( 'Internal Server Error', 'jetpack-boost' ),
  				array( 'response' => 500 )
  			);
  		}
  	);

Within Boost, click the Optimize button.
After Optimization is complete, you should now see an informative info message showing how many pages could not be optimized. When clicking View details, you can see the precise reasoning on why the issue(s) occurred.
After Optimization, you should at least one issue being reported similarly to attached screenshot. You should see multiple issues reported with a similar error message if you have multiple Cornerstone pages.

…mization failures * Migrate LCP status display logic to a new Status component. * Add ErrorTooltip component to show detailed error messages for failed optimizations. * Update LCP state management to include error handling in the backend. * Introduce new SCSS styles for error tooltips and status display. * Ensure compatibility with existing LCP state management and API responses.

github-actions · 2025-05-27T17:15:00Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add a "[Type]" label (Bug, Enhancement, Janitorial, Task).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

Boost plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

LiamSarsfield · 2025-05-27T17:17:41Z

projects/plugins/boost/app/assets/src/js/features/lcp/status/error-tooltip.module.scss

+$black: #101517;
+$white: #fff;
+
+.jb-error-tooltip {


As we do not have many tooltips within the Boost Settings page, I took inspiration from the Boost Score Graph for the View Details tooltip.
https://github.com/Automattic/jetpack/blob/add/boost/lcp/error-messaging/projects/js-packages/components/components/boost-score-graph/tooltip.tsx#L8

Does the IconTooltip component from RNA work for your use case? If so, try to use that.

We have a storybook configured for all the RNA components.

Unfortuntely not precisely as the icon itself appears to be the anchor tag for that React component, where as I wanted the "View details" to be anchor point. I wanted to maintain the pattern of having an info icon to the left similarly to Critical CSS' Advanced Recommendations, but instead of the new page, it's just the tooltip.

To me, "View details" implies that the link will open a page. The following conveys the same message, but more clearly IMHO.

2 pages could not be optimized. ℹ

However, this is a design problem. So, cc @ederrengifo

I also think it would be more consistent to use the notice component. Perhaps use the "warning" level instead of "error" to avoid unwarranted panics.

I've created a couple of prototypes to see how these might show:

Option 1: Similar to the existing styling that we have for Critical CSS, except when clicking "View details" the tooltip appears.

Option 1 Screenshots

Tooltip has a black background on white text for consistency with the Historical Performance tooltip:

Option 2: Icon Tooltip that when clicked, shows the errors/details.

Option 2 Screenshots

Option 3: Notice component with Icon Tooltip that when clicked, shows the errors/details.

Option 3 Screenshots

Personally I like the notice component, it stands out a bit more on the page, as something that should be acted on.

That said, if we picked that we'd have to update the other notices to remain consistent.

Maybe for now we should remain consistent, and we can aim to update the design of all notices in a future PR?

I've created another option which I personally like which balances both consistency and using the Notice component.
We do use the Notice component for a different type of warning within Critical CSS ("Showstopper") So it wouldn't vary much compared to the existing styling we use already.

jp-launch-control · 2025-05-27T17:18:11Z

Code Coverage Summary

Coverage changed in 5 files.

File	Coverage	Δ%	Δ Uncovered
projects/plugins/boost/app/modules/optimizations/lcp/class-lcp-state.php	0/74 (0.00%)	0.00%	8 💔
projects/plugins/boost/app/rest-api/endpoints/class-update-lcp.php	0/30 (0.00%)	0.00%	8 💔
projects/plugins/boost/app/modules/optimizations/lcp/class-lcp.php	1/66 (1.52%)	-0.18%	7 💔
projects/plugins/boost/app/modules/optimizations/lcp/class-lcp-optimize-bg-image.php	0/98 (0.00%)	0.00%	5 💔
projects/plugins/boost/app/assets/src/js/features/lcp/lcp.tsx	0/10 (0.00%)	0.00%	-12 💚

2 files are newly checked for coverage.

File	Coverage
projects/plugins/boost/app/assets/src/js/features/lcp/status/error-details.tsx	0/16 (0.00%) 💔
projects/plugins/boost/app/assets/src/js/features/lcp/status/status.tsx	0/12 (0.00%) 💔

Full summary · PHP report · JS report

_{Coverage check overridden by

Coverage tests to be added later
Use to ignore the Code coverage requirement check when tests will be added in a follow-up PR
.}

* Add ErrorDetails and ErrorDetailsTooltip components for improved error display in LCP status. * Update status.module.scss to reflect changes in error handling structure.

…on checks * Introduce checks to determine if background images can be optimized before processing. * Refactor logic to skip elements that do not meet optimization criteria.

* Enhance the ErrorDetails component to include a summary wrapper for better layout. * Refactor SCSS styles for error tooltips and summary display, improving visual consistency. * Simplify the rendering logic in the Status component by directly integrating ErrorDetails.

* Integrate FoldingElement for better error message display in the ErrorDetails component. * Simplify error message rendering and enhance user interaction with expandable details. * Adjust SCSS styles for improved layout and visual consistency in error summaries.

…/jetpack into add/boost/lcp/error-messaging

haqadn

As I was mentioning during the call. I think this style is the way to go. My only concern is surfacing the internal errors publicly. Let's intercept the errors and show human readable versions of them instead. But, that's outside of the scope of this PR.

However, to effectively show the errors without exposing internal details we may have to change the schema of the errors in the LCP report to something like:

errors: <{
  type: 'url_validation'|'http_error'|'unknown_type', // Any anticipated types of the error that helps us classify.
  meta: ErrorMeta // It would have to adapt to the type. So, 'url_validation' would probably have the url as part of the ErrorMeta object.
}>[]

To be clear, I do not think the schema update needs to be a part of this PR.

haqadn · 2025-05-29T14:25:13Z

projects/plugins/boost/app/modules/optimizations/lcp/class-lcp-optimize-bg-image.php

 			if ( in_array( $lcp_data['element'], $selectors, true ) ) {
 				// If we already printed the styling for this element, skip it.
 				continue;
 			}
 			$selectors[] = $lcp_data['element'];

-			$lcp_optimizer = new LCP_Optimization_Util( $lcp_data );
-			$image_url     = $lcp_optimizer->get_image_to_preload();
+			$image_url = $lcp_optimizer->get_image_to_preload();


🏴 I have renamed this method in #43667

Thanks for the heads up. I've made this PR dependent on #43667 now

…ssaging

LiamSarsfield · 2025-05-29T15:22:03Z

As I was mentioning during the call. I think this style is the way to go. My only concern is surfacing the internal errors publicly. Let's intercept the errors and show human readable versions of them instead. But, that's outside of the scope of this PR.

Yep, I agree. I think communicating the errors, and suggesting potential fixes (dare I say recommendations) may be the way to go, but I have created HOG-53: Surface errors from LCP analysis in the UI to focus on this post Beta release.

… add/boost/lcp/error-messaging

…ssaging

haqadn

LGTM!

Please remember to update the error schema before release.

The base branch was changed.

LiamSarsfield added 2 commits May 27, 2025 18:12

Changelog

36a9e13

github-actions bot added [Boost Feature] Lcp [Plugin] Boost A feature to speed up the site and improve performance. [Status] In Progress labels May 27, 2025

github-actions bot added the [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. label May 27, 2025

LiamSarsfield commented May 27, 2025

View reviewed changes

LiamSarsfield and others added 9 commits May 27, 2025 18:39

Refactor LCP error handling: Introduce ErrorDetails component

d0c0af9

* Add ErrorDetails and ErrorDetailsTooltip components for improved error display in LCP status. * Update status.module.scss to reflect changes in error handling structure.

Enhance LCP background image optimization: Add conditional optimizati…

7521e68

…on checks * Introduce checks to determine if background images can be optimized before processing. * Refactor logic to skip elements that do not meet optimization criteria.

Use property instead of

4c28ed3

Rename lcp image URL method and make it reusable

6c69217

changelog

c7a8b10

Merge branch 'trunk' into add/boost/lcp/error-messaging

01a5ca3

Merge branch 'add/boost/lcp/error-messaging' of github.com:Automattic…

eb980e6

…/jetpack into add/boost/lcp/error-messaging

LiamSarsfield requested a review from a team May 29, 2025 12:21

LiamSarsfield marked this pull request as ready for review May 29, 2025 12:21

haqadn reviewed May 29, 2025

View reviewed changes

Merge branch 'update/lcp-bg-url-property' into add/boost/lcp/error-me…

aae21b4

…ssaging

LiamSarsfield changed the base branch from trunk to update/lcp-bg-url-property May 29, 2025 15:14

github-actions bot added [Feature] Contact Form [Package] Forms Actions GitHub actions used to automate some of the work around releases and repository management labels May 29, 2025

haqadn and others added 2 commits May 29, 2025 11:22

Use selector instead of element property

1c3e4ee

Merge remote-tracking branch 'origin/update/lcp-bg-url-property' into…

24993ff

… add/boost/lcp/error-messaging

LiamSarsfield requested a review from haqadn May 29, 2025 17:15

LiamSarsfield added 2 commits May 29, 2025 18:18

Merge branch 'trunk' into update/lcp-bg-url-property

f8964a6

Merge branch 'update/lcp-bg-url-property' into add/boost/lcp/error-me…

508eb38

…ssaging

haqadn previously approved these changes May 30, 2025

View reviewed changes

Base automatically changed from update/lcp-bg-url-property to trunk May 30, 2025 12:55

Merge branch 'trunk' into add/boost/lcp/error-messaging

1952e14

LiamSarsfield merged commit 3224cfd into trunk May 30, 2025
69 checks passed

LiamSarsfield deleted the add/boost/lcp/error-messaging branch May 30, 2025 13:34

github-actions bot removed the [Status] In Progress label May 30, 2025

LiamSarsfield mentioned this pull request May 30, 2025

Boost: Ensure LCP Errors are not partially hidden #43706

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Boost: Surface Error details for LCP Optimization #43647

Boost: Surface Error details for LCP Optimization #43647

Uh oh!

LiamSarsfield commented May 27, 2025 •

edited

Loading

Uh oh!

github-actions bot commented May 27, 2025 •

edited

Loading

Uh oh!

LiamSarsfield May 27, 2025

Uh oh!

haqadn May 27, 2025

Uh oh!

LiamSarsfield May 27, 2025

Uh oh!

haqadn May 27, 2025 •

edited

Loading

Uh oh!

LiamSarsfield May 28, 2025

Uh oh!

jeherve May 28, 2025

Uh oh!

LiamSarsfield May 29, 2025

Uh oh!

jp-launch-control bot commented May 27, 2025 •

edited

Loading

Uh oh!

haqadn left a comment •

edited

Loading

Uh oh!

haqadn May 29, 2025

Uh oh!

LiamSarsfield May 29, 2025

Uh oh!

LiamSarsfield commented May 29, 2025 •

edited

Loading

Uh oh!

haqadn left a comment

Uh oh!

Uh oh!

Uh oh!

Boost: Surface Error details for LCP Optimization #43647

Boost: Surface Error details for LCP Optimization #43647

Uh oh!

Conversation

LiamSarsfield commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes:

Other information:

Jetpack product discussion

Does this pull request change what data or activity we track or use?

Testing instructions:

Uh oh!

github-actions bot commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

haqadn May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jp-launch-control bot commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Summary

Uh oh!

haqadn left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LiamSarsfield commented May 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

haqadn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

LiamSarsfield commented May 27, 2025 •

edited

Loading

github-actions bot commented May 27, 2025 •

edited

Loading

haqadn May 27, 2025 •

edited

Loading

jp-launch-control bot commented May 27, 2025 •

edited

Loading

haqadn left a comment •

edited

Loading

LiamSarsfield commented May 29, 2025 •

edited

Loading