Introduce and expose query arguments for debugging AMP content generation

[westonruter]

There is currently a query that can be added to an AMP URL to facilitate debugging:

• amp_preserve_source_comments: This prevents source comments from being removed when performing an amp_validate request.

This isn't exposed anywhere in the UI to discover, and the developer just has to know it exists. Maybe this is fine, but there should be a Wiki page with debugging information to inform of its use. Alternatively, when WP_DEBUG is enabled there could be a link added to the AMP admin bar menu to link to it. (Update: UI to be addressed in a subsequent issue.)

But beyond amp_preserve_source_comments there is probably other flags that would be useful for debugging:

• Disable output buffering and short-circuit the sanitizers. This would facilitate inspection of the response from WordPress prior to the post-processors kicking in. This could be particularly helpful debugging embed handlers as well as figuring out where a fatal error may be happening.
• Disable response cache. This would be useful to help with performance debugging since there is a response cache to prevent post-processors from re-processing the same HTML repeatedly.
• Exclude sanitizers from being run. This could help with identifying which sanitizer is causing problems.
• Prevent redirection from AMP URL to non-AMP URL when there are unaccepted validation errors. The amp_validate param does this already, but it also has the behavior of adding validation error source comments, so having another param may be helpful.
• Automatically reject all validation errors on a given page.
• Others?

These debug parameters should only be made available when an appropriately-authorized user is authenticated.

[westonruter]

The amp_validate query param can also be used to preview what a site in classic mode will look like when theme support is enabled. The user must be an admin for this to be honored.

[kienstra]

Question About Working On This

Hi @westonruter,
Hope your week's off to a great start.

It looks like this is assigned to you. Could I work on it? Otherwise, no problem 😄

Thanks, Weston!

[westonruter]

@kienstra Yes, please go for it.

[kienstra]

Thanks, Weston!

[kienstra]

Question about a query arg

Hi @westonruter,
Happy friday!

Exclude sanitizers from being run. This could help with identifying which sanitizer is causing problems.

Should this exclude only a single sanitizer, like ?exclude_sanitizer=nav-menu-dropdown

Or would this somehow be different from the other query arg:

Disable output buffering and short-circuit the sanitizers. This would facilitate inspection of the response from WordPress prior to the post-processors kicking in. This could be particularly helpful debugging embed handlers as well as figuring out where a fatal error may be happening.

Thanks, Weston!

[westonruter]

Excluding all sanitizers would essentially be the same as short-circuiting the entire post-processor. I'm not sure of the value of providing a UI to disable individual sanitizers. I suggest revisiting that later.

[kienstra]

OK, thanks

[westonruter]

• One additional debug flag that would be helpful is to auto-accept all validation errors for excessive_css. Often times a site may look broken but the biggest issue is too much CSS. Being able to quickly just eliminate the 50KB limit can help narrow-down where to focus efforts. This is closely related to Discontinue excluding excessive CSS by default on Standard mode sites #2326. Auto-rejecting all validation errors would be a superset of this, but it goes too far.

[kienstra]

Yeah, that's a good idea. Excessive CSS errors can be tough on big sites.

[westonruter]

Something else that just came up which would be helpful for debugging: when adding the Countdown block from the Ultimate Blocks plugin, you will get two validation errors due to scripts being enqueued on the page. If you are in Transitional mode, it is easy to see what the expected behavior of the block is sine you can just look at the non-AMP version. If you are in Standard mode, you don't want to have to switch to Transitional. You also don't want to turn off AMP for the post/page in order to check it. The alternative then is to try marking the two validation errors as Rejected so that they scripts don't get sanitized and then click the Preview button. This allows the scripts to be included on the page, but the countdown timer then has broken styling because the styles were removed given that they weren't in the page at serve time. So to help identify that as being an issue, a debug flag would be helpful.

• Add debug flag to force AMP to be disabled for the current request. (This is different than the flag to short-circuit the post-processor, since in that case the embed handlers will be outputting AMP components.)
• Add debug flag to disable tree shaking (and allow all excessive_css, per above).

[kienstra]

@westonruter, sounds good. I'll add those to #3448.

[kienstra]

As this issue's PR is awaiting acceptance criteria, I'm moving this back to 'To Do.'

[westonruter]

One-off build to help with debugging support topic: amp.zip (v1.5.0-RC1-20200326T192429Z-d69f536dd)

Includes patch:

--- a/includes/class-amp-theme-support.php
+++ b/includes/class-amp-theme-support.php
@@ -1889,6 +1889,9 @@ class AMP_Theme_Support {
 	 * @return string Processed Response.
 	 */
 	public static function finish_output_buffering( $response ) {
+		if ( isset( $_GET['amp_bypass_post_processing'] ) ) {
+			return '<!-- amp:output_buffered -->' . $response . '<!-- /amp:output_buffered -->';
+		}
 		self::$is_output_buffering = false;
 		return self::prepare_response( $response );
 	}