venetian 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8894a94bd04d285d094166aea97a598e5fe430d0517cd2727af3004c1c1e94ca
-  data.tar.gz: 0bc4c8fa1e7b5188df862e0a1addba7beb46a4e52eb4baa2421c545cc7638fd8
+  metadata.gz: 2a4d0e9aeaf06ee35d6366722bf2a6b6b9bd9f09500f171d1515a73de97a7825
+  data.tar.gz: 04d7d10bc92a7b8b524f669b34dc0a7c456f7a8f7d90dff85e80ec2c29f2ff5d
 SHA512:
-  metadata.gz: 53e51de62a9901d09b496f21f13fef0003d17ae21ee7284e722863fe3b1f8485d43bd2f255aaa8ab2252e736b474ca2d04742caa721dff29b48c319d4cd369ce
-  data.tar.gz: 4fe720569a97919438869bb4e65e5fc1f132922837fca139174f86c20f059f28423ba0c7b376e9bec53fa92dcd52b876a4b64913ccb7857a21716c12f3fdbc47
+  metadata.gz: 1d11a9eb73105eb8700a9657769be900dc5239f59f6e230546b6a8c44dbf68d887a57027163648471b14c82d90200c09ac2d9cc414abfab4b328f1af238a6e0f
+  data.tar.gz: e110ce724c3cae3de2a0cd90ff23f9b141f76b38e5786fea91e010b6eeda63fb68f7821bc75466d771dcb27f93c2e9d3a8d4ea62f96915772e0cb5503229ce22

data/README.md

@@ -14,9 +14,11 @@ bundle add venetian --group test
 
 ## Usage
 
+### Rails system tests
+
 In your system test case, choose the Playwright driver. Venetian will provide the base command to run Playwright,
 which you can still override by passing `:playwright_cli_executable_path`, and this plus any other options will be passed through 
-to `capybara-playwright-driver`. If you specify a browser, this will be automatically downloaded if necessary.
+to `capybara-playwright-driver`.
 
 ```ruby
 require "test_helper"
@@ -26,6 +28,73 @@ class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
 end
 ```
 
+### Using Capybara directly
+
+Likewise, register the Playwright driver before using it later:
+
+```ruby
+Capybara.register_driver :playwright do |app|
+  Capybara::Playwright::Driver.new(app)
+end
+```
+
+### Automatic browser and dependency installation
+
+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) 
+to avoid downloads on every run.
+
+On Linux,
+[Playwright currently only officially supports Debian and Ubuntu](https://playwright.dev/docs/intro#system-requirements) 
+due to e.g. differences between package managers and package names across distros, 
+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.
+
+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.
+
+### 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.
+
+```bash
+$ RAILS_ENV=test rails venetian:install
+
+# Or a specific browser
+$ RAILS_ENV=test rails venetian:install[firefox]
+```
+
+Otherwise in your Rakefile add:
+
+```ruby
+load "tasks/venetian.rake"
+```
+
+And then run:
+
+```bash
+$ rake venetian:install
+```
+
+### Running Playwright yourself
+
+The gem provides a `playwright` executable which you can use to run Playwright yourself.
+
+```bash
+$ playwright --version 
+Version 1.61.1
+```
+
+### Getting more output
+
+Noisy output during a test run is often frustrating, so the gem is quiet by default. 
+You can get more output with `VENETIAN_DEBUG=1`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. 

data/lib/venetian/browser_installer.rb

@@ -5,6 +5,18 @@ module Venetian
   #
   # Installs browsers using the Playwright executable.
   class BrowserInstaller
+    class << self
+      private
+
+      def install_dependencies?
+        Venetian.auto_install_dependencies && dependencies_supported?
+      end
+
+      def install_dry_run
+        Venetian.system "install-deps", "--dry-run", exception: false, echo: ENV.fetch("VENETIAN_DEBUG", nil)
+      end
+    end
+
     # # Install Error
     #
     # Raised when the installation fails for some reason.
@@ -17,11 +29,18 @@ module Venetian
     end
 
     # Installs a browser. Raises InstallError if installation fails.
-    def self.install(browser = nil, install_dependencies: true)
+    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)
     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
+
+      @dependencies_supported = install_dry_run || false
+    end
   end
 end

data/lib/venetian/executable.rb

@@ -5,6 +5,10 @@ module Venetian
   #
   # Provides methods for locating the Playwright executable.
   module Executable
+    class Executor # :nodoc:
+      public :system, :exec
+    end
+
     DEFAULT_DIR = File.expand_path(File.join(__dir__, "..", "..", "exe")) # :nodoc:
     INSTALL_DIR_ENV_VAR = "VENETIAN_INSTALL_DIR" # :nodoc:
 
@@ -82,21 +86,26 @@ module Venetian
       end
 
       # Executes the Playwright executable with the given arguments.
-      def execute(*args, echo: true)
-        [base_command, *args].then do |command|
-          puts command.inspect if echo
+      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(*command, exception: true) if Gem.win_platform?
-
-          exec(*command)
+          next system(*args, exception:, echo:) if Gem.win_platform?
+
+          puts command.shelljoin if echo
+          begin
+            executor.exec(*command)
+          rescue StandardError
+            exception ? raise : false
+          end
         end
       end
 
       # Runs the Playwright executable with the given arguments.
