sus 0.29.1 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb73658184c73da088c57ee5bb4a86834116fdfb31cccf7a7c93248bac9854c1
-  data.tar.gz: ba96338fe0a444462b1a1d4d5f2c249b84874a7be4431a0aac395427e3e92cb5
+  metadata.gz: c3ef71ae68fa2f1c55825c77c389370bd8903b6888bc1a4034126d945c0d0e0c
+  data.tar.gz: 4abbb662af110be31822445fbb76049a26df539630d68466231dd117bb4ef50b
 SHA512:
-  metadata.gz: 9f6469a0c7d2168a11cf3da899e348db511fba9a019fff95a28079ad0b4fb21639fb14a0883f59d69b4fe992aa326b6a58917b05470ed513ae713b0f9b0340dd
-  data.tar.gz: 81282c2660c353a69d38800e70386fdba27a8f8221d522967a66d442a9be1692c75340c75f4a3bf14b0f774bc8367c5a2f5ac43e281cf01112b4d31d0f232782
+  metadata.gz: c7ccf1055d49fdb0dcb45b4c3cad14c91f325bc0e897018680354cc1a6ae83c5476f7a240370a98569eabb523603d7b2006e3bd028571e82ef8e0138c337cd13
+  data.tar.gz: 49c602c11a456c8eaefcf105e4c135efd18c8c62a3106fc475de03245ce99ace9281d2a246528b0bff96ff153983430748967e4ee7b530e6a91008bbf9044394

data/bin/sus

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 # require 'stackprof'
 # StackProf.start(mode: :wall, interval: 10)

data/bin/sus-host

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'json'
 

data/bin/sus-parallel

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require_relative '../lib/sus/config'
 config = Sus::Config.load

data/bin/sus-tree

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'json'
 

data/lib/sus/base.rb

@@ -16,18 +16,31 @@ module Sus
 			"\#<Sus::Base for #{self.class.description.inspect}>"
 		end
 		
+		# A hook which is called before the test is executed.
+		#
+		# If you override this method, you must call super.
 		def before
 		end
 		
-		def after
+		# A hook which is called after the test is executed.
+		#
+		# If you override this method, you must call super.
+		def after(error = nil)
 		end
 		
-		def around
+		# Wrap logic around the test being executed.
+		#
+		# Invokes the before hook, then the block, then the after hook.
+		#
+		# @yields {...} the block which should execute a test.
+		def around(&block)
 			self.before
 			
-			return yield
+			return block.call
+		rescue => error
+			raise
 		ensure
-			self.after
+			self.after(error)
 		end
 		
 		def assert(...)

data/lib/sus/context.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2023, by Samuel Williams.
+# Copyright, 2021-2024, by Samuel Williams.
 
 require_relative 'assertions'
 require_relative 'identity'
@@ -75,5 +75,56 @@ module Sus
 				end
 			end
 		end
+		
+		# Include an around method to the context class, that invokes the given block before running the test.
+		#
+		# Before hooks are usually invoked in the order they are defined, i.e. the first defined hook is invoked first.
+		#
+		# @parameter hook [Proc] The block to execute before each test.
+		def before(&hook)
+			wrapper = Module.new
+			
+			wrapper.define_method(:before) do
+				super()
+				
+				instance_exec(&hook)
+			end
+			
+			self.include(wrapper)
+		end
+		
+		# Include an around method to the context class, that invokes the given block after running the test.
+		#
+		# After hooks are usually invoked in the reverse order they are defined, i.e. the last defined hook is invoked first.
+		#
+		# @parameter hook [Proc] The block to execute after each test. An `error` argument is passed if the test failed with an exception.
+		def after(&hook)
+			wrapper = Module.new
+			
+			wrapper.define_method(:after) do |error|
+				instance_exec(error, &hook)
+			rescue => error
+				raise
+			ensure
+				super(error)
+			end
+			
+			self.include(wrapper)
+		end
+		
+		# Add an around hook to the context class.
+		#
+		# Around hooks are called in the reverse order they are defined.
+		#
+		# The top level `around` implementation invokes before and after hooks.
+		#
+		# @paremeter block [Proc] The block to execute around each test.
+		def around(&block)
+			wrapper = Module.new
+			
+			wrapper.define_method(:around, &block)
+			
+			self.include(wrapper)
+		end
 	end
 end

data/lib/sus/include_context.rb

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2023, by Samuel Williams.
+# Copyright, 2021-2024, by Samuel Williams.
 
 require_relative 'context'
 
 module Sus
 	module Context
+		# Include a shared context into the current context, along with any arguments or options.
+		#
+		# @parameter shared [Sus::Shared] The shared context to include.
+		# @parameter arguments [Array] The arguments to pass to the shared context.
+		# @parameter options [Hash] The options to pass to the shared context.
 		def include_context(shared, *arguments, **options)
 			self.class_exec(*arguments, **options, &shared.block)
 		end

data/lib/sus/it_behaves_like.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2023, by Samuel Williams.
+# Copyright, 2021-2024, by Samuel Williams.
 
 require_relative 'context'
 
