venetian 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c599b422e667a871ef1b770d925eba77b670865bc3e93d453467f8868158a96
-  data.tar.gz: 10c75b357f976409bc73a3e7cb478e00f5f5bb34e2fdbcb02917ca88e96599e7
+  metadata.gz: aafa47a0f14da5b53e15342d47066d1949662794fd51bbcccf5c557a9aaa85ea
+  data.tar.gz: 0e3a2e04f9f0bc780f119767e4f681a2cd859b7962acd24b895f6b3f5a2d8148
 SHA512:
-  metadata.gz: 78a685bc7a929fd1305905e727912787162f85f88d05983e4c1649d06a8a3055e37b9ba6bb979ca5ef3d15be2619b1ff93e46394849154d079081c5b7a10adfb
-  data.tar.gz: 26e00d4ce95a2f03f5f816272788d917d092d78aae6de9423acb488021d74e9e9cfd19323e85d6e1c3644a23269de12b2357f9d935d39f0fc238f28eea17ecab
+  metadata.gz: dab03d644e9b48c4a0563767a997abff66a0d79161e575bcea79a26bd1c84efee33a73ba774d3612df3a7b8faecbaab5acf50411246381de6966607f0e2ed094
+  data.tar.gz: 5f024a8121cd70f4e48182cc192da2ed703b58c36b127969d673265fa994c67b88484a2665e171ebe6e8a1843d7d02cf83b4a8510c6964d425df819e09a851d9

data/README.md

@@ -80,13 +80,20 @@ due to e.g. differences between package managers and package names across distro
 so dependency installation happens only if a compatible package manager is found.
 Depending on what you're doing, you may not need to install dependencies, 
 but if you do and your distro is unsupported, you will need to work out what you need and deal with that first.
+On Windows, Firefox also needs the [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist),
+which Playwright doesn't install; you'll get a warning after installation if it's missing.
 
-When parallelizing tests, there's also the issue of multiple processes all trying to acquire the package manager lock:
-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 already installed (e.g. from a restored cache) are left alone. If the browsers directory
+(or `PLAYWRIGHT_BROWSERS_PATH`, if set) is read-only, as with a prepopulated cache, browsers aren't installed at all,
+since Playwright can't take its lock there, though dependencies still are if needed.
+When parallelizing tests, there's also the issue of multiple processes all trying to acquire the package manager lock,
+so installations are serialized across processes. On top of this, if you use Rails system tests with `ActionDispatch::SystemTestCase`,
+all required browsers are installed 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.
+Nor are they if you pass `:executablePath`, or a `:channel` for a system-wide browser like `chrome` or `msedge`
+(install these with e.g. `playwright install chrome`), but other channels are installed instead of the browser type.
 You can also turn installation off with `Venetian.auto_install_browsers = false`, or just dependency installation with
 `Venetian.auto_install_dependencies = false`.
 

data/lib/venetian/browser_installer.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "pathname"
+require "tmpdir"
+
 module Venetian
   # # Browser Installer
   #
@@ -18,10 +21,63 @@ module Venetian
         Executable.capture("install-deps", *browser&.to_s, "--dry-run", echo: debug?)
       end
 
+      def install_into_browsers_path(browser, deps: nil)
+        if browsers_to_install.fetch(browser) { browsers_path_writable? }
+          run_installer "install", *browser, *("--with-deps" if deps)
+        elsif deps
+          run_installer "install-deps", *browser
+        end
+        browsers_to_install[browser] = false
+        dependencies_to_install[browser] = false if deps
+      end
+
+      def browsers_path_writable?
+        [expanded_browsers_path, expanded_browsers_path.join(LINKS_DIRECTORY)].all? do |path|
+          Dir.mktmpdir(WRITE_PROBE_PREFIX, path.ascend.find(&:directory?)) { true }
+        end
+      rescue SystemCallError
+        false
+      end
+
+      def default_cache_path
+        if Gem.win_platform?
+          env_path("LOCALAPPDATA") || Pathname(Dir.home).join("AppData", "Local")
+        elsif Gem::Platform.local.os == "darwin"
+          Pathname(Dir.home).join("Library", "Caches")
+        else
+          env_path("XDG_CACHE_HOME") || Pathname(Dir.home).join(".cache")
+        end
+      end
+
+      def env_path(name)
+        return if (path = ENV.fetch(name, "")).empty?
+
+        Pathname(path)
+      end
+
       def dependencies_to_install
         @dependencies_to_install ||= {}
       end
 
