venetian 0.3.1-x86_64-linux → 0.4.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04cf1a9d2cb860a3fee950970f7cb0529dbb1b946fd14e14eb0cbd7f12fcb70c
-  data.tar.gz: 177a863861a18743443274c31168e951874abf6fffe779ba3b862e8dd581e29f
+  metadata.gz: a85ccc842cc4cf0d2b050a237de2ff62f53f9de40b30d7520e0b5a14555882ba
+  data.tar.gz: f170084be2a272cd9d1c8b9a2b748c4d94a786f98c530990871b155526d33b9a
 SHA512:
-  metadata.gz: 2cee57c64e5e3c8f6190fec1338907378022cffffcad1da056489cc5024a49166f80fa3d3cdf1d40243ddf961c8b1c38d2582658f0ecc85d5a70c8be04aeb538
-  data.tar.gz: f260215cfd16a918d1a06996f84f838e2a159f447cb712e398987b3966ca4bbada1e6ff8cd359c49157e7f623a8b0a847b0d47c1d74030f2e0cf74a338868149
+  metadata.gz: 59f2926a61379fe12c79564b8317be45bbe43228aa9f60ce087856d454889645df7eebafad1e9ae62607e75e0d08ed89c4ce81a3eede0a5c483118119a7c16d4
+  data.tar.gz: 1175bc11bf21281dc3ad582b14ae361cb81dccbe637011dcdc6bccfb2546bdeab6a21d75ee5be1b24bcc376b9842e5a811bfefe6c67115f8cada84ab7f60a17f

data/AGENTS.md

