[Feature] Guide on how to build binding for other languages

[d4h0]

It would be great, if there was a guide that explains how to build bindings for other languages. As far as I can see, there isn't such a guide, currently.

It seems the only way to figure out how to do it, is to look at how other bindings are created (which is pretty painful because these bindings are not created to show others how to do it, they basically have no comments/instructions).

It also adds the requirements, that someone knows one of these other languages, which makes it even more difficult for some people to create language bindings (for example, I don't know Python, Java, .Net, Go, or Crystal).

Is there any chance someone with the required knowledge could write such a guide?

[mxschmitt]

In what language are you interested in?

Usually we recommend taking a look at the client part of our JS client, which is our best documentation so far: https://github.com/microsoft/playwright/tree/master/packages/playwright-core/src/client

This contains some generated parts for our communication in between (channels) so for them it might be better to take a look at the Python port to see how it was done there without these generated channels: https://github.com/microsoft/playwright-python/tree/master/playwright/_impl

Usually mirroring it from one language into another language is not that of a big deal since each of these languages which you've listed do basically the same.

In a TL;DR how a language binding works would be: It launches the driver as a sub-process and sends over that JSON payloads to represent the Playwright objects. For each action e.g. goto it sends then e.g. a Page.goto message over the stdin/stdout (we call it protocol) and waits for it's response asynchronously to resolve the method and represent the response data.

If you want to chat about it, feel free to join our Slack: https://aka.ms/playwright-slack and there the #contributors channel.

[d4h0]

Thanks for your quick response, @mxschmitt!

In what language are you interested in?

I'm interested in using Playwright with Rust. Ideally, I'd contribute to the existing Rust binding (which wasn't updated for a few months), but even with some instructions by the creator I'm struggling (because some stuff seems to have changed).

My thinking was, that a guide would help me understand how to update the Rust client (or how to build my own binding, if there are too many problems).

The main roadblock so far was that I need to generate 'api.json' via playwright print-api-json.

However, this fails with:

$ npx playwright print-api-json
node:internal/modules/cjs/loader:936
  throw err;
  ^

Error: Cannot find module '../../api.json'

...probably because api.json isn't bundled anymore (the undocumented 'print-api-json' command-line-option wasn't removed, btw).

I think official documentation would help to prevent to break things that are used by community-language-bindings (e.g. by defining what can be used safely). And even if there are breaking changes (which of course happen), then official documentation makes it possible to communicate these breaking changes to developers (e.g. via a changelog.txt).

In the end, I figured out that I can clone this repo and run node utils/doclint/generateApiJson.js to generate 'api.json'.

...but I don't know if this version is even compatible with the Python-binding (from which I need to derive/port other code/techniques)...

Overall my experience was quite frustrating so far, to be honest. And I'm pretty sure, it will continue to be this way because a language-binding-generator basically can break at any moment, because there isn't any official "contract" in regard to how things are done, or how breaking changes are communicated.

I believe some form of official documentation would be a great addition to this project, and would help build a Playwright community in ecosystems that are not officially supported.

In the above issue in the playwright-rust repo, the author wrote:

playwright is 1.15.2, but this crate is based on 1.11.0-1620331022000. I had to stop because there was a test that broke when I upgraded the version.

I'm not 100% sure if I understand this correctly, but I believe this means, that something in the build-process broke, and the author wasn't willing to spend the time to figure out what it was or how to fix it.

[pavelfeldman]

Supporting language port is a serious committment, it implies deep understanding of Playwright, not just the binding contracts. If some organization champions the port, confirms full-time staff for it and long-term intentions, we are happy to work with them on the ongoing basis.

Otherwise port authors are on their own - helping them is too much load on our side and keeping entry barrier where it is helps us containing the ports that are created and abandoned.

[d4h0]

It is too bad to hear this, but thanks for your honest feedback.

keeping entry barrier where it is helps us containing the ports that are created and abandoned.

Besides preventing ports from being started, I'm pretty sure this is also a reason why projects that got started get abandoned.

[pavelfeldman]

Besides preventing ports from being started, I'm pretty sure this is also a reason why projects that got started get abandoned.

Yes, somehow perceived complexity of Playwright port is lower than it should be. Not too many people get into writing their own OS, yet some are trying to start a Playwright port :).