+      def browsers_to_install
+        @browsers_to_install ||= {}
+      end
+
+      def with_install_lock
+        File.open(File.join(Dir.tmpdir, "venetian-#{Process.uid}.lock"), File::RDWR | File::CREAT, 0o600) do |file|
+          file.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      def run_installer(*args)
+        return Venetian.system(*args, exception: true, echo: true) if debug?
+
+        Executable.capture(*args, echo: false, merge_stderr: false).then do |output, status|
+          raise InstallError, "exit status #{status.exitstatus}\n#{output}".strip unless status.success?
+        end
+      end
+
       def debug?
         ENV.fetch("VENETIAN_DEBUG", nil)
       end
@@ -36,17 +92,26 @@ module Venetian
       def initialize(message = nil)
         super([INSTALL_FAILED_MESSAGE, *message].join(": "))
       end
+
+      def self.wrap(error) # :nodoc:
+        error.is_a?(self) ? error : new(error.message)
+      end
     end
 
-    # Installs a browser. Raises InstallError if installation fails.
+    # Installs a browser, unless it and any dependencies are already installed. Playwright skips browsers already in the
+    # browsers path, and if that's read-only (e.g. a prepopulated cache), only dependencies are installed. Raises
+    # InstallError if installation fails.
     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?
+      with_install_lock do
+        install_into_browsers_path(browser&.to_s, deps: install_dependencies?(browser, force: install_dependencies))
+      end
     rescue StandardError => e
-      raise InstallError, e.message
+      raise InstallError.wrap(e)
     end
 
+    LINKS_DIRECTORY = ".links" # :nodoc:
+    WRITE_PROBE_PREFIX = ".venetian-write-probe" # :nodoc:
+
     # 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:
 
@@ -68,6 +133,18 @@ module Venetian
       end
     end
 
+    def self.browsers_path # :nodoc:
+      case ENV.fetch("PLAYWRIGHT_BROWSERS_PATH", "")
+      when "" then default_cache_path.join("ms-playwright")
+      when "0" then Pathname(Executable.base_command.last).dirname.join(".local-browsers")
+      else Pathname(ENV.fetch("PLAYWRIGHT_BROWSERS_PATH"))
+      end
+    end
+
+    def self.expanded_browsers_path # :nodoc:
+      browsers_path.expand_path(ENV.fetch("INIT_CWD", nil) || Dir.pwd)
+    end
+
     def self.dependencies_supported?(...) # :nodoc:
       warn "Venetian::BrowserInstaller.dependencies_supported? is deprecated; use dependencies_to_install? instead.",
            category: :deprecated, uplevel: 1

data/lib/venetian/browser_runner_extensions.rb

@@ -4,18 +4,22 @@ module Venetian
   module BrowserRunnerExtensions # :nodoc:
     ALTERNATIVE_DRIVER_OPTIONS = %i[playwright_cli_executable_path playwright_server_endpoint_url
                                     browser_server_endpoint_url].freeze
+    SYSTEM_CHANNEL_PATTERN = /\A(chrome|msedge)/
 
     def self.browser_to_preinstall_from(options)
-      (options[:browser_type] || :chromium).to_sym if options.values_at(*ALTERNATIVE_DRIVER_OPTIONS).none?
+      return if options.values_at(*ALTERNATIVE_DRIVER_OPTIONS, :executablePath).any?
+      return if options[:channel].to_s.match?(SYSTEM_CHANNEL_PATTERN)
+
+      (options[:channel] || options[:browser_type] || :chromium).to_sym
     end
 
     def initialize(options = {}, *args)
-      @venetian_browser = BrowserRunnerExtensions.browser_to_preinstall_from(options) if Venetian.auto_install_browsers
+      @venetian_browser = BrowserRunnerExtensions.browser_to_preinstall_from(options)
       super
     end
 
     def start
-      BrowserInstaller.install(@venetian_browser) if @venetian_browser
+      BrowserInstaller.install(@venetian_browser) if @venetian_browser && Venetian.auto_install_browsers
       super
     end
   end

data/lib/venetian/connection_extensions.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Venetian
+  # # Forked Connection Error
+  #
+  # Raised when a Playwright connection is used by a process forked from the one that started it.
+  class ForkedConnectionError < Error
+    def initialize(pid) # :nodoc:
+      super("This Playwright connection belongs to process #{pid}, so can't be used after forking. " \
+            "Start Playwright again in this process instead.")
+    end
+  end
+
+  module ConnectionExtensions # :nodoc:
+    def initialize(...)
+      @venetian_pid = Process.pid
+      super
+    end
+
+    def async_send_message_to_server(...)
+      raise ForkedConnectionError, @venetian_pid unless Process.pid == @venetian_pid
+
+      super
+    end
+  end
+end
+
+Playwright::Connection.prepend(Venetian::ConnectionExtensions)

