Add additional e2e debugging option

[ajlende]

Description

Getting node debugging working for e2e tests in #21631 was a bit more involved than just add the --inspect-brk flag to wp-scripts --inspect-brk test-e2e, so I'm moving the additional code and documentation changes to a new pull request.

• Add PUPPETEER_DEVTOOLS environment (default false) to enable the devtools launch option.
• Add --puppeteer-devtools option to test-e2e to automatically open the devtools.
• Add test-e2e:debug npm script with --inspect-brk (from wp-scripts test-unit-js node debugging #21631) and --puppeteer-devtools.
• Add documentation for how to debug e2e tests

How has this been tested?

• Run test-e2e:debug with breakpoints set in:
  • test context (add debugger; within a test)
  • evaluate context (add await page.evaluate( () => { debugger; } ); within a test)
  • window context (add debugger; within any front-end code that would be run)

Types of changes

New feature

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.
• I've updated all React Native files affected by any refactorings/renamings in this PR.

[gziolo]

I'm about to merge #21653

Add documentation for how to debug e2e tests

I think that it largely overlaps with unit tests so maybe we just move the existing section to the shared Advanced information section and reference it from both commands. What do you think?

[ajlende]

@gziolo I like the idea! I figured the docs should also include some info about node options so I added that section and put it under there instead. Do you think that makes sense as a place to put it? The Advanced information section wasn't shared between them (and having multiple headers named the same makes that a little confusing and impossible to link to).

[gziolo]

I figured the docs should also include some info about node options so I added that section and put it under there instead.

Awesome, super helpful 🤩 Should it be moved before the list of scripts maybe or is it too advanced use case?

Do you think that makes sense as a place to put it?

Now we have two advanced sections, but only the second is linked. So maybe we consolidate it as one?

I plan to test it tomorrow and land

[ajlende]

Should it be moved before the list of scripts maybe or is it too advanced use case?

As a reader of the documentation I'm probably more likely to be looking for which scripts are available rather than seeing how to pass Node.js options to a script, so it makes sense to not put too much before the "available scripts" section.

Now we have two advanced sections, but only the second is linked. So maybe we consolidate it as one?

Now that you mention it, the word 'advanced' is probably a little overused in this document. Debugging unit tests shouldn't be considered "advanced"—it should be a technique that everyone feels comfortable using.

I think "Passing Node.js options" may be a little more clear. All the other options aside from --inspect would probably be considered advanced options, but the second "Advanced Usage" section refers strictly to overriding default configuration which is why I didn't put it under that header.

I plan to test it tomorrow and land

❤️

[gziolo]

I like all the revisions applied since I last viewed 💯

[gziolo]

great idea to cross-link here 👍

[gziolo]

It works like a charm. I love it. This is how it looks in action. Well, I need to convert screen recording into GIF ...

Update: it looks like GIF is too big so I used Twitter:
https://video.twimg.com/ext_tw_video/1254999864280264704/pu/pl/aULuGCn7NkSB654x.m3u8