Improve documentation for DEBUG variable

[Mathspy]

First let me start by thanking you for the lovely library and its truly stellar documentations ❤️ I did notice one tiny thing that could be improved in the latter though

DEBUG environmental variable has some extremely valuable logs (its logs are really good!) in situations where for example some resource hangs during page.goto and it'd be useful to find out what's hanging by using DEBUG=pw:protocol (or similar?) but as of right now only pw:api and pw:browser* are documented and even those aren't fully explained (What do each of them log and what do they not log?)

The only reason I stumbled upon pw:protocol are other issues with similar problems where it was recommended, i.e #3151

I still don't know the difference between pw:protocol, pw:protocol* (#3726 (comment)) and *protocol* (#5224 (comment)) and which one would fit my situation better which isn't that big of a problem as I can at least try each until I figure the problem out but I think it's something future users could benefit from

Thank you ❤️

[dgozman]

@Mathspy Thank you for your kind words!

pw:protocol and other variants (they are all equivalent) is intended to be internal - we do not expect Playwright users to understand these logs. However, it is possible to collect these logs and send to us, so that we can try to debug issues in Playwright itself.

For your usecase, where something in your page does not work as you'd expect, we'd like the debugging story to be much more user friendly and are working on that. From what I see here, you'd need something similar to Network Panel in browser Devloper Tools. Meanwhile, if you can reproduce the issue locally, you could launch with headless: false option, or even devtools: true for Chromium, and use the real Network Panel.

That said, there is always a room for improvement in our documentation. If you'd like to contribute a PR about pw:api or pw:browser*, here are documentation source files.

[Mathspy]

pw:protocol and other variants (they are all equivalent) is intended to be internal - we do not expect Playwright users to understand these logs. However, it is possible to collect these logs and send to us, so that we can try to debug issues in Playwright itself.

Gotcha!

Well in my case the bug was irreproducible locally; it was an img resource hanging indefinitely sporadically in CI environment. I was able to debug it with pw:protocol by reading the different requests and figuring out which one never got a response, then tried to confirm it by creating a dedicated debugging test and listening to page's request, response, and requestfinished.

And yeah after trying pw:protocol, I understand why documenting it wouldn't be very helpful, in my case ideally if a page's "domcontentloaded" fired but "load" didn't fire Playwright would include as part of the error log that "domcontentloaded" has already fired and which resource requests have not yet resolved.
I realise that's quite a bit of extra internal bookkeeping and so not the easiest thing to implement, so feel free to close this issue if there's nothing actionable!

[pavelfeldman]

I'll close this as a part of the bug triaging process. We have hundreds of bugs and feature requests with dozens and even hundreds of upvotes, while this one only has a few thumbs up. Please feel free to open a new bug and link this one if you'd like to see it addressed.