data/lib/venetian/executable.rb

@@ -11,8 +11,12 @@ module Venetian
     class Executor # :nodoc:
       public :system, :exec
 
-      def capture(*command)
-        Open3.capture2e(*command)
+      def capture(*command, merge_stderr: true, **)
+        merge_stderr ? Open3.capture2e(*command, **) : Open3.capture2(*command, **)
+      end
+
+      def run(*command, **)
+        Process.wait2(Process.spawn(*command, **)).last
       end
     end
 
@@ -51,11 +55,14 @@ module Venetian
     #
     # Raised when the Playwright executable cannot be found for the current platform.
     class ExecutableNotFoundError < StandardError
-      def initialize(reason, **context) # :nodoc:
+      def initialize(reason, exe_dir: nil, exe_path: nil, cli_path: nil, platform: nil) # :nodoc:
         super(case reason
-              in :directory_missing then directory_missing_message(context[:exe_dir])
-              in :executable_missing then executable_missing_message(context[:exe_dir])
-              else unsupported_platform_message(context[:platform], context[:exe_dir])
+              in :directory_missing then directory_missing_message(exe_dir)
+              in :executable_missing then executable_missing_message(exe_dir)
+              in :missing_platform then unsupported_platform_message(platform, exe_dir)
+              in :not_a_file then incomplete_message(exe_path, "#{exe_path} is not a file")
+              in :not_executable then incomplete_message(exe_path, "#{exe_path} is not executable")
+              in :cli_missing then incomplete_message(exe_path, "#{cli_path} is missing")
               end)
       end
 
@@ -69,6 +76,14 @@ module Venetian
         "#{INSTALL_DIR_ENV_VAR} is set to #{exe_dir} but playwright was not found there."
       end
 
+      def incomplete_message(exe_path, problem)
+        <<~MSG
+          The Playwright driver at #{File.dirname(exe_path)} is incomplete: #{problem}.
+
+          Reinstall the gem, or check #{INSTALL_DIR_ENV_VAR} points to a complete driver.
+        MSG
+      end
+
       def unsupported_platform_message(platform, exe_dir)
         <<~MSG
           Cannot find the Playwright executable for #{platform} in #{exe_dir}.
@@ -82,28 +97,103 @@ module Venetian
       end
     end
 
-    class << self
-      # Returns the path to the Node executable. Raises an error if the executable cannot be found.
-      def path
+    # # Unsupported Path Error
+    #
+    # Raised on Windows when the path to the Playwright executable contains an environment variable reference such as
+    # +%USERNAME%+, as Ruby would then run the command with +cmd.exe+, which expands it.
+    class UnsupportedPathError < StandardError
+      def initialize(path) # :nodoc:
+        super(<<~MSG)
+          Cannot run Playwright from #{path} as Windows would expand the environment variable references in its path.
+
+          Set #{INSTALL_DIR_ENV_VAR} to a directory without them (e.g. %NAME%) containing your Playwright executable.
+        MSG
+      end
+    end
+
+    module Command # :nodoc:
+      TOKEN_PATTERN = /\\.?|%[A-Za-z_][A-Za-z0-9_]*.?|./m
+      VARIABLE_REFERENCE_PATTERN = /\A%[A-Za-z_][A-Za-z0-9_]*%\z/
+
+      def self.shelljoin(command)
+        return command.shelljoin unless Gem.win_platform?
+
+        command.collect { |arg| %("#{arg}") }
+               .join(" ")
+               .tap { |string| raise UnsupportedPathError, command.first if run_by_cmd?(string) }
+      end
+
+      def self.run_by_cmd?(string)
+        string.scan(TOKEN_PATTERN).any? { |token| token.match?(VARIABLE_REFERENCE_PATTERN) }
+      end
+    end
+
+    module Validations # :nodoc:
+      private
+
+      def validate!
         ensure_exe_dir_exists!
         ensure_gem_platform_supported! unless ENV.key?(INSTALL_DIR_ENV_VAR)
         ensure_executable_exists!
