venetian 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 141b4bbd544a72e7eae92778a543138e941c4d358f56861df49215470980cbb4
-  data.tar.gz: 218e2c4c4443944bd93b793f6c12a2a6d2c58f74205e2e0d66246bee2d7a6e0a
+  metadata.gz: 0c599b422e667a871ef1b770d925eba77b670865bc3e93d453467f8868158a96
+  data.tar.gz: 10c75b357f976409bc73a3e7cb478e00f5f5bb34e2fdbcb02917ca88e96599e7
 SHA512:
-  metadata.gz: 0f6904d17f6b9c4e807e66b7e95e4d326787c2daadd382d5f2d162103ff2f626ecc40a7f2fb80e1b7bddd5c531ebaaff218b147ff7e4d21aa60d80f0a33bb576
-  data.tar.gz: 1d67aef3da52d1cb6a730586a13171a3d48b6fed5799a644a5abf6eae8b4c3bf09e5cd523c4efc00db605fc7e38413cd67929ce8a122bdfa30eb0b6ff9856dd2
+  metadata.gz: 78a685bc7a929fd1305905e727912787162f85f88d05983e4c1649d06a8a3055e37b9ba6bb979ca5ef3d15be2619b1ff93e46394849154d079081c5b7a10adfb
+  data.tar.gz: 26e00d4ce95a2f03f5f816272788d917d092d78aae6de9423acb488021d74e9e9cfd19323e85d6e1c3644a23269de12b2357f9d935d39f0fc238f28eea17ecab

data/README.md

@@ -38,9 +38,37 @@ Capybara.register_driver :playwright do |app|
 end
 ```
 
+### Using `playwright-ruby-client` without Capybara
+
+Require the Capybara-free entry point instead, either in your Gemfile if you use `Bundler.require`:
+
+```ruby
+gem "venetian", require: "venetian/playwright"
+```
+
+Or directly:
+
+```ruby
+require "venetian/playwright"
+```
+
+Then use `Venetian.start` in place of `Playwright.create`. It takes the same arguments, with the bundled executable as the default
+`:playwright_cli_executable_path`. Browsers aren't installed automatically here, so install them first, either with
+the [Rake task](#installing-browsers-manually) or `Venetian::BrowserInstaller.install`:
+
+```ruby
+Venetian::BrowserInstaller.install(:chromium)
+
+Venetian.start do |playwright|
+  playwright.chromium.launch do |browser|
+    # ...
+  end
+end
+```
+
 ### Automatic browser and dependency installation
 
-The gem will automatically install a browser and dependencies for you before attempting to use it.
+With Capybara or Rails system tests, the gem will automatically install a browser and dependencies for you before attempting to use it.
 Browsers are installed to `$XDG_CACHE_HOME/ms-playwright` on Linux, `~/Library/Caches/ms-playwright` on macOS, 
 and `%LOCALAPPDATA%\ms-playwright` on Windows. In CI, you will want to 
 [cache this directory](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching) 
@@ -57,10 +85,15 @@ When parallelizing tests, there's also the issue of multiple processes all tryin
 if you use Rails system tests with `ActionDispatch::SystemTestCase`,
 this is handled automatically by installing all required browsers before disabling auto-installation and then forking.
 
+Browsers aren't installed automatically if you pass your own `:playwright_cli_executable_path`, or connect to a server with
+`:playwright_server_endpoint_url` or `:browser_server_endpoint_url`, since the bundled executable won't be the one running them.
+You can also turn installation off with `Venetian.auto_install_browsers = false`, or just dependency installation with
+`Venetian.auto_install_dependencies = false`.
+
 ### Installing browsers manually
 
 If you can't rely on automatic installation, you can use the included Rake task to install browsers.
-With Rails this is included automatically when the gem is required.
+With Rails this is included automatically when `venetian` is required (but not `venetian/playwright`).
 
 ```bash
 $ RAILS_ENV=test rails venetian:install

data/exe/playwright

@@ -1,7 +1,7 @@
 #! /usr/bin/env ruby
 # frozen_string_literal: true
 
-require "venetian"
+require "venetian/core"
 
 begin
   Venetian.execute(*ARGV, echo: ENV.fetch("VENETIAN_DEBUG", nil))

data/lib/tasks/venetian.rake

@@ -5,7 +5,7 @@ namespace :venetian do
     Install Playwright browsers. Pass a name to install a specific browser (e.g. venetian:install[chromium]), else installs default browsers.
   USAGE
   task :install, [:browser] do |_task, args|
-    require "venetian"
+    require "venetian/core"
     Venetian::BrowserInstaller.install(args[:browser])
   end
 end

data/lib/venetian/browser_installer.rb

@@ -8,12 +8,22 @@ module Venetian
     class << self
       private
 
-      def install_dependencies?
-        Venetian.auto_install_dependencies && dependencies_supported?
+      def install_dependencies?(browser = nil, force: nil)
+        return force unless force.nil?
+
+        Venetian.auto_install_dependencies && dependencies_to_install?(browser)
+      end
+
+      def install_dry_run(browser = nil)
+        Executable.capture("install-deps", *browser&.to_s, "--dry-run", echo: debug?)
+      end
+
+      def dependencies_to_install
+        @dependencies_to_install ||= {}
       end
 
-      def install_dry_run
-        Venetian.system "install-deps", "--dry-run", exception: false, echo: ENV.fetch("VENETIAN_DEBUG", nil)
+      def debug?
+        ENV.fetch("VENETIAN_DEBUG", nil)
       end
     end
 
@@ -29,18 +39,39 @@ module Venetian
     end
 
     # Installs a browser. Raises InstallError if installation fails.
-    def self.install(browser = nil, install_dependencies: install_dependencies?)
-      Venetian.system "install", *browser&.to_s, *("--with-deps" if install_dependencies),
-                      exception: true, echo: ENV.fetch("VENETIAN_DEBUG", nil)
+    def self.install(browser = nil, install_dependencies: nil)
+      Venetian.system "install", *browser&.to_s,
+                      *("--with-deps" if install_dependencies?(browser, force: install_dependencies)),
+                      exception: true, echo: debug?
     rescue StandardError => e
       raise InstallError, e.message
     end
 
-    # Returns true if the current OS supports Playwright's dependency installer.
-    def self.dependencies_supported?(force: false)
-      return @dependencies_supported unless @dependencies_supported.nil? || force
+    # Output from a dry run where Playwright couldn't spawn its package manager, so has no way to install dependencies.
+    NO_PACKAGE_MANAGER_OUTPUT = "ENOENT" # :nodoc:
+
+    # Returns true if Playwright's dependency installer has something to install on the current OS for a browser,
+    # or for the default browsers if none given.
+    #
+    # On Linux, the dry run simulates the install with the package manager, exiting non-zero if packages are missing or
+    # if it can't simulate (e.g. no package lists yet, which the installer fixes by updating them first), unless there's
+    # no package manager it can use. On Windows, the dry run only prints the command it would run, so there is always
+    # something to install.
+    def self.dependencies_to_install?(browser = nil, force: false)
+      return true if Gem.win_platform?
+
+      dependencies_to_install.delete(browser&.to_s) if force
+      dependencies_to_install.fetch(browser&.to_s) do |key|
+        dependencies_to_install[key] = install_dry_run(browser).then do |output, status|
+          !status.success? && !output.include?(NO_PACKAGE_MANAGER_OUTPUT)
+        end
+      end
+    end
 
-      @dependencies_supported = install_dry_run || false
+    def self.dependencies_supported?(...) # :nodoc:
+      warn "Venetian::BrowserInstaller.dependencies_supported? is deprecated; use dependencies_to_install? instead.",
+           category: :deprecated, uplevel: 1
+      dependencies_to_install?(...)
     end
   end
 end

data/lib/venetian/browser_runner_extensions.rb

@@ -2,13 +2,20 @@
 
 module Venetian
   module BrowserRunnerExtensions # :nodoc:
+    ALTERNATIVE_DRIVER_OPTIONS = %i[playwright_cli_executable_path playwright_server_endpoint_url
+                                    browser_server_endpoint_url].freeze
+
+    def self.browser_to_preinstall_from(options)
+      (options[:browser_type] || :chromium).to_sym if options.values_at(*ALTERNATIVE_DRIVER_OPTIONS).none?
+    end
+
     def initialize(options = {}, *args)
-      @venetian_browser_type = options[:browser_type] || :chromium
+      @venetian_browser = BrowserRunnerExtensions.browser_to_preinstall_from(options) if Venetian.auto_install_browsers
       super
     end
 
     def start
-      BrowserInstaller.install(@venetian_browser_type) if Venetian.auto_install_browsers
+      BrowserInstaller.install(@venetian_browser) if @venetian_browser
       super
     end
   end

data/lib/venetian/core.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "venetian/version"
+require "venetian/upstream"
+require "venetian/executable"
+require "venetian/browser_installer"
+require "venetian/gemspec"
+
+module Venetian # :nodoc:
+  class << self
+    attr_accessor :auto_install_dependencies
+  end
+
+  class Error < StandardError; end
+
+  self.auto_install_dependencies = true
+
+  def self.execute(*, echo: true, **)
+    Executable.execute(*, echo: echo, **)
+  end
+
+  def self.system(*, echo: true, **)
+    Executable.system(*, echo: echo, **)
+  end
+end

