Add agent context.

Author: ioquatix

.gitignore

@@ -3,3 +3,4 @@
 /gems.locked
 /.covered.db
 /external
+/.context

context/mocking.md

@@ -0,0 +1,95 @@
+# Mocking
+
+There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace method implementations or set up more complex behavior.
+
+Mocking non-local objects permanently changes the object's ancestors, so it should be used with care. For local objects, you can use `let` to define the object and then mock it.
+
+Sus does not support the concept of test doubles, but you can use `receive` and `mock` to achieve similar functionality.
+
+## Method Call Expectations
+
+The `receive(:method)` expectation is used to set up an expectation that a method will be called on an object. You can also specify arguments and return values. However, `receive` is not sequenced, meaning it does not enforce the order of method calls. If you need to enforce the order, use `mock` instead.
+
+```ruby
+describe MyThing do
+	let(:my_thing) {subject.new}
+	
+	it "calls the expected method" do
+		expect(my_thing).to receive(:my_method)
+		
+		expect(my_thing.my_method).to be == 42
+	end
+end
+```
+
+### With Arguments
+
+```ruby
+it "calls the method with arguments" do
+	expect(object).to receive(:method_name).with(arg1, arg2)
+	# or .with_arguments(be == [arg1, arg2])
+	# or .with_options(be == {option1: value1, option2: value2})
+	# or .with_block
+	
+	object.method_name(arg1, arg2)
+end
+```
+
+### Returning Values
+
+```ruby
+it "returns a value" do
+	expect(object).to receive(:method_name).and_return("expected value")
+	result = object.method_name
+	expect(result).to be == "expected value"
+end
+```
+
+### Raising Exceptions
+
+```ruby
+it "raises an exception" do
+	expect(object).to receive(:method_name).and_raise(StandardError, "error message")
+	
+	expect{object.method_name}.to raise_exception(StandardError, message: "error message")
+end
+```
+
+### Multiple Calls
+
+```ruby
+it "calls the method multiple times" do
+	expect(object).to receive(:method_name).twice.and_return("result")
+	# or .with_call_count(be == 2)
+	expect(object.method_name).to be == "result"
+	expect(object.method_name).to be == "result"
+end
+```
+
+## Mock Objects
+
+Mock objects are used to replace method implementations or set up complex behavior. They can be used to intercept method calls, modify arguments, and control the flow of execution. They are thread-local, meaning they only affect the current thread, therefore are not suitable for use in tests that have multiple threads.
+
+```ruby
+describe ApiClient do
+	let(:http_client) {Object.new}
+	let(:client) {ApiClient.new(http_client)}
+	let(:users) {["Alice", "Bob"]}
+	
+	it "makes GET requests" do
+		mock(http_client) do |mock|
+			mock.replace(:get) do |url, headers: {}|
+				expect(url).to be == "/api/users"
+				expect(headers).to be == {"accept" => "application/json"}
+				users.to_json
+			end
+			
+			# or mock.before {|...| ...}
+			# or mock.after {|...| ...}
+			# or mock.wrap(:new) {|original, ...| original.call(...)}
+		end
+		
+		expect(client.fetch_users).to be == users
+	end
+end
+```

context/shared.md