+        ensure_exe_file!
+        ensure_exe_executable!
+        ensure_cli_path_exists!
+      end
+
+      def ensure_exe_dir_exists!
+        raise ExecutableNotFoundError.new(:directory_missing, exe_dir: exe_dir) unless exe_dir_exists?
+      end
+
+      def ensure_gem_platform_supported!
+        raise UnsupportedPlatformError, platform if gem_platforms_unsupported?
+      end
+
+      def ensure_executable_exists!
+        return unless exe_path.nil?
+
+        raise ExecutableNotFoundError.new ENV.key?(INSTALL_DIR_ENV_VAR) ? :executable_missing : :missing_platform,
+                                          exe_dir: exe_dir, platform: platform
+      end
+
+      def ensure_exe_file!
+        return if exe_file?
+
+        raise ExecutableNotFoundError.new(:not_a_file, exe_path: exe_path)
+      end
+
+      def ensure_exe_executable!
+        return if exe_executable?
+
+        raise ExecutableNotFoundError.new(:not_executable, exe_path: exe_path)
+      end
+
+      def ensure_cli_path_exists!
+        return if cli_path_exists?
+
+        raise ExecutableNotFoundError.new(:cli_missing, exe_path: exe_path, cli_path: cli_path_for(exe_path))
+      end
+    end
+
+    extend Validations
+
+    class << self
+      # Returns the path to the Node executable. Raises an error if the executable cannot be found.
+      def path
+        validate!
 
         exe_path
       end
 
-      # Executes the Playwright executable with the given arguments.
+      # 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|
-          # due to mysterious Windows behavior; see equivalent in `tailwindcss-ruby`
-          next system(*args, exception:, echo:) if Gem.win_platform?
-
           puts command.shelljoin if echo
-          begin
-            executor.exec(*command)
-          rescue StandardError
-            exception ? raise : false
-          end
+          # exec misbehaves on Windows (see equivalent in `tailwindcss-ruby`), so run Playwright and exit likewise
+          exit executor.run(*command, **).exitstatus if Gem.win_platform?
+
+          executor.exec(*command, **)
+        rescue StandardError
+          exception ? raise : false
         end
       end
 
@@ -111,16 +201,15 @@ module Venetian
       def system(*args, echo: true, exception: true, **)
         [*base_command, *args].then do |command|
           puts command.shelljoin if echo
-          executor.system(*command,
-                          exception:, **{ out: echo ? nil : File::NULL, err: echo ? nil : File::NULL }.compact)
+          executor.system(*command, exception:, **(echo ? {} : { out: File::NULL, err: File::NULL }), **)
         end
       end
 
       # Runs the Playwright executable with the given arguments, returning its combined output and status.
-      def capture(*args, echo: true)
+      def capture(*args, echo: true, **)
         [*base_command, *args].then do |command|
           puts command.shelljoin if echo
-          executor.capture(*command).tap do |output, _|
+          executor.capture(*command, **).tap do |output, _|
             puts output if echo
           end
         end
@@ -128,50 +217,45 @@ module Venetian
 
       # Returns the base command to execute Playwright.
       def base_command
-        [path, File.join(File.dirname(path), "package", "cli.js")]
+        path.then { |path| [path, cli_path_for(path)] }
       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
+        Command.shelljoin(base_command)
       end
 
       private
 
-      def ensure_exe_dir_exists!
-        raise ExecutableNotFoundError.new(:directory_missing, exe_dir: exe_dir) unless exe_dir_exists?
+      def exe_dir_exists?
+        File.directory?(exe_dir)
       end
 
-      def ensure_gem_platform_supported!
-        raise UnsupportedPlatformError, platform if gem_platforms_unsupported?
+      def exe_dir
+        ENV[INSTALL_DIR_ENV_VAR] || DEFAULT_DIR
       end
 
-      def ensure_executable_exists!
-        return unless exe_path.nil?
+      def exe_file?
+        File.file?(exe_path.to_s)
+      end
 
-        raise ExecutableNotFoundError.new ENV.key?(INSTALL_DIR_ENV_VAR) ? :executable_missing : :missing_platform,
-                                          exe_dir: exe_dir, platform: platform
+      def exe_executable?
+        File.executable?(exe_path.to_s)
       end
 
-      def exe_dir_exists?
-        File.directory?(exe_dir)
+      def cli_path_exists?
+        File.file?(cli_path_for(exe_path))
       end
 
-      def exe_dir
-        ENV[INSTALL_DIR_ENV_VAR] || DEFAULT_DIR
+      def cli_path_for(exe_path)
+        File.join(File.dirname(exe_path), "package", "cli.js")
       end
 
       def exe_path
         return custom_exe_path if ENV.key?(INSTALL_DIR_ENV_VAR)
 
