venetian 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee4a825fffe442202e0321928ba3aea21c82eebc8dcd0d8e6672b24a46ed6236
+  data.tar.gz: 500819233fcdc8ee6b1c97adb96ddbd1637a9ddac642e0f9bac8b452e835ced4
+SHA512:
+  metadata.gz: e8bcf1bcf0ac89adc4b7f4e84a439579f1edcd815edf608f1d2ffbe90532e2b079ed64af6e1a58923519083956a5720336bdfe9cab6f2e40baf88ec3d794a360
+  data.tar.gz: a8300d7492ad92ae6bf615978a1ce24cb2f41328bf0918be81fc770e0b1478922067314e893a4a133190e99da86b386a4effe21fd0ce83b9ee1c743b99e7912c

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"venetian" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["j.malcic@me.com"](mailto:"j.malcic@me.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Justin Malčić
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+# Venetian
+
+Want stable system tests with Playwright, but don't want a Heath Robinson/Rube Goldberg setup in CI to try to keep the Ruby gem and Node
+package in sync? This gem packages a Node executable plus the common Playwright package, using builds produced by Playwright for other
+languages.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add venetian --group test
+```
+
+## Usage
+
+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.
+
+```ruby
+require "test_helper"
+
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  driven_by :playwright
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. 
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. 
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, 
+which will create a git tag for the version, push git commits and the created tag, 
+and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jmalcic/venetian. 
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected 
+to adhere to the [code of conduct](https://www.ruby-lang.org/en/conduct/).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Venetian project's codebases, issue trackers, chat rooms and mailing lists is expected
+to follow the [code of conduct](https://www.ruby-lang.org/en/conduct/).

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]
+
+import "rakelib/release.rake"

data/exe/playwright

@@ -0,0 +1,11 @@
+#! /usr/bin/env ruby
+# frozen_string_literal: true
+
+require "venetian"
+
+begin
+  Venetian.execute(*ARGV, echo: ENV.fetch("VENETIAN_DEBUG", nil))
+rescue Venetian::Executable::UnsupportedPlatformError, Venetian::Executable::ExecutableNotFoundError => e
+  warn "ERROR: #{e.message}"
+  exit 1
+end

data/lib/tasks/venetian.rake

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+namespace :venetian do
+  desc <<~USAGE
+    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"
+    Venetian::BrowserInstaller.install(args[:browser])
+  end
+end

data/lib/venetian/browser_installer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Venetian
+  # # Browser Installer
+  #
+  # Installs browsers using the Playwright executable.
+  class BrowserInstaller
+    # # Install Error
+    #
+    # Raised when the installation fails for some reason.
+    class InstallError < StandardError
+      INSTALL_FAILED_MESSAGE = "Playwright install failed. Run `rake venetian:install` manually."
+
+      def initialize(message = nil)
+        super([INSTALL_FAILED_MESSAGE, *message].join(": "))
+      end
+    end
+
+    # Installs a browser. Raises InstallError if installation fails.
+    def self.install(browser = nil)
+      Executable.system "install", *browser&.to_s, exception: true
+    rescue StandardError => e
+      raise InstallError, e.message
+    end
+  end
+end

data/lib/venetian/browser_runner_extensions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Venetian
+  module BrowserRunnerExtensions # :nodoc:
+    def initialize(options = {}, *args)
+      @venetian_browser_type = options[:browser_type] || :chromium
+      super
+    end
+
+    def start
+      BrowserInstaller.install(@venetian_browser_type) if Venetian.auto_install_browsers
+      super
+    end
+  end
+end
+
+Capybara::Playwright::BrowserRunner.prepend(Venetian::BrowserRunnerExtensions)

data/lib/venetian/executable.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Venetian
+  # # \Executable
+  #
+  # Provides methods for locating the Playwright executable.
+  module Executable
+    DEFAULT_DIR = File.expand_path(File.join(__dir__, "..", "..", "exe")) # :nodoc:
+    INSTALL_DIR_ENV_VAR = "VENETIAN_INSTALL_DIR" # :nodoc:
+
+    # # Unsupported Platform Error
+    #
+    # Raised when no platform targeted by this gem is supported by the Rubygems installation.
+    class UnsupportedPlatformError < StandardError
+      def initialize(platform) # :nodoc:
+        super(unsupported_platform_message(platform))
+      end
+
+      private
+
+      def unsupported_platform_message(platform)
+        <<~MSG
+          Playwright does not support the #{platform} platform.
+          Supported platforms:
+            #{supported_platforms}
+
+          Set #{INSTALL_DIR_ENV_VAR} to the directory containing your playwright executable.
+          See https://github.com/jmalcic/venetian for more details.
+        MSG
+      end
+
+      def supported_platforms
+        Upstream::NATIVE_PLATFORMS.keys
+                                  .collect { |platform| "- #{platform}" }
+                                  .join("\n  ")
+      end
+    end
+
+    # # Executable Not Found Error
+    #
+    # Raised when the Playwright executable cannot be found for the current platform.
+    class ExecutableNotFoundError < StandardError
+      def initialize(reason, **context) # :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])
+              end)
+      end
+
+      private
+
+      def directory_missing_message(exe_dir)
+        "#{INSTALL_DIR_ENV_VAR} is set to #{exe_dir} but that directory does not exist."
+      end
+
+      def executable_missing_message(exe_dir)
+        "#{INSTALL_DIR_ENV_VAR} is set to #{exe_dir} but playwright was not found there."
+      end
+
+      def unsupported_platform_message(platform, exe_dir)
+        <<~MSG
+          Cannot find the Playwright executable for #{platform} in #{exe_dir}.
+
+          Make sure your Gemfile.lock includes this platform:
+            bundle lock --add-platform #{platform}
+            bundle install
+
+          Or set #{INSTALL_DIR_ENV_VAR} to the directory containing your Playwright executable.
+        MSG
+      end
+    end
+
+    class << self
+      # Returns the path to the Node executable. Raises an error if the executable cannot be found.
+      def path
+        ensure_exe_dir_exists!
+        ensure_gem_platform_supported! unless ENV.key?(INSTALL_DIR_ENV_VAR)
+        ensure_executable_exists!
+
+        exe_path
+      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
+          # due to mysterious Windows behavior; see equivalent in `tailwindcss-ruby`
+          next system(*command, exception: true) if Gem.win_platform?
+
+          exec(*command)
+        end
+      end
+
+      # Runs the Playwright executable with the given arguments.
+      def system(*args, echo: true, **)
+        [*base_command, *args].then do |command|
+          puts command.inspect if echo
+          super(*command, exception: true)
+        end
+      end
+
+      # Returns the base command to execute Playwright.
+      def base_command
+        [path, File.join(File.dirname(path), "package", "cli.js")]
+      end
+
+      private
+
+      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 exe_dir_exists?
+        File.directory?(exe_dir)
+      end
+
+      def exe_dir
+        ENV[INSTALL_DIR_ENV_VAR] || DEFAULT_DIR
+      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), GEMSPEC.name) }
+                                  .collect { |platform, _info| File.join(exe_dir, platform, "node") }
+                                  .detect { |candidate| File.exist?(candidate) }
+      end
+
+      def custom_exe_path
+        File.join(exe_dir, "node").then { |path| path if File.exist?(path) }
+      end
+
+      def gem_platforms_unsupported?
+        Upstream::NATIVE_PLATFORMS.keys.none? { |platform| Gem::Platform.match_gem?(Gem::Platform.new(platform), GEMSPEC.name) }
+      end
+
+      def platform
+        Gem::Platform.local.to_s
+      end
+    end
+  end
+end

