playwright-ruby-client 0.0.8 → 1.58.1.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04f50e523a846e243058cbb53a44e0f4a6ecce32aa843a02ace9b855b2264862
-  data.tar.gz: a8c99b7550206d0ff90ad033e0391a9224f780ae1e009a8cab48441070adabaa
+  metadata.gz: 78c64e38b462ad2449eda1349128c44ae6dbe7adae66570b76cd886e005f418f
+  data.tar.gz: d410ab0adf418bbf8f43925984a95663b7f947519b85e9afa93bec64daf76f06
 SHA512:
-  metadata.gz: d5e089555dc0d1ee2a86980d14d8310e338fa1d23b529a3d711895532dba64101300a198ed55b80f90342116b86baae8937c7526f992bc7ea9816297e385c436
-  data.tar.gz: d1da5e4e141043a37f3eccdd300865437264c795e343fa5652534d2fa04168d6f1326f7311c1f8c0212c98fd0d365b5b8f684b18b4b615b8825d5d65fa185562
+  metadata.gz: 319787778e82280859a291247e01b4fc5626b12974e9d7e08fd7331beb596696f15cc83c09d9b6f2cb5a76c15ef30308cc9e9eb7f2f16462188d08bc72546ddc
+  data.tar.gz: df5b988a9124a42006720bee860c3ebc91804ebc9ce396a922b0dbd0e1a1c81798912cd42530f91dcde49da83432b60be17cded55408548d7e795a7991b8276b

data/AGENTS.md

@@ -0,0 +1,4 @@
+# AGENTS.md
+
+When working in this repository, read `CLAUDE.md` first and follow its mandatory checks.  
+For detailed rules and workflows, refer to `CLAUDE/*.md`.

data/CLAUDE/api_generation.md

@@ -0,0 +1,28 @@
+# API Generation
+
+## Source of generated artifacts
+
+- Input: `development/api.json`
+- Generator script: `development/generate_api.rb`
+
+## Generated outputs
+
+- `lib/playwright_api/*.rb`
+- `documentation/docs/api/**/*.md`
+- `documentation/docs/include/api_coverage.md`
+- `sig/playwright.rbs`
+- `development/unimplemented_examples.md`
+
+## Critical rules
+
+- `lib/playwright_api/` is not tracked by Git (`lib/playwright_api/.gitignore` only).
+- Do not manually edit `lib/playwright_api/*.rb`.
+- Re-run `development/generate_api.rb` whenever API specs change.
+
+## Typical command set
+
+```sh
+rm lib/playwright_api/*.rb
+find documentation/docs -name "*.md" | grep -v documentation/docs/article/ | xargs rm
+bundle exec ruby development/generate_api.rb
+```

data/CLAUDE/ci_expectations.md

@@ -0,0 +1,23 @@
+# CI Expectations
+
+## Main guardrails
+
+`/.github/workflows/check.yml` detects stale generated artifacts.
+
+Checked paths:
+
+- `development/api.json`
+- `documentation/docs/**`
+- `development/unimplemented_examples.md`
+
+## Practical implication
+
+- If API-related code changes, regenerate artifacts before finishing.
+- If you open a PR without regeneration, `check.yml` will likely fail.
+
+## Related workflows
+
+- `/.github/workflows/rspec.yml`
+- `/.github/workflows/deploy.yml`
+
+These workflows also depend on `bundle exec ruby development/generate_api.rb`.

data/CLAUDE/gem_release_flow.md