@@ -0,0 +1,185 @@
+# Shared Test Behaviors and Fixtures
+
+## Overview
+
+Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.
+
+When you have common test behaviors that you want to apply to multiple test files, add them to the `fixtures/` directory. When you have common test behaviors that you want to apply to multiple implementations of the same interface, within a single test file, you can define them as shared contexts within that file.
+
+## Shared Fixtures
+
+### Directory Structure
+
+```
+my-gem/
+├── lib/
+│   ├── my_gem.rb
+│   └── my_gem/
+│       └── my_thing.rb
+├── fixtures/
+│   └── my_gem/
+│       └── a_thing.rb               # Provides MyGem::AThing shared context
+└── test/
+    ├── my_gem.rb
+    └── my_gem/
+        └── my_thing.rb
+```
+
+### Creating Shared Fixtures
+
+Create shared behaviors in the `fixtures/` directory using `Sus::Shared`:
+
+```ruby
+# fixtures/my_gem/a_user.rb
+
+require "sus/shared"
+
+module MyGem
+	AUser = Sus::Shared("a user") do |role|
+		let(:user) do
+			{
+				name: "Test User",
+				email: "[email protected]",
+				role: role
+			}
+		end
+		
+		it "has a name" do
+			expect(user[:name]).not.to be_nil
+		end
+		
+		it "has a valid email" do
+			expect(user[:email]).to be(:include?, "@")
+		end
+		
+		it "has a role" do
+			expect(user[:role]).to be_a(String)
+		end
+	end
+end
+```
+
+### Using Shared Fixtures
+
+Require and use shared fixtures in your test files:
+
+```ruby
+# test/my_gem/user_manager.rb
+require 'my_gem/a_user'
+
+describe MyGem::UserManager do
+	it_behaves_like MyGem::AUser, "manager"
+	# or include_context MyGem::AUser, "manager"
+end
+```
+
+### Multiple Shared Fixtures
+
+You can create multiple shared fixtures for different scenarios:
+
+```ruby
+# fixtures/my_gem/users.rb
+module MyGem
+	module Users
+		AStandardUser = Sus::Shared("a standard user") do
+			let(:user) do
+				{ name: "John Doe", role: "user", active: true }
+			end
+			
+			it "is active" do
+				expect(user[:active]).to be_truthy
+			end
+		end
+		
+		AnAdminUser = Sus::Shared("an admin user") do
+			let(:user) do
+				{ name: "Admin User", role: "admin", active: true }
+			end
+			
+			it "has admin role" do
+				expect(user[:role]).to be == "admin"
+			end
+		end
+	end
+end
+```
+
+Use specific shared fixtures:
+
+```ruby
+# test/my_gem/authorization.rb
+require 'my_gem/users'
+
+describe MyGem::Authorization do
+	with "standard user" do
+		# If there are no arguments, you can use `include` directly:
+		include MyGem::Users::AStandardUser
+		
+		it "denies admin access" do
+			auth = subject.new
+			expect(auth.can_admin?(user)).to be_falsey
+		end
+	end
+	
+	with "admin user" do
+		include MyGem::Users::AnAdminUser
+		
+		it "allows admin access" do
+			auth = subject.new
+			expect(auth.can_admin?(user)).to be_truthy
+		end
+	end
+end
+```
+
+### Modules
+
+You can also define shared behaviors in modules and include them in your test files:
+
+```ruby
+# fixtures/my_gem/shared_behaviors.rb
+module MyGem
+	module SharedBehaviors
+		def self.included(base)
+			base.it "uses shared data" do
+				expect(shared_data).to be == "some shared data"
+			end
+		end
+		
+		def shared_data
+			"some shared data"
+		end
+	end
+end
+```
+
+### Enumerating Tests
+
+Some tests will be run multiple times with different arguments (for example, multiple database adapters). You can use `Sus::Shared` to define these tests and then enumerate them:
+
+```ruby
+# test/my_gem/database_adapter.rb
+
+require "sus/shared"
+
+ADatabaseAdapter = Sus::Shared("a database adapter") do |adapter|
+	let(:database) {adapter.new}
+	
+	it "connects to the database" do
+		expect(database.connect).to be_truthy
+	end
+	
+	it "can execute queries" do
+		expect(database.execute("SELECT 1")).to be == [[1]]
+	end
+end
+
+# Enumerate the tests with different adapters
+MyGem::DatabaseAdapters.each do |adapter|
+	describe "with #{adapter}", unique: adapter.name do
+		it_behaves_like ADatabaseAdapter, adapter
+	end
+end
+```
+
+Note the use of `unique: adapter.name` to ensure each test is uniquely identified, which is useful for reporting and debugging - otherwise the same test line number would be used for all iterations, which can make it hard to identify which specific test failed.