@@ -0,0 +1,151 @@
+# AGENTS.md
+
+Guidance for coding agents working on Venetian. See `README.md` for what the gem does from a user's point of view.
+
+## What this is
+
+Venetian packages a Node.js binary and the `playwright-core` npm package in platform-specific gems, so
+`playwright-ruby-client` and `capybara-playwright-driver` work without a separate Node.js setup. It's the same
+packaging approach as Playwright for Python, Java and .NET, and as `tailwindcss-ruby`.
+
+The source gem (`ruby` platform) has no driver. The release tasks assemble a driver for each platform in
+`Venetian::Upstream::NATIVE_PLATFORMS` and build a `venetian-<platform>` gem from it.
+
+## Setup
+
+```bash
+bin/setup                 # bundle install
+bundle exec rake          # tests + RuboCop (the default task, what CI runs)
+bundle exec rake test     # tests only
+bundle exec rubocop       # lint only
+N=/pattern/ bundle exec rake test   # run tests matching a name
+```
+
+Ruby >= 3.3. CI runs Ruby 3.3, 3.4 and 4.0 on Linux, 3.3 and 4.0 on Windows, and Rails 7.1, 7.2 and 8.0 on Linux.
+To test against another Rails version, use a separate lockfile (gitignored):
+
+```bash
+BUNDLE_LOCKFILE=Gemfile.rails.lock RAILS_VERSION="~> 7.1.0" bundle exec rake test
+```
+
+The tests don't need a driver, browsers or network access. They stub the executable or use fixtures in `test/fixtures/`.
+`print_args.exe` there is built from `print_args.c` on Windows (`gcc -O2 -s -municode`, from `ridk exec`).
+
+When you run `bundle` locally, check that `Gemfile.lock` still has its `bundler (x.y.z) sha256=...` line under
+`CHECKSUMS`. Restore it before committing if it's gone.
+
+## Layout
+
+```
+lib/venetian.rb                          Full entry point: Capybara extensions + Railtie
+lib/venetian/playwright.rb               Capybara-free entry point (require: "venetian/playwright"), Venetian.start
+lib/venetian/core.rb                     Shared core: config accessors, Venetian.execute/system, Error
+lib/venetian/version.rb                  VERSION, COMPATIBLE_PLAYWRIGHT_VERSION, NODE_VERSION
+lib/venetian/upstream.rb                 NATIVE_PLATFORMS (gem platform => PlatformInfo), npm/nodejs.org URLs
+lib/venetian/executable.rb               Finds and validates the bundled node + package/cli.js, runs commands
+lib/venetian/browser_installer.rb        Browser and system-dependency installation, locking, writability checks
+lib/venetian/trust_store.rb              Environment pointing the bundled Node at Ruby's certificate authorities
+lib/venetian/playwright_create_extensions.rb   Prepended into Playwright's create: bundled CLI as default
+lib/venetian/browser_runner_extensions.rb      Prepended into Capybara::Playwright::BrowserRunner: auto-install
+lib/venetian/connection_extensions.rb       Prepended into Playwright::Connection: raises ForkedConnectionError after fork
+lib/venetian/transport_extensions.rb        Prepended into Playwright::Transport: runs the bundled driver with TrustStore
+lib/venetian/system_test_case_extension.rb     driven_by tracking, browser install before parallel forking
+lib/venetian/railtie.rb                  Loads the Rake task, installs SystemTestCaseExtension
+lib/venetian/gemspec.rb                  Venetian::GEMSPEC, the loaded spec for this gem
+lib/tasks/venetian.rake                  User-facing venetian:install[browser] task
+exe/playwright                           User-facing executable; exe/<platform>/ is generated and gitignored
+
+rakelib/release_task.rb                  Release tasks: playwright-core download, per-platform tasks
+rakelib/release_task/platform_task.rb    <platform>:build/install/release, Node.js download and assembly
+rakelib/upstream_task.rb                 update_keys and update_node tasks (run by scheduled workflows)
+rakelib/tasks/                           Shared task code: helpers, signatures, versioning, signed commits, PRs
+rakelib/tasks/keys/                      Pinned Node.js release keys (node.kbx) and npm registry keys (npm.json)
+
+test/test_helper.rb                      Requires everything and defines the test DSL
+test/venetian/                           Tests for lib/venetian/
+test/tasks/, test/upstream_task_test.rb  Tests for rakelib/
+```
+
+The assembled driver for each platform is `exe/<platform>/node` (`node.exe` on `x64-mingw-ucrt`) next to
+`exe/<platform>/package/`, with `package/cli.js` as the entry point. `Executable.base_command` depends on this
+layout, so keep it if you change the assembly. There's no wrapper script: `Executable.playwright_command`
+(through `TrustStore::NodeCommand`) adds the Node options Venetian runs the driver with between the two.
+
+## Releases and versions
+
+- `Venetian::COMPATIBLE_PLAYWRIGHT_VERSION` must match `Playwright::COMPATIBLE_PLAYWRIGHT_VERSION` from
+  `playwright-ruby-client`. When Dependabot bumps the client, `rake sync_version` (in the Pull Request workflow) bumps
+  the gem version, the Playwright version and the gemspec requirement, and commits through the GitHub API.
+- `Venetian::NODE_VERSION` is pinned. The Update Node workflow opens a PR for each new Node.js LTS release.
+- The Update Keys workflow opens a PR when the pinned signing keys in `rakelib/tasks/keys/` change. Downloads are
+  checked against signed checksums (Node.js `SHASUMS256.txt.asc`, npm registry signatures), so don't bypass them.
+- Releases happen on push to `main` when `rake release_source` says the current version isn't on RubyGems yet.
+  This requires CI and the Verify Build workflow (`rake install`, which builds and installs every platform gem) to pass.
+  To release, bump `VERSION` in `lib/venetian/version.rb`. Don't run `rake release` by hand.
+- `rakelib/`, `Rakefile`, `.github/`, `upstream.rb` and `gemspec.rb` are owned by the maintainer (`CODEOWNERS`).
+  Changes there need extra care: a broken release task means a broken release.
+
+## Code style
+
+- RuboCop with `rubocop-minitest` and `rubocop-rake`, new cops enabled, double-quoted strings. Fix offences instead of
+  disabling cops or adding exclusions. If a class gets too long, split it up.
+- `# frozen_string_literal: true` at the top of every Ruby file.
+- Use anonymous argument forwarding (`*`, `**`, `&`, `...`) where it fits, like the rest of the code.
+- Prefer `Pathname` (`join`, `dirname`, `mkpath`, `write`) to `File.join`/`File.expand_path` strings and `FileUtils`.
+  Call `.to_path` only where a String is needed, e.g. for ENV values or APIs that return Strings. The older rake code
+  still uses `File.join`; don't add more.
+- Doc comments are RDoc. Modules and classes start with a `# # Title` heading and a one-line description; background
+  on why they exist goes in the commit message. Public methods get a short comment saying what they return or do.
+- Don't comment methods marked `# :nodoc:` or private methods. Put the reasoning in the commit message. A short
+  inline comment on a genuinely non-obvious line is fine.
+- Mark internal classes and modules `# :nodoc:` (`# :nodoc: all` for rake task classes). Public methods that only the
+  gem itself calls are `# :nodoc:` too (e.g. `BrowserInstaller.browsers_path`), rather than documented API.
+- Read `ENV` where it's used rather than taking it as an argument so tests can pass a Hash. Tests set ENV and restore
+  it instead.
+- Extensions to other gems are `*Extensions` modules prepended at the bottom of their own file, not monkey patches.
+  The entry points (`lib/venetian.rb`, `lib/venetian/playwright.rb`) decide which ones load.
+- Debug output only appears when `VENETIAN_DEBUG` is set. Keep the gem quiet by default.
+
+## Tests
+
+- Minitest only. Every test file `require "test_helper"` and nothing else. Add new requires to `test/test_helper.rb`.
+- Classes subclass `Minitest::Test` and use the declarative DSL from `test_helper.rb`: `test "does something" do`,
+  `setup do`, `teardown do`. No `def test_*`, no `Minitest::Spec`/`describe`/`it`, and no custom base test class.
+- Split long test classes into nested concerns instead of disabling `Metrics` cops:
+
+  ```ruby
+  class ExecutableTest < Minitest::Test
+    module Running
+      module Tests
+        extend ActiveSupport::Concern
+
+        included do
+          test "..." do
+          end
+        end
+
+        private
+
+        # helpers for this topic
+      end
+    end
+
+    include Running::Tests
+  end
+  ```
+
+  Name concerns after the topic (`Running`, `Discovery`), not the class under test. Helpers only one concern uses go
+  in its `private` section; shared setup, teardown and stubbing helpers stay in the class.
+- `assert_raises` takes `match:` to check the exception message.
+- Restore any ENV you change in `teardown` or an `ensure`.
+- Tests must pass on Windows too: watch out for path separators, `node.exe`, and commands run through `cmd.exe`.
+
+## Commits and pull requests
+
+- Commit messages are a single imperative sentence describing the behaviour change, with no type prefix, e.g.
+  "Verify the Node.js and playwright-core downloads" or "Raise when gh can't say whether there's a pull request".
+  Put the reasoning in the body if it isn't obvious.
+- Commits are authored by the configured git user. Coding agents add only a `Co-Authored-By` trailer, with no other
+  trailers such as session links.
+- Work on a branch and open a PR against `main`. Don't push to `main` directly.
+- Workflows use least-privilege `permissions` and `persist-credentials: false` on checkout. Keep that for new ones.