@@ -0,0 +1,39 @@
+# Gem Release Flow
+
+## Overview
+
+Pushing a Git tag triggers `.github/workflows/deploy.yml`, which builds and publishes the gem to RubyGems.
+
+## Tag format
+
+The deploy workflow triggers on tags matching these patterns:
+
+- `X.Y.Z` — stable release (e.g. `1.58.0`)
+- `X.Y.betaN` — beta release (e.g. `1.58.beta1`)
+- `X.Y.Z.alphaN` — alpha release (e.g. `1.58.1.alpha1`)
+
+## Steps to release
+
+1. Update `lib/playwright/version.rb`:
+   - Set `Playwright::VERSION` to the target version string.
+   - `COMPATIBLE_PLAYWRIGHT_VERSION` stays at the base Playwright version.
+
+2. Commit the version change.
+
+3. Create and push a Git tag matching the version exactly:
+   ```sh
+   git tag 1.58.1.alpha1
+   git push origin 1.58.1.alpha1
+   ```
+
+4. The deploy workflow will:
+   - Check out the tagged commit.
+   - Verify `Playwright::VERSION == RELEASE_TAG` (must match exactly).
+   - Run `bundle exec ruby development/generate_api.rb` to generate API code.
+   - Run `rake build` to build the gem.
+   - Push the gem to RubyGems using the `RUBYGEMS_API_KEY` secret.
+
+## Important notes
+
+- The `Playwright::VERSION` in `lib/playwright/version.rb` **must exactly match** the Git tag name. If they differ, the deploy job fails at the version check step.
+- Alpha/beta tags do NOT require a separate branch — they can be tagged on any commit.

data/CLAUDE/past_upgrade_pr_patterns.md

@@ -0,0 +1,42 @@
+# Past Upgrade PR Patterns
+
+Common patterns observed from `Update Playwright driver to 1.xx.x` PRs reviewed with `gh`.
+
+## PR sample
+
+- `#366` (1.58.0)
+- `#360` (1.57.0)
+- `#354` (1.56.1)
+- `#348` (1.55.0)
+- `#341` (1.54.1)
+- `#336` (1.53.0)
+- `#331` (1.52.0)
+- `#327` (1.51.0)
+
+## Frequently changed files
+
+Almost every time:
+
+- `development/CLI_VERSION`
+- `development/api.json`
+- `lib/playwright/version.rb`
+
+High frequency:
+
+- `documentation/docs/api/*.md`
+- `documentation/docs/include/api_coverage.md`
+- `development/generate_api/example_codes.rb`
+- `spec/integration/example_spec.rb`
+- `lib/playwright/channel_owners/page.rb`
+- `lib/playwright/locator_impl.rb`
+
+Sometimes:
+
+- `development/generate_api.rb`
+- `development/unimplemented_examples.md`
+
+## Work style trend
+
+- The first commit often updates version files and generated API artifacts.
+- Follow-up commits often add/update specs and then implement `lib/playwright/**` changes.
+- Broader upstream changes usually increase docs/example/assets updates.

data/CLAUDE/playwright_upgrade_workflow.md

@@ -0,0 +1,35 @@
+# Playwright Upgrade Workflow
+
+## Scope
+
+Standard process for `Update Playwright driver to 1.xx.x` tasks.
+
+## Order (Do not reorder)
+
+1. Update versions
+- `development/CLI_VERSION`
+- `lib/playwright/version.rb` (`VERSION`, `COMPATIBLE_PLAYWRIGHT_VERSION`)
+
+2. Update API definition
+- Set `PLAYWRIGHT_CLI_EXECUTABLE_PATH`
+- `$PLAYWRIGHT_CLI_EXECUTABLE_PATH print-api-json | jq . > development/api.json`
+
+3. Clean before generation + regenerate
+- `rm lib/playwright_api/*.rb`
+- `find documentation/docs -name "*.md" | grep -v documentation/docs/article/ | xargs rm`
+- `bundle exec ruby development/generate_api.rb`
+
+4. Update tests first
+- Add/update `spec/` changes that represent upstream behavior differences.
+
+5. Implement
+- Apply minimal implementation changes in `lib/playwright/**`.
+
+6. Run tests
+- `bundle exec rspec`
+- Run focused specs first while iterating, then run the full suite.
+
+## Notes
+
+- During upgrade work, prefer the steps in `development/README.md`.
+- `development/update_playwright_driver.sh` can be used as a helper script.

data/CLAUDE/rspec_debugging.md