@@ -18,12 +18,12 @@ module Sus
 			base.description = shared.name
 			base.identity = Identity.nested(parent.identity, base.description, unique: unique)
 			base.set_temporary_name("#{self}[#{base.description}]")
-
+			
 			# User provided block is evaluated first, so that it can provide default behaviour for the shared context:
 			if block_given?
 				base.class_exec(*arguments, &block)
 			end
-
+			
 			base.class_exec(*arguments, &shared.block)
 			return base
 		end

data/lib/sus/mock.rb

@@ -82,7 +82,7 @@ module Sus
 	end
 
 	module Mocks
-		def after
+		def after(error = nil)
 			super
 			
 			@mocks&.each_value(&:clear)

data/lib/sus/shared.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2022, by Samuel Williams.
+# Copyright, 2021-2024, by Samuel Williams.
 
 require_relative 'context'
 
@@ -11,13 +11,21 @@ module Sus
 		attr_accessor :block
 		
 		def self.build(name, block)
-			base = Class.new
+			base = Module.new
 			base.extend(Shared)
 			base.name = name
 			base.block = block
 			
 			return base
 		end
+		
+		def included(base)
+			base.class_exec(&self.block)
+		end
+		
+		def prepended(base)
+			base.class_exec(&self.block)
+		end
 	end
 	
 	def self.Shared(name, &block)

data/lib/sus/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2021-2024, by Samuel Williams.
 
 module Sus
-	VERSION = "0.29.1"
+	VERSION = "0.31.0"
 end

data/readme.md

@@ -1,40 +1,33 @@
-# Sus(picious)
+# Sus
 
-An opinionated test framework designed with several goals:
+Sus is a testing framework for Ruby.
 
-  - As fast as possible, aiming for \~10,000 assertions per second per core.
-  - Isolated tests which parallelise easily (including `class` definitions).
-  - Native support for balanced (work-stealing) multi-core execution.
-  - Incredible test output with detailed failure logging (including nested assertions and predicates).
+- It's similar to RSpec but with less baggage and more parallelism.
+- It uses `expect` style syntax with first-class predicates.
+- It has direct [support for code coverage](https://github.com/socketry/covered).
+- It supports the [VSCode Test Runner interface](https://github.com/socketry/sus-vscode).
+- It's based on my experience writing thousands of tests.
+- It's easy to extend (see the `sus-fixtures-` gems for examples).
 
-Non-features:
+[![Development Status](https://github.com/socketry/sus/workflows/Test/badge.svg)](https://github.com/socketry/sus/actions?workflow=Test)
 
-  - Flexibility at the expense of performance.
-  - Backwards compatibility.
+## Lightning Talk: Testing with Sus (2023)
 
-[![Development Status](https://github.com/sus-rb/sus/workflows/Test/badge.svg)](https://github.com/sus-rb/sus/actions?workflow=Test)
+<div align="center">
+  <a href="https://www.youtube.com/watch?v=BDQHgb2rrwU">
+    <img src="https://img.youtube.com/vi/BDQHgb2rrwU/0.jpg" alt="Testing with Sus">
+  </a>
+</div>
 
-## Ideas
-
-I've been thinking about how this should grow long term. I see a separation between "defining tests" and "running tests". I think this gem should be split across those responsibilities. By doing so, defining tests remains relatively static, but can be extended independently of execution model. And execution models which include parallelism, code coverage, multi-server, etc can be implemented effectively.
-
-The key point is that we need a well defined interface between defining tests and running tests. This interface is provided by the test registry, which can load test files. The test registry provides a way to enumerate all tests where each test has an identity that uniquely identifies it.
-
-### Sequential vs Parallel
-
-`sus` has both sequential and multi-threaded (`sus-parallel`) execution models for tests. Parallel execution is potentially much faster. This is an experimental feature.
-
-![Sequential vs Parallel](https://user-images.githubusercontent.com/30030/144770080-092cf07b-b121-4754-96e0-8ff1d8ea0695.mov)
+## Usage
 
-## Installation
+Please see the [project documentation](https://socketry.github.io/sus/) for more details.
 
-``` shell
-bundle add sus
-```
+  - [Getting Started](https://socketry.github.io/sus/guides/getting-started/index) - This guide explains how to use the `sus` gem to write tests for your Ruby projects.
 
-## Usage
+## See Also
 
-Check `test` directory for examples.
+- [sus-vscode](https://github.com/socketry/sus-vscode) - Visual Studio Code extension for Sus.
 
 ## Contributing
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sus
 version: !ruby/object:Gem::Version
-  version: 0.29.1
+  version: 0.31.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -38,7 +38,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-07-17 00:00:00.000000000 Z
+date: 2024-07-28 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -101,13 +101,13 @@ files:
 - lib/sus/with.rb
 - license.md
 - readme.md
-homepage: https://github.com/sus-rb/sus
+homepage: https://github.com/socketry/sus
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://sus-rb.github.io/sus/
+  documentation_uri: https://socketry.github.io/sus/
   funding_uri: https://github.com/sponsors/ioquatix/
-  source_code_uri: https://github.com/sus-rb/sus.git
+  source_code_uri: https://github.com/socketry/sus.git
 post_install_message:
 rdoc_options: []
 require_paths: