sus-fixtures-async-webdriver 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b2db086816dba9ccdeda6e616fa7061c1bdfc566c1a93f44171a27d3025d469
-  data.tar.gz: 683370ebe7cdedb936d9afca32c14a6bdc8ec8258457b9cc0b141fc040010fca
+  metadata.gz: 13796a43b11df5959aa1c2e61af561b337ab98395ac06755665c8c2b6f655af8
+  data.tar.gz: 36ad7b10080390c72879d81a3ba8f63cf232943889cf19fb05574c12b3f11bed
 SHA512:
-  metadata.gz: adb1ad8e5ad03fbc42cce1a599a6f7057034e343d901bd296e615b3cce3536785bc990378b2fbe01de43ec5853a9408c894942c07e4d0a99e855e8499940e9fb
-  data.tar.gz: 00b007a710ebbfdeda0ef446717485b17ff83dfd3ee3c45902711de70f3d2c2f08a0fa913ca53beb78240a32787cf66f9d0a143dcbacf8f93cd657e28b9e57c7
+  metadata.gz: c9487d809b255d6e6c12309c690a72c778d661602d0cc19e5186944cb6bfa5aebe87a524180765f6fd3055d20a45fd3a3e9566574c9d486e3e07427f466bbc35
+  data.tar.gz: 496f5c1e1d4c2c692d13ef976516c3df65968c53c07e404191418c8c9931f96faa330b9c20bdbb2ba98a4cefa9830e10c691170c6d06bd458ac8ee0b716328c9

data/context/getting-started.md

@@ -0,0 +1,59 @@
+# Getting Started
+
+This guide is designed to help you get started with the `sus-fixtures-async-webdriver` gem.
+
+## Installation
+
+Add the gem to your project:
+
+``` bash
+$ bundle add sus-fixtures-async-webdriver
+```
+
+## Usage
+
+Simply add the appropriate fixtures to your integration tests:
+
+```ruby
+require 'sus/fixtures/async/http/server_context'
+require 'sus/fixtures/async/webdriver/session_context'
+
+require 'protocol/rack/adapter'
+require 'rack/builder'
+
+describe "my website" do
+	include Sus::Fixtures::Async::HTTP::ServerContext
+	include Sus::Fixtures::Async::WebDriver::SessionContext
+	
+	def middleware
+		Protocol::Rack::Adapter.new(app)
+	end
+	
+	def app
+		Rack::Builder.load_file(File.expand_path('../config.ru', __dir__))
+	end
+	
+	it "has a title" do
+		navigate_to('/')
+		
+		expect(session.document_title).to be == "Example"
+	end
+end
+```
+
+See `examples/rack` for a full example.
+
+## Automatic Debugging
+
+When tests fail, the `SessionContext` automatically captures debugging information to help you understand what went wrong:
+
+- **HTML Source**: The current page DOM structure is saved to a timestamped `.html` file
+- **Screenshot**: A visual screenshot of the page is saved to a timestamped `.png` file
+
+Debug files are automatically saved to the `tmp/debug/` directory and named with the test class and timestamp (e.g., `tmp/debug/MyTestClass-20250923-143022.html`). When a test fails, you'll see output like:
+
+```
+🐛 Test failed, debug files captured: 📄 HTML: tmp/debug/MyTestClass-20250923-143022.html 📸 Screenshot: tmp/debug/MyTestClass-20250923-143022.png ❌ Error: NoSuchElementError: Element not found
+```
+
+This debugging information is captured automatically without any additional setup - just include the `SessionContext` fixture and it will handle debug capture on test failures.

data/context/index.yaml

@@ -0,0 +1,13 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A set of sus fixtures for writing integration tests.
+metadata:
+  documentation_uri: https://socketry.github.io/sus-fixtures-async-webdriver/
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/socketry/sus-fixtures-async-webdriver.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide is designed to help you get started with the `sus-fixtures-async-webdriver`
+    gem.

data/lib/sus/fixtures/async/webdriver/session_context.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023, by Samuel Williams.
+# Copyright, 2023-2024, by Samuel Williams.
 