@@ -0,0 +1,30 @@
+# RSpec Debugging
+
+## Critical execution rule
+
+- Run RSpec via `rbenv exec`.
+- Some environments fail with plain `bundle exec rspec`, so always use `rbenv exec bundle exec rspec ...`.
+
+## Debug rule when spec fails
+
+- On failure, rerun with `DEBUG=1`.
+- Use `DEBUG=1` output to inspect Playwright protocol logs and isolate the issue.
+
+## Example
+
+```sh
+rbenv exec bundle exec rspec spec/integration/page/aria_snapshot_ai_spec.rb
+```
+
+```sh
+DEBUG=1 rbenv exec bundle exec rspec spec/integration/page/aria_snapshot_ai_spec.rb
+```
+
+## Node.js Playwright protocol log
+
+- Node.js Playwright protocol logs can be captured with `DEBUG=pw:*`.
+- This is useful when comparing behavior against the Ruby client.
+
+```sh
+DEBUG=pw:* node script.mjs 2>&1 | head -200
+```

data/CLAUDE/unimplemented_examples.md

@@ -0,0 +1,18 @@
+# unimplemented_examples.md
+
+## What it is
+
+- `development/unimplemented_examples.md` is a generated artifact.
+- It lists examples from API docs that could not be converted to Ruby examples.
+
+## How examples are converted
+
+- Source: API doc comments
+- Conversion rules: `development/generate_api/example_codes.rb`
+- Unmapped examples remain in Python in docs and are listed in `development/unimplemented_examples.md`.
+
+## When this file changes
+
+1. Review the diff to identify unmapped examples.
+2. Add conversion mappings to `development/generate_api/example_codes.rb` when needed.
+3. Re-run `bundle exec ruby development/generate_api.rb`.

data/CLAUDE.md

@@ -0,0 +1,32 @@
+# CLAUDE.md
+
+This file contains only the checks that must be verified first.  
+For detailed rules, see `CLAUDE/*.md`.
+
+## Must Check First
+
+1. Determine first whether the task is a Playwright version upgrade.
+2. Confirm generated-code handling.
+- `lib/playwright_api/*.rb` is auto-generated by `development/generate_api.rb`.
+- `lib/playwright_api/` is not tracked by Git. Do not edit generated files manually.
+3. Confirm change order.
+- For version upgrade work, update tests first, then implement `lib/playwright/**`.
+4. Confirm generation and diff consistency.
+- Update `development/api.json`, run generation, and verify generated diffs.
+5. Confirm CI-required generated files.
+- `development/api.json`
+- `documentation/docs/**`
+- `development/unimplemented_examples.md`
+6. Confirm RSpec execution mode (critical).
+- Run RSpec via `rbenv exec`.
+- On failure, rerun with `DEBUG=1` and inspect protocol logs.
+
+## Topic Docs
+
+- `CLAUDE/playwright_upgrade_workflow.md`
+- `CLAUDE/api_generation.md`
+- `CLAUDE/unimplemented_examples.md`
+- `CLAUDE/ci_expectations.md`
+- `CLAUDE/past_upgrade_pr_patterns.md`
+- `CLAUDE/rspec_debugging.md`
+- `CLAUDE/gem_release_flow.md`

data/CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# Contributing
+
+Thanks for your interest in contributing to `playwright-ruby-client`!
+
+For development setup instructions and guidelines, please see [development/README.md](development/README.md).

data/README.md