data/lib/venetian/executable.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "open3"
+require "shellwords"
+
 module Venetian
   # # \Executable
   #
@@ -7,6 +10,10 @@ module Venetian
   module Executable
     class Executor # :nodoc:
       public :system, :exec
+
+      def capture(*command)
+        Open3.capture2e(*command)
+      end
     end
 
     DEFAULT_DIR = File.expand_path(File.join(__dir__, "..", "..", "exe")) # :nodoc:
@@ -109,11 +116,31 @@ module Venetian
         end
       end
 
+      # 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|
+          puts command.shelljoin if echo
+          executor.capture(*command).tap do |output, _|
+            puts output if echo
+          end
+        end
+      end
+
       # Returns the base command to execute Playwright.
       def base_command
         [path, File.join(File.dirname(path), "package", "cli.js")]
       end
 
+      # Returns the base command as a single string, as expected by +:playwright_cli_executable_path+.
+      def cli_command
+        if Gem.win_platform?
+          base_command.collect { |arg| %("#{arg}") }
+                      .join(" ")
+        else
+          base_command.shelljoin
+        end
+      end
+
       private
 
       def ensure_exe_dir_exists!

data/lib/venetian/gemspec.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "pathname"
+
 module Venetian
   GEMSPEC = Gem.loaded_specs.values.reverse.find do |spec|
     spec.gem_dir == Pathname.new(__dir__).join("..", "..").expand_path.to_path

data/lib/venetian/playwright.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "playwright"
+
+require "venetian/core"
+
+module Venetian # :nodoc:
+  # Starts Playwright using the bundled executable. Accepts the same arguments as +Playwright.create+,
+  # so +:playwright_cli_executable_path+ can still be overridden.
+  def self.start(**options, &)
+    options[:playwright_cli_executable_path] ||= Executable.cli_command
+    Playwright.create(**options, &)
+  end
+end

data/lib/venetian/playwright_create_extensions.rb

@@ -3,7 +3,10 @@
 module Venetian
   module PlaywrightCreateExtensions # :nodoc:
     def initialize(options = {}, *)
-      super({ playwright_cli_executable_path: Executable.base_command.shelljoin }.merge(options), *)
+      unless options[:playwright_cli_executable_path]
+        options = options.merge(playwright_cli_executable_path: Executable.cli_command)
+      end
+      super
     end
   end
 end

data/lib/venetian/system_test_case_extension.rb

@@ -16,7 +16,9 @@ module Venetian
       def driven_by(driver, options: {}, **)
         super
 
-        self.venetian_browser_type = driver == :playwright ? options.fetch(:browser_type, :chromium).to_sym : nil
+        self.venetian_browser_type = if driver == :playwright
+                                       BrowserRunnerExtensions.browser_to_preinstall_from(options)
+                                     end
       end
 
       def install_playwright_browsers

data/lib/venetian/upstream.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "playwright"
+require "playwright/version"
 
 module Venetian
   # # \Upstream

data/lib/venetian/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Venetian
-  VERSION = "0.2.3"
+  VERSION = "0.3.0"
   COMPATIBLE_PLAYWRIGHT_VERSION = "1.63.0"
 end

data/lib/venetian.rb

@@ -2,33 +2,18 @@
 
 require "capybara/playwright"
 
-require "venetian/version"
-require "venetian/upstream"
-require "venetian/executable"
+require "venetian/playwright"
 require "venetian/playwright_create_extensions"
-require "venetian/browser_installer"
 require "venetian/browser_runner_extensions"
-require "venetian/gemspec"
-require "venetian/railtie" if defined? Rails
+require "venetian/railtie" if defined?(Rails::Railtie)
 
 # # Venetian
 #
-# Native Playwright driver for Capybara.
+# Native Playwright driver for Ruby.
 module Venetian
   class << self
-    attr_accessor :auto_install_browsers, :auto_install_dependencies
+    attr_accessor :auto_install_browsers
   end
 
-  class Error < StandardError; end
-
   self.auto_install_browsers = true
-  self.auto_install_dependencies = true
-
-  def self.execute(*, echo: true, **)
-    Executable.execute(*, echo: echo, **)
-  end
-
-  def self.system(*, echo: true, **)
-    Executable.system(*, echo: echo, **)
-  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: venetian
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Justin Malčić
@@ -55,8 +55,10 @@ files:
 - lib/venetian.rb
 - lib/venetian/browser_installer.rb
 - lib/venetian/browser_runner_extensions.rb
+- lib/venetian/core.rb
 - lib/venetian/executable.rb
 - lib/venetian/gemspec.rb
+- lib/venetian/playwright.rb
 - lib/venetian/playwright_create_extensions.rb
 - lib/venetian/railtie.rb
 - lib/venetian/system_test_case_extension.rb