-require 'async/webdriver'
-require 'async/webdriver/bridge/pool'
+require "async/webdriver"
+require "async/webdriver/bridge/pool"
+require "fileutils"
 
 module Sus
 	module Fixtures
@@ -44,8 +45,13 @@ module Sus
 						@session = nil
 					end
 					
-					def after
+					def after(error = nil)
 						if @session
+							# Capture debugging information if there was an error
+							if error
+								capture_debug_state(error)
+							end
+							
 							SessionContext.pool.reuse(@session)
 							@session = nil
 						end
@@ -53,6 +59,36 @@ module Sus
 						super
 					end
 					
+					private
+					
+					def capture_debug_state(error)
+						return unless @session
+						
+						begin
+							# Create debug directory if it doesn't exist
+							debug_dir = "tmp/debug"
+							::FileUtils.mkdir_p(debug_dir)
+							
+							timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
+							test_name = self.class.name&.gsub("::", "-") || "unknown-test"
+							prefix = "#{test_name}-#{timestamp}"
+							
+							# Capture HTML source
+							html = @session.document_source
+							html_file = ::File.join(debug_dir, "#{prefix}.html")
+							::File.write(html_file, html)
+							
+							# Capture screenshot
+							screenshot_data = @session.screenshot
+							screenshot_file = ::File.join(debug_dir, "#{prefix}.png")
+							::File.binwrite(screenshot_file, screenshot_data)
+							
+							inform "🐛 Test failed, debug files captured: 📄 HTML: #{html_file} 📸 Screenshot: #{screenshot_file} ❌ Error: #{error.class.name}: #{error.message}"
+						rescue => debug_error
+							inform "⚠️ Failed to capture debug state: #{debug_error.class.name}: #{debug_error.message}"
+						end
+					end
+					
 					# Navigate to a specific path within the website.
 					# @parameter path [String] The path to navigate to.
 					def navigate_to(path)

data/lib/sus/fixtures/async/webdriver/version.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023, by Samuel Williams.
+# Copyright, 2023-2024, by Samuel Williams.
 
 module Sus
 	module Fixtures
 		module Async
 			module WebDriver
-				VERSION = "0.1.2"
+				VERSION = "0.3.0"
 			end
 		end
 	end

data/readme.md

@@ -10,6 +10,14 @@ Please see the [project documentation](https://socketry.github.io/sus-fixtures-a
 
   - [Getting Started](https://socketry.github.io/sus-fixtures-async-webdriver/guides/getting-started/index) - This guide is designed to help you get started with the `sus-fixtures-async-webdriver` gem.
 
+## Releases
+
+Please see the [project releases](https://socketry.github.io/sus-fixtures-async-webdriver/releases/index) for all releases.
+
+### v0.3.0
+
+  - Dump screenshot and HTML of the browser session on test failure for easier debugging.
+
 ## See Also
 
   - [async-webdriver](https://github.com/socketry/async-webdriver) - Asynchronous WebDriver client used by this fixture.
@@ -26,8 +34,8 @@ We welcome contributions to this project.
 
 ### Developer Certificate of Origin
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
 
-### Contributor Covenant
+### Community Guidelines
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,5 @@
+# Releases
+
+## v0.3.0
+
+  - Dump screenshot and HTML of the browser session on test failure for easier debugging.

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: sus-fixtures-async-webdriver
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -37,7 +36,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-05-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-webdriver
@@ -45,32 +44,32 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
-description:
-email:
+        version: '0.9'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/getting-started.md
+- context/index.yaml
 - lib/sus/fixtures/async/webdriver/session_context.rb
 - lib/sus/fixtures/async/webdriver/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/sus-fixtures-async-webdriver
 licenses:
 - MIT
 metadata:
   documentation_uri: https://socketry.github.io/sus-fixtures-async-webdriver/
-  funding_uri: https://github.com/sponsors/ioquatix
+  funding_uri: https://github.com/sponsors/ioquatix/
   source_code_uri: https://github.com/socketry/sus-fixtures-async-webdriver.git
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -78,15 +77,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A set of sus fixtures for writing integration tests.
 test_files: []