-        Upstream::NATIVE_PLATFORMS.select { |platform, _| Gem::Platform.match_gem?(Gem::Platform.new(platform), gem_name) }
-                                  .collect { |platform, info| File.join(exe_dir, platform, info.executable_name) }
-                                  .detect { |candidate| File.exist?(candidate) }
+        native_platforms.collect { |platform, info| File.join(exe_dir, platform, info.executable_name) }
+                        .detect { |candidate| File.exist?(candidate) }
       end
 
       def custom_exe_path
@@ -183,7 +267,17 @@ module Venetian
       end
 
       def gem_platforms_unsupported?
-        Upstream::NATIVE_PLATFORMS.keys.none? { |platform| Gem::Platform.match_gem?(Gem::Platform.new(platform), gem_name) }
+        native_platforms.none?
+      end
+
+      def native_platforms
+        return {} if musl? # musl isn't supported because official Linux Node binaries require glibc
+
+        Upstream::NATIVE_PLATFORMS.select { |platform, _| Gem::Platform.match_gem?(Gem::Platform.new(platform), gem_name) }
+      end
+
+      def musl?
+        Gem::Platform.local.then { |local| local.os == "linux" && local.version.to_s.start_with?("musl") }
       end
 
       def gem_name

data/lib/venetian/playwright.rb

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

data/lib/venetian/system_test_case_extension.rb

@@ -1,24 +1,33 @@
 # frozen_string_literal: true
 
 module Venetian
-  module SystemTestCaseExtension # :nodoc:
+  module SystemTestCaseExtension # :nodoc: all
     extend ActiveSupport::Concern
 
+    module ParallelizationExtension
+      def start
+        ActionDispatch::SystemTestCase.venetian_before_fork
+        super
+      end
+    end
+
     prepended do
-      class_attribute :venetian_browser_type, default: :chromium, instance_writer: false
+      # Set by +driven_by+, so classes using a driver registered under another name are still included.
+      class_attribute :venetian_browser_type, default: nil, instance_writer: false
 
-      parallelize_before_fork do
-        install_playwright_browsers if venetian_preinstall_browsers_before_fork?
+      if respond_to?(:parallelize_before_fork)
+        parallelize_before_fork { venetian_before_fork }
+      else
+        ActiveSupport::Testing::Parallelization.prepend(ParallelizationExtension)
       end
     end
 
-    class_methods do # :nodoc:
+    class_methods do
       def driven_by(driver, options: {}, **)
-        super
-
         self.venetian_browser_type = if driver == :playwright
                                        BrowserRunnerExtensions.browser_to_preinstall_from(options)
                                      end
+        super
       end
 
       def install_playwright_browsers
@@ -28,6 +37,10 @@ module Venetian
         end
       end
 
+      def venetian_before_fork
+        install_playwright_browsers if venetian_preinstall_browsers_before_fork?
+      end
+
       private
 
       def venetian_preinstall_browsers_before_fork?
@@ -36,7 +49,7 @@ module Venetian
 
       def venetian_browsers
         Minitest::Runnable.runnables
-                          .select { |klass| klass < ActionDispatch::SystemTestCase && klass.driver&.name == :playwright }
+                          .select { |klass| klass < ActionDispatch::SystemTestCase }
                           .filter_map(&:venetian_browser_type)
                           .uniq
       end

data/lib/venetian/upstream.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "playwright/version"
+require "venetian/version"
 
 module Venetian
   # # \Upstream
@@ -43,7 +43,7 @@ module Venetian
 
     # Returns the URL to download the playwright-core npm package containing the driver's JS sources.
     def self.playwright_core_url
-      "#{NPM_REGISTRY_URL}/playwright-core/-/playwright-core-#{Playwright::COMPATIBLE_PLAYWRIGHT_VERSION}.tgz"
+      "#{NPM_REGISTRY_URL}/playwright-core/-/playwright-core-#{COMPATIBLE_PLAYWRIGHT_VERSION}.tgz"
     end
 
     # Returns the gemspec files for the base gem.

data/lib/venetian/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: venetian
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Justin Malčić
@@ -27,14 +27,14 @@ dependencies:
   name: playwright-ruby-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 1.63.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 1.63.0
 description: Bundles the Playwright driver binary in platform-specific gem variants
@@ -55,6 +55,7 @@ files:
 - lib/venetian.rb
 - lib/venetian/browser_installer.rb
 - lib/venetian/browser_runner_extensions.rb
+- lib/venetian/connection_extensions.rb
 - lib/venetian/core.rb
 - lib/venetian/executable.rb
 - lib/venetian/gemspec.rb