TLC Meeting - July 16, 2026

Meetings are happening weekly on Thursday at 0700 Pacific / 1000 Eastern / 1500 UK / 1930 India as a video call, and the invite is posted to the #selenium-tlc channel on Selenium Slack. To add items to the agenda for the next meeting, please see our public Rolling Agenda

Participation

Agenda

Meeting Summary

The TLC merged the Selenium 5 release charter and the BiDi implementation boundaries ADR, and closed the competing three API layers proposal. Most of the meeting was spent reviewing the network async/event API ADR point by point, covering handler references, URL pattern filtering, authentication handlers, observation versus interception, and handler disposition. Several points will be revised based on the discussion and reviewed again at a future meeting.

Decisions

  • The Selenium 5 release charter was merged. Everyone present had approved it, along with diemol, and no new concerns were raised. Handling of incomplete implementations was deferred to a later ADR.
  • The BiDi implementation boundaries ADR was merged. It establishes that the API is protocol neutral, that the low-level implementation is internal and officially unsupported while remaining publicly reachable, and that low-level access is by composition rather than off the driver.
  • The three API layers proposal was closed in favor of the merged boundaries ADR.
  • Everyone present preferred handler references in the network API to be objects rather than integer or string IDs, for extensibility. titusfortner will still seek input from the members who were not present.
  • URL pattern filtering belongs on the add handler methods rather than a separate mechanism, is optional, and must support the components the remote end recognizes. The accepted argument type is left to each binding.
  • The default disposition is to process other handlers; accumulated mutations are sent when no handler specifies a disposition.

Discussion Notes

Selenium 5 release charter

titusfortner confirmed that all comments on SeleniumHQ/selenium#17717 had been addressed, that everyone present had approved it, and that diemol had approved it as well. The contentious question of how incomplete implementations should be handled was moved out of the charter and will be addressed in a separate ADR. The charter was merged during the meeting.

The charter requires four ADRs. titusfortner noted that the existing ADRs were reworked to be more generic so they satisfy the charter’s requirements.

Closing the three API layers proposal

titusfortner recapped that SeleniumHQ/selenium#17709 proposed three API layers, but the boundaries between the layers were unclear. Under the approach the group discussed two weeks earlier, the raw protocol layer can be the generated modules directly, removing the need for a separate middle layer. AutomatedTester had commented that the PR could be closed in favor of the other work but had not closed it. pujagani agreed it was fine to close given the earlier agreement, and titusfortner closed it.

titusfortner noted that Python work on the low-level layer was intended to demonstrate that the generated code satisfies what the three-layer proposal needed, but that the generated code alone was not enough for AutomatedTester to evaluate without seeing it used in an implementation.

BiDi implementation boundaries ADR

The group had already gone through SeleniumHQ/selenium#17670 point by point two weeks earlier. titusfortner summarized the decisions: keep the API protocol neutral, treat the low-level implementation as internal and officially unsupported while keeping it publicly reachable, and provide low-level access by composition rather than off the driver. The ADR deliberately avoids marking the low-level layer beta, since that would imply support.

p0deje said the direction made sense based on what was presented and that he could still look through it. titusfortner framed the ADR as a flag planted to move forward that can be adjusted with new information. The ADR was merged, with a tracking issue to follow.

titusfortner raised a related idea of renaming the options convenience method from enabling BiDi to enabling sockets more generically, since webSocketUrl is a boolean on the client side and a string from the remote end. pujagani preferred handling that separately, as it concerns the options rather than the driver experience covered by this ADR.

Network async/event API ADR

titusfortner walked through SeleniumHQ/selenium#17685, which now carries eleven decisions after being reworked to fit the charter and to incorporate the earlier in-person discussion that started this work.

On handler references, the ADR now proposes returning an object instead of an ID. p0deje said it should always have been an object and recalled wanting to push for that originally, while adding that he did not have a strong argument for it. pujagani described hitting the limits of the ID approach while separating the Java implementation, since subscriptions return string IDs while Java had used a long, and agreed an object is more extensible. titusfortner did not recall why the earlier in-person discussion settled on IDs managed by the network class.

On URL patterns, titusfortner initially proposed a list of objects matching the components the remote end supports, because the specification does not currently support globs and a bare string would invite unexpected glob behavior. p0deje pushed back from a user perspective, saying users should be able to pass a URL or string rather than destructure it themselves, and noted that glob matching can still be handled client side until the remote end supports it. The group converged on accepting a string or a native URL object, with a list supported through splat arguments or overloads depending on the language, and left the remaining details to each binding.

On authentication, titusfortner leaned toward keeping add, remove, and clear handler methods with a callable and probably adding a convenience method for the common case that avoids lambdas. p0deje and pujagani noted the callable is needed because a handler may either supply credentials or cancel the authentication. titusfortner will make the convenience method more explicit in the next revision.

On observation versus interception, titusfortner preferred configuring both through the same add handler methods rather than separate methods, as Playwright does, while noting he had gone back and forth and did not feel strongly, and that Nikolai believes strongly they should be separate methods. p0deje pointed out that separate methods would let the callable receive a different object type, so that methods like failing a request are simply unavailable when only observing. titusfortner agreed the event object must differ and suggested the options argument would determine the type, with interception remaining the default. pujagani asked whether every variant would still return a handle for remove and clear, and titusfortner said there is no reason to treat removing and clearing differently for observation versus interception, which he offered as another argument against separate methods. p0deje did not have a strong opinion and was willing to go with the proposal; the point will be revised and reviewed next time.

On disposition, titusfortner described fail, respond, and submit, with the default being to fall through to other handlers. He noted that BiDi and Playwright both use continue, and that he chose submit because continue does not make clear whether processing continues through the remaining handlers or ends the chain. p0deje argued submit is a foot gun: a handler that calls it conditionally will silently stop other handlers from running, and preferred that handlers only mutate the request while the library aggregates mutations and resolves at the end. titusfortner countered that users need a way to override defaults set by a framework or library they do not control, giving the example of a library that filters out ads when one test needs to see an ad. p0deje did not push back further, preferring to ship sooner over perfecting the API. titusfortner leaned toward a name that signals more clearly that the chain ends; p0deje said submit is fine and that force submit sounds silly, suggesting something like finish or complete if a change is wanted.

The group also discussed last-in-first-out handler ordering, following Playwright, so that a local handler can override one added by a framework. titusfortner described an alternative proposed by Nikolai, in which handlers chain recursively and can act after the rest of the chain has been processed, as interesting but more trouble than it was worth, and something that could be added later.

Items not covered

titusfortner noted for the record that the script and logging ADR was not discussed and the Selenium Manager ADR details have not been worked through. The behavioral contract for the low-level BiDi layer was deferred as lower priority; it replaces an earlier gist, is more behavior focused, and jimevans is on board with it apart from one exception.

titusfortner also raised that outstanding ADRs from AutomatedTester need to be reconciled against the four ADRs the charter requires, and leaned toward settling what Selenium 5 needs before working through those details.

Action Items

Last modified July 16, 2026: Add TLC meeting minutes for July 16, 2026 (1427f4dfc43)