[Docs]: Python documentation starting point is confusing

[simonw]

Page(s)

https://playwright.dev/python/docs/intro is the page you get if you start on https://playwright.dev/python/ and click the "docs" link - but it's not actually documentation, it's documentation for pytest-playwright.

https://playwright.dev/python/docs/library is a better starting point.

Description

This came up in a comment on Hacker News: https://news.ycombinator.com/item?id=39442273#39443071

[simonw]

It looks to me like this was a deliberate decision from July 2022: dcb83d9#diff-c5c1ae09b26c6442c5d15f69902a771732c57a3ebdc153cec3ccb177d941ccd3 - presumably the goal was to better match the way the Node.js library is explained on https://playwright.dev/docs/intro

While I use and enjoy pytest-playwright, my mental model of Playwright Python is that it's the best available browser automation library, independently of using it to write Pytest tests.

The simplest way of addressing this would be to add a paragraph of text at the top of https://playwright.dev/python/docs/intro that specifically links to https://playwright.dev/python/docs/library as the place to learn about using Playwright Python outside of testing.

Currently that page has a mention of the library here:

Alternatively you can use the library to manually write the testing infrastructure with your preferred test-runner

But that's still giving the impression that Playwright is primarily a testing tool, as opposed to a general purpose browser automation tool.

[fireattack]

I agree. To me it's not even about what the tool is for, more about the flow of a doc/tutorial, and how intuitive it is.

For any lib, naturally (new) users want to learn about what the lib actually does before using it in the tests, even if that's the ultimate goal. Learning about how to use the tool in pytest before the tool itself sounds backwards.

[mxschmitt]

The simplest way of addressing this would be to add a paragraph of text at the top of https://playwright.dev/python/docs/intro that specifically links to https://playwright.dev/python/docs/library as the place to learn about using Playwright Python outside of testing.

This sounds good from our side, happy to accept a PR for that.

[simonw]

Opened a PR here:

• Clarify Pytest v.s. Library on Python intro page #29590

[mxschmitt]

Addressed by #29590. Thanks!