data/lib/venetian/gemspec.rb

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

data/lib/venetian/playwright_create_extensions.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Venetian
+  module PlaywrightCreateExtensions # :nodoc:
+    def initialize(options = {}, *)
+      super({ playwright_cli_executable_path: Executable.base_command.shelljoin }.merge(options), *)
+    end
+  end
+end
+
+Capybara::Playwright::BrowserRunner::PlaywrightCreate.prepend(Venetian::PlaywrightCreateExtensions)

data/lib/venetian/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Venetian
+  class Railtie < Rails::Railtie # :nodoc:
+    rake_tasks do
+      load "tasks/venetian.rake"
+    end
+  end
+end

data/lib/venetian/tasks.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+load "tasks/venetian.rake"

data/lib/venetian/upstream.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "playwright"
+
+module Venetian
+  # # \Upstream
+  #
+  # Provides platform mappings and URLs for Playwright.
+  module Upstream
+    # map of gem platform strings to Playwright CDN platform strings and executable names inside the driver zip
+    NATIVE_PLATFORMS = {
+      "x86_64-linux" => "linux",
+      "aarch64-linux" => "linux-arm64",
+      "x86_64-darwin" => "mac",
+      "arm64-darwin" => "mac-arm64",
+      "x64-mingw-ucrt" => "win32_x64"
+    }.freeze
+
+    # base for driver download URLs
+    BASE_URL = "https://playwright.azureedge.net/builds/driver"
+
+    # Returns the URL to download the driver for the given platform.
+    def self.driver_download_url(playwright_platform)
+      "#{BASE_URL}/playwright-#{Playwright::COMPATIBLE_PLAYWRIGHT_VERSION}-#{playwright_platform}.zip"
+    end
+
+    # Returns a hash that maps platforms to download URLs.
+    def self.download_urls
+      NATIVE_PLATFORMS.transform_values { |value| driver_download_url(value) }
+    end
+
+    # Returns the gemspec files for the base gem.
+    def self.base_files
+      GEMSPEC.files
+    end
+
+    # Builds a gemspec for the given platform, adding the files currently in the native platform directory.
+    def self.build_gemspec_for(platform)
+      GEMSPEC.dup.tap do |s|
+        s.platform = platform
+        s.files += Dir["exe/#{platform}/**/*"]
+      end
+    end
+  end
+end

data/lib/venetian/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Venetian
+  VERSION = "0.1.0"
+end

data/lib/venetian.rb

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

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: venetian
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Justin Malčić
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capybara-playwright-driver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+description: Bundles the Playwright driver binary in platform-specific gem variants
+  and integrates with `capybara-playwright-driver`.
+email:
+- j.malcic@me.com
+executables:
+- playwright
+extensions: []
+extra_rdoc_files: []
+files:
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/playwright
+- lib/tasks/venetian.rake
+- lib/venetian.rb
+- lib/venetian/browser_installer.rb
+- lib/venetian/browser_runner_extensions.rb
+- lib/venetian/executable.rb
+- lib/venetian/gemspec.rb
+- lib/venetian/playwright_create_extensions.rb
+- lib/venetian/railtie.rb
+- lib/venetian/tasks.rb
+- lib/venetian/upstream.rb
+- lib/venetian/version.rb
+homepage: https://github.com/jmalcic/venetian
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://malcic.codes/software/venetian
+  source_code_uri: https://github.com/jmalcic/venetian
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Playwright executables for Ruby
+test_files: []