Taking debugging use cases into account in W3C specifications

[captainbrosset]

The W3C TAG ethical web principles include a section about the transparency of the web and how "we will always make sure it is possible to audit and inspect web applications".

I'm very thankful for this part of the design principles, and I think some W3C specifications took that at hearth and really went the extra mile in thinking about how a given piece of technology was going to be easy for people to debug.

One example is the Web Animations spec. Right from the starts, it lists use cases including an "Animation debugging" one. This use case was taken into account right from the start to make sure it would be just as easy to debug animations (when things go wrong) as to create them in the first place: "The Web Animations programming interface may be used to inspect running animations".

I love this for 2 reasons:

• A new piece of technology is much easier to adopt and use on the long run if it comes with a way to inspect and debug the result of using this technology.
• Requiring (or at least suggesting) UAs to expose some form of debugging information means that web authors are able to create debugging tools themselves. Debugging tools are currently something that mostly browser vendors do. They often require privileged access to the rendering engine of the browser to even exist, and are therefore impossible for web authors to create.

The web was built on View Source but has evolved past it. Being able to access and read the source code is immensely valuable for the web, but it doesn't tell you the full story. Complex CSS layout implementations in UAs tend to take a lot of decisions on behalf of web authors. Just reading the CSS code for a piece of layout won't be enough to solve a layout bug on a web page.

I would love for specification authors and editors to take debugging as a more important use case, more consistently and for specifications to include suggestions for how UAs should expose debugging information.

Flexbox is a good example of a CSS layout model that people sometimes have problems with and that could use tooling to be easier to adopt and use. With a few CSS properties, web authors define the sizing rules that flex items should be governed by, but that doesn't tell them what the final size of an item is going to be and why. Finding out the final size of an item can be done already by accessing the computed style of the element, or DOM APIs like getBoundingClientRect, but it won't tell you why that happened.

We built specialized tooling for this in Firefox which required us to access privileged data from the layout engine otherwise not accessible to web authors. The spec could suggest UAs to surface some of this data to web authors. In particular the flex layout algorithm could be defined in a more transparent way whereby each flex item gets augmented with data about its content size, its final size, the amount of space it grew or shrunk by, etc.

To be clear, I do not think W3C specs should define all of the many advanced ways a technology should be inspected or debugged. For starters, this isn't possible as time is required for people to adopt the technology, and for the right questions about it to surface. Only then can we know which tool to build that will make using it much easier. And I believe there will always be different developer tools out there, with varying degrees of debugging features for various technologies. Not everything will or should be standardized.

But that doesn't mean we shouldn't try to make technology at least a little bit easier to adopt at first by asking UAs to implement more than just the ability to view the code.

I think a lot of it could actually be more advanced warnings in browser consoles.

Thank you for taking the time to read this. Let me know your thoughts about this.

PS: this earlier conversation on twitter led me to post this issue here: https://twitter.com/patrickbrosset/status/1229798942226907136

[torgo]

In call today we discussed adding a principle on meaningful error messages. @cynthia volunteered on this one.

[alice]

Just linking directly to the minutes of the earlier discussion: https://github.com/w3ctag/meetings/blob/gh-pages/2020/telcons/07-06-minutes.md#taking-debugging-use-cases-into-account-in-w3c-specifications---torgo

[torgo]

We are just picking this up in our TAG call this week. The consensus is that it's a tricky issue. One possible approach might be:

In the context of API design, consider whether hooks implemented for testing and debugging purposes should be part of the standard - if they would help web developers debug their applications. Balance this against the need to not expose additional information (e.g. device-specific information) which could be used for fingerprinting.

[kenchris]

We sometimes add hooks for testing purposes (WPT) which could similarly be used for debugging, but it is a hard balance. Some functions calls might reset state, and invalidate state which might be very expensive and something we don't want to see broad developer adoption of (misuse), or it might reveal very privacy sensitive info, like say a sensors max frequency

[captainbrosset]

The privacy, performance and fingerprinting points are very good ones indeed. These would definitely need to be carefully balanced with the added debugging value. I guess that more often than not, authors will want to err on the side of safety.

I wanted to bring another use case also inspired by my previous work on devtools. A few years ago we introduced css grid debugging tools to Firefox, and to do this, we gave gecko the ability to surface useful debugging information about grids on the page. It came in the form of a WebIDL that's marked as chrome-only so that only privileged devtools code could use it: https://searchfox.org/mozilla-central/rev/4e290edc65023e16f5fe7d12f84d3b629433c7ab/dom/webidl/Element.webidl#322-342

The main API is element.getGridFragments(). If it returns a non-empty array, then that means the element does define a grid layout, and consumers of the API can then get all sorts of information like:

const fragment = element.getGridFragments()[0];
const row = fragment.rows.tracks[0];
const startPos = row.start;
const trackSize = row.breadth;
...

Without this information, we wouldn't be able to build grid tooling that works in all cases. We'd be left having to parse complex computed styles and re-doing a lot of what the engine already does.

My intuition is that such an API doesn't expose private information, or device-specific information. It does require an extra reflow from the engine though, but nothing more than what you'd do with JavaScript already when causing sync reflows with, say, element.offsetWidth.

This WebIDL could pretty easily be made available to web content, rather than just being chrome-only. And my belief is that would unlock a lot of ideas and innovation from web authors as they start using this for new tooling and use cases.