data/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

data/README.md

@@ -130,6 +130,17 @@ $ playwright --version
 Version 1.61.1
 ```
 
+### Certificates
+
+The bundled Node has its own OpenSSL and certificate authorities, which can lag behind your system's, e.g. when a
+certificate authority is distrusted. So Venetian runs Node with `--use-openssl-ca`, pointing it at the certificate
+authorities Ruby's OpenSSL uses (`OpenSSL::X509::DEFAULT_CERT_FILE` and `DEFAULT_CERT_DIR`, or `SSL_CERT_FILE` and
+`SSL_CERT_DIR` if set). Playwright then trusts what e.g. `Net::HTTP` does, such as a corporate proxy's certificate
+authority installed on your system, and nothing more. To use Node's bundled certificate authorities instead, set
+`VENETIAN_BUNDLED_CA=1`. Venetian also leaves Node's certificate authorities alone if you've chosen them with
+`--use-bundled-ca` or `--use-system-ca` in `NODE_OPTIONS`, or with `NODE_USE_SYSTEM_CA=1`, as the bundled Node won't
+combine those with `--use-openssl-ca`. `NODE_EXTRA_CA_CERTS` works as usual either way.
+
 ### Getting more output
 
 Noisy output during a test run is often frustrating, so the gem is quiet by default. 

data/Rakefile

@@ -12,3 +12,4 @@ RuboCop::RakeTask.new
 task default: %i[test rubocop]
 
 import "rakelib/release.rake"
+import "rakelib/upstream.rake"

data/exe/x86_64-linux/node

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/exe/x86_64-linux/node
-size: 126595440 bytes
-sha256: 7fde7b8afa198da66257f42ee2001d874c7355631e6d1579a5fb5ef1f246df4c
+size: 126816376 bytes
+sha256: 67ca5783febb8bf85736c79fcdd92c8d6d465a0eb2a082672bcdfa76a506751c

data/exe/x86_64-linux/package/browsers.json

@@ -3,39 +3,39 @@
   "browsers": [
     {
       "name": "chromium",
-      "revision": "1243",
+      "revision": "1248",
       "installByDefault": true,
-      "browserVersion": "153.0.8010.12",
+      "browserVersion": "156.0.8078.4",
       "title": "Chrome for Testing"
     },
     {
       "name": "chromium-headless-shell",
-      "revision": "1243",
+      "revision": "1248",
       "installByDefault": true,
-      "browserVersion": "153.0.8010.12",
+      "browserVersion": "156.0.8078.4",
       "title": "Chrome Headless Shell"
     },
     {
       "name": "firefox",
-      "revision": "1543",
+      "revision": "1555",
       "installByDefault": true,
-      "browserVersion": "155.0",
+      "browserVersion": "157.0",
       "title": "Firefox"
     },
     {
       "name": "webkit",
-      "revision": "2359",
+      "revision": "2370",
       "installByDefault": true,
       "revisionOverrides": {
         "mac14": "2251",
         "mac14-arm64": "2251"
       },
-      "browserVersion": "26.6",
+      "browserVersion": "27.2",
       "title": "WebKit"
     },
     {
       "name": "ffmpeg",
-      "revision": "1011",
+      "revision": "1013",
       "installByDefault": true
     },
     {

data/exe/x86_64-linux/package/cli.js

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+require('./lib/bootstrap');
 const { libCli, libCliTestStub } = require('./lib/coreBundle');
 const { program } = require('./lib/utilsBundle');
 libCli.decorateProgram(program);

data/exe/x86_64-linux/package/lib/bootstrap.js

@@ -1,4 +1,26 @@
 "use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var bootstrap_exports = {};
+__export(bootstrap_exports, {
+  processExit: () => processExit
+});
+module.exports = __toCommonJS(bootstrap_exports);
 const minimumMajorNodeVersion = 20;
 const currentNodeVersion = process.versions.node;
 const major = +currentNodeVersion.split(".")[0];
@@ -10,6 +32,41 @@ Please update your version of Node.js.`
   );
   process.exit(1);
 }