@@ -1,30 +1,36 @@
 [![Gem Version](https://badge.fury.io/rb/playwright-ruby-client.svg)](https://badge.fury.io/rb/playwright-ruby-client)
 
-# playwright-ruby-client
+# 🎭 Playwright client for Ruby
 
-A Ruby client for Playwright driver.
-
-Note: Currently, this Gem is just a PoC (Proof of Concept). If you want to develop browser-automation for Chrome with Ruby, consider using [puppeteer-ruby](https://github.com/YusukeIwaki/puppeteer-ruby). The list of the available APIs of playwright-ruby-client is [here](./docs/api_coverage.md)
+#### [Docs](https://playwright-ruby-client.vercel.app/docs/article/getting_started) | [API](https://playwright-ruby-client.vercel.app/docs/api/playwright)
 
 ## Getting Started
 
-At this point, playwright-ruby-client doesn't include the downloader of playwright driver, so **we have to install [playwright](https://github.com/microsoft/playwright) in advance**.
+```
+gem 'playwright-ruby-client'
+```
 
-```sh
+and then 'bundle install'.
+
+Since playwright-ruby-client doesn't include the playwright driver, **we have to install [playwright](https://github.com/microsoft/playwright) in advance**.
+
+```
 npm install playwright
 ./node_modules/.bin/playwright install
 ```
 
-and then, set `playwright_cli_executable_path: ./node_modules/.bin/playwright` at `Playwright.create`.
+And set `playwright_cli_executable_path: './node_modules/.bin/playwright'`
 
-Instead of npm install, you can also directly download playwright driver from playwright.azureedge.net/builds/. The URL can be easily detected from [here](https://github.com/microsoft/playwright-python/blob/79f6ce0a6a69c480573372706df84af5ef99c4a4/setup.py#L56-L61)
+**Prefer playwrighting without Node.js?**
+
+Instead of npm, you can also directly download playwright driver from playwright.azureedge.net/builds/. The URL can be easily detected from [here](https://github.com/microsoft/playwright-python/blob/cb5409934629adaabc0cff1891080de2052fa778/setup.py#L73-L77)
 
 ### Capture a site
 
 ```ruby
 require 'playwright'
 
-Playwright.create(playwright_cli_executable_path: '/path/to/playwright') do |playwright|
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright') do |playwright|
   playwright.chromium.launch(headless: false) do |browser|
     page = browser.new_page
     page.goto('https://github.com/YusukeIwaki')
@@ -45,18 +51,24 @@ Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwrigh
     page = browser.new_page
     page.goto('https://github.com/')
 
-    form = page.query_selector("form.js-site-search-form")
-    search_input = form.query_selector("input.header-search-input")
-    search_input.click
+    page.get_by_placeholder("Search or jump to...").click
+    page.locator('input[name="query-builder-test"]').click
+
+    expect(page.keyboard).to be_a(::Playwright::Keyboard)
+
     page.keyboard.type("playwright")
     page.expect_navigation {
       page.keyboard.press("Enter")
     }
 
-    list = page.query_selector("ul.repo-list")
-    items = list.query_selector_all("div.f4")
-    items.each do |item|
-      title = item.eval_on_selector("a", "a => a.innerText")
+    list = page.get_by_test_id('results-list').locator('.search-title')
+
+    # wait for item to appear
+    list.first.wait_for
+
+    # list them
+    list.locator('.search-title').all.each do |item|
+      title = item.text_content
       puts("==> #{title}")
     end
   end
@@ -147,6 +159,38 @@ end
 
 ```
 
+### Communicate with Playwright server
+
+If your environment doesn't accept installing browser or creating browser process, consider separating Ruby client and Playwright server.
+
+![structure](https://user-images.githubusercontent.com/11763113/124934448-ad4d0700-e03f-11eb-942e-b9f3282bb703.png)
+
+For launching Playwright server, just execute:
+
+```
+npx playwright install && npx playwright run-server --port 8080 --path /ws
+```
+
+and we can connect to the server with the code like this:
+
+```ruby
+Playwright.connect_to_playwright_server('ws://127.0.0.1:8080/ws?browser=chromium') do |playwright|
+  playwright.chromium.launch do |browser|
+    page = browser.new_page
+    page.goto('https://github.com/YusukeIwaki')
+    page.screenshot(path: './YusukeIwaki.png')
+  end
+end
+```
+
+When `Playwright.connect_to_playwright_server` is used, playwright_cli_executable_path is not required.
+
+For more detailed instraction, refer this article: https://playwright-ruby-client.vercel.app/docs/article/guides/playwright_on_alpine_linux
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contributing guidelines.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/documentation/README.md

@@ -0,0 +1,33 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```console
+yarn install
+```
+
+## Local Development
+
+```console
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```console
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+```console
+GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

data/documentation/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

data/documentation/docs/api/api_request.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 10
+---
+
+# APIRequest
+
+Not Implemented