venetian 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f695151d55003ebac29d7a3a8f07e9fefa0f0f89157f4968136c455227cd6db0
-  data.tar.gz: cc76fe2abb9785560bf07410ff248965aba79695f0fdb95ebeffc06903353cf9
+  metadata.gz: e4bcd5f9bdb03a39b5c9752fcc2461b061e013060c4953a135a983fdcbc7820e
+  data.tar.gz: 05ca5f3d601495cade8dc36fe8ebfcb7bfa6986f362c3414195d399d63767d8d
 SHA512:
-  metadata.gz: 63cc42e4330acc9b36da4096b31e922866437eaa174c4c9970dfdbf1ee35f23837cd0a4faa918e8dc9340f409c355a277b190ab7350e43a6ae31ad8ea84ee39b
-  data.tar.gz: 54095af7e65876ba7ce6804451de1618fa52eb1db6cad1fb46a7e27b9a901b7c8948ebda0c351671f6831c9f7f8609ab3172b854b377ddcfd9a92c2637fa5dae
+  metadata.gz: 68d3a6bc0602386f7e4d47ee0afa310a98585d4b0e9f2397e6c7f29dab158fc676cda63d3dba5f0a4babeffa8d067f7f1f0788538347068fd337eb4b76c0b2d0
+  data.tar.gz: 84016739b5897b01032a59d3b3403f45bd12b2db9b32c46ce5f87b109e53baa05ed95ef54a5938d3e2b0678e258a03c127f55bc33d68a1aa652e809633a4a1d9

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/lib/venetian/core.rb

@@ -2,6 +2,7 @@
 
 require "venetian/version"
 require "venetian/upstream"
+require "venetian/trust_store"
 require "venetian/executable"
 require "venetian/browser_installer"
 require "venetian/gemspec"

data/lib/venetian/executable.rb

@@ -9,14 +9,17 @@ module Venetian
   # Provides methods for locating the Playwright executable.
   module Executable
     class Executor # :nodoc:
+      include Open3
+      include TrustStore
+
       public :system, :exec
 
       def capture(*command, merge_stderr: true, **)
-        merge_stderr ? Open3.capture2e(*command, **) : Open3.capture2(*command, **)
+        merge_stderr ? capture2e(*command, **) : capture2(*command, **)
       end
 
       def run(*command, **)
-        Process.wait2(Process.spawn(*command, **)).last
+        Process.wait2(spawn(*command, **)).last
       end
     end
 
@@ -174,7 +177,21 @@ module Venetian
       end
     end
 
+    module Invocation # :nodoc:
+      def playwright_command(*args)
+        [*base_command, *args]
+      end
+
+      def cli_command?(command)
+        command == cli_command
+      rescue UnsupportedPlatformError, ExecutableNotFoundError, UnsupportedPathError
+        false
+      end
+    end
+
     extend Validations
+    extend Invocation
+    extend TrustStore::NodeCommand
 
     class << self
       # Returns the path to the Node executable. Raises an error if the executable cannot be found.
@@ -186,8 +203,10 @@ module Venetian
 
       # Executes the Playwright executable with the given arguments, replacing the current process.
       def execute(*args, echo: true, exception: true, **)
-        [*base_command, *args].then do |command|
+        playwright_command(*args).then do |command|
           puts command.shelljoin if echo
+          # Write out the command before Playwright's output, as exec would otherwise discard it
+          $stdout.flush
           # exec misbehaves on Windows (see equivalent in `tailwindcss-ruby`), so run Playwright and exit likewise
           exit executor.run(*command, **).exitstatus if Gem.win_platform?
 
@@ -199,7 +218,7 @@ module Venetian
 
       # Runs the Playwright executable with the given arguments.
       def system(*args, echo: true, exception: true, **)
-        [*base_command, *args].then do |command|
+        playwright_command(*args).then do |command|
           puts command.shelljoin if echo
           executor.system(*command, exception:, **(echo ? {} : { out: File::NULL, err: File::NULL }), **)
         end
@@ -207,7 +226,7 @@ module Venetian
 
       # Runs the Playwright executable with the given arguments, returning its combined output and status.
       def capture(*args, echo: true, **)
-        [*base_command, *args].then do |command|
+        playwright_command(*args).then do |command|
           puts command.shelljoin if echo
           executor.capture(*command, **).tap do |output, _|
             puts output if echo

data/lib/venetian/playwright.rb