-      def system(*args, echo: true, **)
+      def system(*args, echo: true, exception: true, **)
         [*base_command, *args].then do |command|
-          puts command.inspect if echo
-          super(*command, exception: true)
+          puts command.shelljoin if echo
+          executor.system(*command,
+                          exception:, **{ out: echo ? nil : File::NULL, err: echo ? nil : File::NULL }.compact)
         end
       end
 
@@ -133,7 +142,7 @@ module Venetian
       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), GEMSPEC.name) }
+        Upstream::NATIVE_PLATFORMS.select { |platform, _| Gem::Platform.match_gem?(Gem::Platform.new(platform), gem_name) }
                                   .collect { |platform, _info| File.join(exe_dir, platform, "node") }
                                   .detect { |candidate| File.exist?(candidate) }
       end
@@ -143,12 +152,20 @@ module Venetian
       end
 
       def gem_platforms_unsupported?
-        Upstream::NATIVE_PLATFORMS.keys.none? { |platform| Gem::Platform.match_gem?(Gem::Platform.new(platform), GEMSPEC.name) }
+        Upstream::NATIVE_PLATFORMS.keys.none? { |platform| Gem::Platform.match_gem?(Gem::Platform.new(platform), gem_name) }
+      end
+
+      def gem_name
+        GEMSPEC&.name || "venetian"
       end
 
       def platform
         Gem::Platform.local.to_s
       end
+
+      def executor
+        @executor ||= Executor.new
+      end
     end
   end
 end

data/lib/venetian/railtie.rb

@@ -5,5 +5,12 @@ module Venetian
     rake_tasks do
       load "tasks/venetian.rake"
     end
+
+    initializer "venetian.system_test_setup" do
+      ActiveSupport.on_load :action_dispatch_system_test_case do
+        require "venetian/system_test_case_extension"
+        prepend SystemTestCaseExtension
+      end
+    end
   end
 end

data/lib/venetian/system_test_case_extension.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Venetian
+  module SystemTestCaseExtension # :nodoc:
+    extend ActiveSupport::Concern
+
+    prepended do
+      class_attribute :venetian_browser_type, default: :chromium, instance_writer: false
+
+      parallelize_before_fork do
+        install_playwright_browsers if venetian_preinstall_browsers_before_fork?
+      end
+    end
+
+    class_methods do # :nodoc:
+      def driven_by(driver, options: {}, **)
+        super
+
+        self.venetian_browser_type = driver == :playwright ? options.fetch(:browser_type, :chromium).to_sym : nil
+      end
+
+      def install_playwright_browsers
+        venetian_browsers.presence.try do |browsers|
+          browsers.each { |browser| BrowserInstaller.install(browser) }
+          Venetian.auto_install_browsers = false
+        end
+      end
+
+      private
+
+      def venetian_preinstall_browsers_before_fork?
+        Venetian.auto_install_browsers && defined? ActionDispatch::SystemTestCase
+      end
+
+      def venetian_browsers
+        Minitest::Runnable.runnables
+                          .select { |klass| klass < ActionDispatch::SystemTestCase && klass.driver&.name == :playwright }
+                          .filter_map(&:venetian_browser_type)
+                          .uniq
+      end
+    end
+  end
+end

data/lib/venetian/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Venetian
-  VERSION = "0.1.3"
-  COMPATIBLE_PLAYWRIGHT_VERSION = "1.60.0"
+  VERSION = "0.2.0"
+  COMPATIBLE_PLAYWRIGHT_VERSION = "1.61.1"
 end

data/lib/venetian.rb

@@ -16,15 +16,16 @@ require "venetian/railtie" if defined? Rails
 # Native Playwright driver for Capybara.
 module Venetian
   class << self
-    attr_accessor :auto_install_browsers
+    attr_accessor :auto_install_browsers, :auto_install_dependencies
   end
 
   class Error < StandardError; end
 
   self.auto_install_browsers = true
+  self.auto_install_dependencies = true
 
-  def self.execute(*, echo: true)
-    Executable.execute(*, echo: echo)
+  def self.execute(*, echo: true, **)
+    Executable.execute(*, echo: echo, **)
   end
 
   def self.system(*, echo: true, **)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: venetian
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Justin Malčić
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.60.0
+        version: 1.61.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.60.0
+        version: 1.61.0
 description: Bundles the Playwright driver binary in platform-specific gem variants
   and integrates with `capybara-playwright-driver`.
 email:
@@ -59,6 +59,7 @@ files:
 - lib/venetian/gemspec.rb
 - lib/venetian/playwright_create_extensions.rb
 - lib/venetian/railtie.rb
+- lib/venetian/system_test_case_extension.rb
 - lib/venetian/tasks.rb
 - lib/venetian/upstream.rb
 - lib/venetian/version.rb
@@ -69,7 +70,7 @@ metadata:
   homepage_uri: https://malcic.codes/software/venetian
   source_code_uri: https://github.com/jmalcic/venetian
   rubygems_mfa_required: 'true'
-  playwright_version: 1.60.0
+  playwright_version: 1.61.1
 rdoc_options: []
 require_paths:
 - lib