+let stopProfiling = (callback) => callback();
+if (process.env.PW_PROFILE_DIR) {
+  const fs = require("fs");
+  const path = require("path");
+  const { Session } = require("inspector");
+  const profileDir = path.resolve(process.env.PW_PROFILE_DIR);
+  const script = process.argv[1] ? path.basename(process.argv[1], path.extname(process.argv[1])) : "node";
+  const command = /^[a-z][\w-]*$/i.test(process.argv[2] ?? "") ? process.argv[2] : void 0;
+  const profileName = [script, command, process.pid].filter(Boolean).join("-");
+  const session = new Session();
+  session.connect();
+  session.post("Profiler.enable");
+  session.post("Profiler.start");
+  stopProfiling = (callback) => {
+    stopProfiling = (callback2) => callback2();
+    session.post("Profiler.stop", (error, result) => {
+      try {
+        if (!error) {
+          fs.mkdirSync(profileDir, { recursive: true });
+          fs.writeFileSync(path.join(profileDir, profileName + ".cpuprofile"), JSON.stringify(result.profile));
+        }
+      } finally {
+        callback();
+      }
+    });
+  };
+  process.on("beforeExit", () => stopProfiling(() => {
+  }));
+}
+function processExit(code) {
+  stopProfiling(() => {
+    process.exit(code);
+  });
+  return void 0;
+}
 if (process.env.PW_INSTRUMENT_MODULES) {
   const Module = require("module");
   const originalLoad = Module._load;
@@ -86,3 +143,7 @@ if (process.env.PW_INSTRUMENT_MODULES) {
 ` + flatLines.join("\n") + "\n");
   });
 }
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  processExit
+});