@@ -4,6 +4,7 @@ require "playwright"
 
 require "venetian/core"
 require "venetian/connection_extensions"
+require "venetian/transport_extensions"
 
 module Venetian # :nodoc:
   # Starts Playwright using the bundled executable. Accepts the same arguments as +Playwright.create+,

data/lib/venetian/transport_extensions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Venetian
+  module TransportExtensions # :nodoc:
+    private
+
+    def run_driver_with_open3
+      return super unless Executable.cli_command?(@driver_executable_path)
+
+      # Windows doesn't accept the pgroup option
+      Open3.popen3(TrustStore.environment, *Executable.playwright_command("run-driver"),
+                   **({ pgroup: true } unless Gem.win_platform?).to_h)
+    end
+  end
+end
+
+Playwright::Transport.prepend(Venetian::TransportExtensions)

data/lib/venetian/trust_store.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Venetian
+  # # Trust Store
+  #
+  # Points the bundled Node at the certificate authorities Ruby's OpenSSL trusts.
+  module TrustStore
+    CERT_FILE_ENV_VAR = OpenSSL::X509::DEFAULT_CERT_FILE_ENV # :nodoc:
+    CERT_DIR_ENV_VAR = OpenSSL::X509::DEFAULT_CERT_DIR_ENV # :nodoc:
+    USE_OPENSSL_CA = "--use-openssl-ca" # :nodoc:
+    USE_BUNDLED_CA = "--use-bundled-ca" # :nodoc:
+    USE_SYSTEM_CA = "--use-system-ca" # :nodoc:
+    SYSTEM_CA_ENV_VAR = "NODE_USE_SYSTEM_CA" # :nodoc:
+    BUNDLED_CA_ENV_VAR = "VENETIAN_BUNDLED_CA" # :nodoc:
+
+    class << self
+      # Returns whether to run Node with the certificate authorities Ruby's OpenSSL trusts, which it does unless
+      # +VENETIAN_BUNDLED_CA+ is set or Node is told to use other certificate authorities, with +--use-bundled-ca+ or
+      # +--use-system-ca+ in +NODE_OPTIONS+ or with +NODE_USE_SYSTEM_CA=1+.
+      def enabled?
+        !ENV.key?(BUNDLED_CA_ENV_VAR) && !other_certificate_authorities?
+      end
+
+      # Returns the environment variables pointing Node at the certificates Ruby's OpenSSL trusts, if #enabled?.
+      def environment
+        return {} unless enabled?
+
+        { CERT_FILE_ENV_VAR => ENV.fetch(CERT_FILE_ENV_VAR, OpenSSL::X509::DEFAULT_CERT_FILE),
+          CERT_DIR_ENV_VAR => ENV.fetch(CERT_DIR_ENV_VAR, OpenSSL::X509::DEFAULT_CERT_DIR) }
+      end
+
+      # Returns the Node command with the given arguments, having Node use those certificates instead of its bundled
+      # ones if #enabled?.
+      def node_command(node, *)
+        [node, *(USE_OPENSSL_CA if enabled?), *]
+      end
+
+      private
+
+      def other_certificate_authorities?
+        ENV[SYSTEM_CA_ENV_VAR] == "1" || ENV.fetch("NODE_OPTIONS", "").split.intersect?([USE_BUNDLED_CA, USE_SYSTEM_CA])
+      end
+    end
+
+    module NodeCommand # :nodoc:
+      def playwright_command(...)
+        TrustStore.node_command(*super)
+      end
+    end
+
+    private
+
+    def system(*, **)
+      super(TrustStore.environment, *, **)
+    end
+
+    def exec(*, **)
+      super(TrustStore.environment, *, **)
+    end
+
+    def spawn(*, **)
+      super(TrustStore.environment, *, **)
+    end
+  end
+end

data/lib/venetian/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Venetian
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
   COMPATIBLE_PLAYWRIGHT_VERSION = "1.64.0"
   NODE_VERSION = "24.22.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: venetian
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Justin Malčić
@@ -46,6 +46,8 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
@@ -64,6 +66,8 @@ files:
 - lib/venetian/railtie.rb
 - lib/venetian/system_test_case_extension.rb
 - lib/venetian/tasks.rb
+- lib/venetian/transport_extensions.rb
+- lib/venetian/trust_store.rb
 - lib/venetian/upstream.rb
 - lib/venetian/version.rb
 homepage: https://github.com/jmalcic/venetian