@quenty/binder 14.40.0 → 14.41.0

package/src/Shared/Binder.spec.lua

@@ -1,155 +1,25 @@
 --!strict
 --[[
-	Comprehensive coverage for Binder.
-
-	Runtime binders are booted the way production code boots them: registered on a BinderProvider
-	that is initialized and started through a ServiceBag, and torn down through serviceBag:Destroy().
-	Adornees are parented into a workspace container because CollectionService.GetInstanceAddedSignal
-	only fires for instances that live in the DataModel. A bind that happens after :Start() is awaited
-	event-driven through `binder:Promise(inst):Yield()`, never a fixed sleep. Tags are global and the
-	test place is shared across a batch run, so every test uses a distinct tag and cleans up after
-	itself.
-
-	A handful of tests exercise Binder's standalone lifecycle contract (:new/:Init/:Start guards,
-	:Create) and construct the binder directly -- there is no other way to assert, for example, that
-	:Start() is idempotent when called twice by hand.
-
 	@class Binder.spec.lua
 ]]
 
 local require = require(script.Parent.loader).load(script)
 
 local Binder = require("Binder")
-local BinderProvider = require("BinderProvider")
+local BinderTestUtils = require("BinderTestUtils")
 local Jest = require("Jest")
-local ServiceBag = require("ServiceBag")
 
 local describe = Jest.Globals.describe
 local expect = Jest.Globals.expect
 local it = Jest.Globals.it
 
-local specCounter = 0
-
--- A minimal bound class that records its instance and whether it was destroyed. It deliberately
--- does NOT retain its constructor varargs: the ServiceBag is injected as a constructor arg, and its
--- object graph contains Quenty Signals whose strict __index makes jest's deep-equality traversal
--- throw. Keeping the class free of them lets toEqual compare instances safely.
-local function makeTrackingClass()
-	local Class = {}
-	Class.__index = Class
-	Class.ClassName = "TrackingClass"
-
-	function Class.new(inst)
-		local self = setmetatable({}, Class)
-		self.instance = inst
-		self.destroyed = false
-		return self
-	end
-
-	function Class:Destroy()
-		self.destroyed = true
-	end
-
-	return Class
-end
-
--- Returns once `inst` is no longer bound. CollectionService tag removal is synchronous here, so the
--- class is usually already gone by the time we check; the guarded wait also covers a deferred case.
-local function awaitUnbound(binder, inst)
-	if binder:Get(inst) ~= nil then
-		binder:GetClassRemovedSignal():Wait()
-	end
-end
-
--- A no-op constructor that still returns a value, so Binder's generic bound type stays inhabited.
-local function noopConstructor()
-	return {}
-end
-
-local function setup()
-	specCounter += 1
-	local suffix = specCounter
-
-	local serviceBag = ServiceBag.new()
-	local serviceBagDestroyed = false
-
-	local container = Instance.new("Folder")
-	container.Name = "BinderSpecContainer"
-	container.Parent = workspace
-
-	local instances = {}
-	local pendingBinders: { any } = {}
-	local extraTagCounter = 0
-	local booted = false
-
-	local function uniqueTag(): string
-		extraTagCounter += 1
-		return string.format("BinderSpecTag_%d_%d", suffix, extraTagCounter)
-	end
-
-	-- Registers a binder to be booted by boot(); returns the binder so the test can tag/query it.
-	-- The constructor is intentionally untyped (any) so per-test generic inference does not leak
-	-- into this shared helper.
-	local function addBinder(constructor: any, ...): Binder.Binder<any>
-		assert(not booted, "Cannot add a binder after boot()")
-		local binder = Binder.new(uniqueTag(), constructor, ...)
-		table.insert(pendingBinders, binder)
-		return binder
-	end
-
-	-- Boots the registered binders through a ServiceBag, exactly as production code does.
-	local function boot()
-		assert(not booted, "Already booted")
-		booted = true
-
-		local binders = pendingBinders
-		local provider = BinderProvider.new(string.format("BinderSpecProvider_%d", suffix), function(self)
-			for _, binder in binders do
-				self:Add(binder)
-			end
-		end)
-
-		serviceBag:GetService(provider)
-		serviceBag:Init()
-		serviceBag:Start()
-	end
-
-	local function newInstance(parent: Instance?, className: string?): Instance
-		local inst = Instance.new(className or "Folder")
-		inst.Parent = parent or container
-		table.insert(instances, inst)
-		return inst
-	end
-
-	local function destroyServiceBag()
-		if not serviceBagDestroyed then
-			serviceBagDestroyed = true
-			serviceBag:Destroy()
-		end
-	end
-
-	return {
-		container = container,
-		uniqueTag = uniqueTag,
-		addBinder = addBinder,
-		boot = boot,
-		newInstance = newInstance,
-		destroyServiceBag = destroyServiceBag,
-		destroy = function()
-			destroyServiceBag()
-			for _, inst in instances do
-				pcall(function()
-					inst:Destroy()
-				end)
-			end
-			container:Destroy()
-		end,
-	}
-end
+local setup = BinderTestUtils.setup
+local makeTrackingClass = BinderTestUtils.makeTrackingClass
+local awaitUnbound = BinderTestUtils.awaitUnbound
+local noopConstructor = BinderTestUtils.noopConstructor
 
 describe("Binder.new()", function()
 	it("constructs a binder", function()
-		-- Never Init'd/Started, so it holds no resources and needs no teardown.
 		local binder = Binder.new("BinderNewSpecTag", noopConstructor)
 		expect(Binder.isBinder(binder)).toEqual(true)
 	end)
@@ -173,16 +43,14 @@ describe("Binder.new()", function()
 	end)
 
 	it("captures variadic constructor args", function()
-		local env = setup()
+		local controller = setup()
 
-		-- Explicit .new()-time args take precedence over the ServiceBag that Init would otherwise
-		-- inject, so this class only ever captures the "a"/"b" passed here.
-		local binder = env.addBinder(function(_inst, a, b)
+		local binder = controller.addBinder(function(_inst, a, b)
 			return { a = a, b = b }
 		end, "a", "b")
-		env.boot()
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Tag(inst)
 
 		local ok, class = binder:Promise(inst):Yield()
@@ -190,7 +58,7 @@ describe("Binder.new()", function()
 		expect(class.a).toEqual("a")
 		expect(class.b).toEqual("b")
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
@@ -226,14 +94,14 @@ end)
 
 describe("Binder constructor variants", function()
 	it("supports a plain function constructor", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(function(inst)
+		local binder = controller.addBinder(function(inst)
 			return { instance = inst, kind = "function" }
 		end)
-		env.boot()
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Tag(inst)
 
 		local ok, class = binder:Promise(inst):Yield()
@@ -241,45 +109,45 @@ describe("Binder constructor variants", function()
 		expect(class.kind).toEqual("function")
 		expect(class.instance).toEqual(inst)
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("supports a class table with .new", function()
-		local env = setup()
+		local controller = setup()
 
 		local Class = makeTrackingClass()
-		local binder = env.addBinder(Class)
-		env.boot()
+		local binder = controller.addBinder(Class)
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Tag(inst)
 
 		local ok, class = binder:Promise(inst):Yield()
 		assert(ok, "Never bound")
 		expect(class.instance).toEqual(inst)
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("supports a provider table with :Create", function()
-		local env = setup()
+		local controller = setup()
 
 		local provider = {}
 		function provider.Create(_self, inst)
 			return { instance = inst, kind = "provider" }
 		end
 
-		local binder = env.addBinder(provider :: any)
-		env.boot()
+		local binder = controller.addBinder(provider :: any)
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Tag(inst)
 
 		local ok, class = binder:Promise(inst):Yield()
 		assert(ok, "Never bound")
 		expect(class.kind).toEqual("provider")
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
@@ -312,88 +180,87 @@ end)
 
 describe("Binder binding via ServiceBag", function()
 	it("binds instances tagged before start", function()
-		local env = setup()
+		local controller = setup()
 
 		local Class = makeTrackingClass()
-		local binder = env.addBinder(Class)
+		local binder = controller.addBinder(Class)
 
-		local inst = env.newInstance()
-		binder:Tag(inst) -- tag before the service bag starts the binder
+		local inst = controller.newInstance()
+		binder:Tag(inst)
 
-		env.boot()
+		controller.boot()
 
-		-- Pre-tagged instances bind synchronously as the binder starts.
 		expect(binder:Get(inst)).never.toBeNil()
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("binds instances tagged after start", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(makeTrackingClass())
-		env.boot()
+		local binder = controller.addBinder(makeTrackingClass())
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Tag(inst)
 
 		local ok = binder:Promise(inst):Yield()
 		expect(ok).toEqual(true)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("Binder:Get()", function()
 	it("returns nil for an unbound instance", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(function() end)
-		env.boot()
+		local binder = controller.addBinder(function() end)
+		controller.boot()
 
-		expect(binder:Get(env.newInstance())).toBeNil()
+		expect(binder:Get(controller.newInstance())).toBeNil()
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("throws when passed a non-instance", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(function() end)
-		env.boot()
+		local binder = controller.addBinder(function() end)
+		controller.boot()
 
 		expect(function()
 			binder:Get(5 :: any)
 		end).toThrow()
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("Binder tagging", function()
 	it("Tag/HasTag/Untag manage the collection service tag", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(function() end)
-		env.boot()
+		local binder = controller.addBinder(function() end)
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		expect(binder:HasTag(inst)).toEqual(false)
 		binder:Tag(inst)
 		expect(binder:HasTag(inst)).toEqual(true)
 		binder:Untag(inst)
 		expect(binder:HasTag(inst)).toEqual(false)
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("Bind tags and Unbind untags on the server", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(makeTrackingClass())
-		env.boot()
+		local binder = controller.addBinder(makeTrackingClass())
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Bind(inst)
 		expect(binder:HasTag(inst)).toEqual(true)
 
@@ -403,7 +270,7 @@ describe("Binder tagging", function()
 		binder:Unbind(inst)
 		expect(binder:HasTag(inst)).toEqual(false)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
@@ -439,13 +306,13 @@ end)
 
 describe("Binder:GetAll() / GetAllSet()", function()
 	it("tracks every bound class", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(makeTrackingClass())
-		env.boot()
+		local binder = controller.addBinder(makeTrackingClass())
+		controller.boot()
 
-		local instA = env.newInstance()
-		local instB = env.newInstance()
+		local instA = controller.newInstance()
+		local instB = controller.newInstance()
 		binder:Tag(instA)
 		binder:Tag(instB)
 
@@ -458,29 +325,29 @@ describe("Binder:GetAll() / GetAllSet()", function()
 		expect(set[binder:Get(instA)]).toEqual(true)
 		expect(set[binder:Get(instB)]).toEqual(true)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("Binder signals", function()
 	it("memoizes the added/removing/removed signals", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(function() end)
-		env.boot()
+		local binder = controller.addBinder(function() end)
+		controller.boot()
 
 		expect(binder:GetClassAddedSignal()).toEqual(binder:GetClassAddedSignal())
 		expect(binder:GetClassRemovingSignal()).toEqual(binder:GetClassRemovingSignal())
 		expect(binder:GetClassRemovedSignal()).toEqual(binder:GetClassRemovedSignal())
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("fires the added signal with the class and instance", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(makeTrackingClass())
-		env.boot()
+		local binder = controller.addBinder(makeTrackingClass())
+		controller.boot()
 
 		local firedClass, firedInst
 		binder:GetClassAddedSignal():Connect(function(class, inst)
@@ -488,21 +355,21 @@ describe("Binder signals", function()
 			firedInst = inst
 		end)
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Tag(inst)
 		assert((binder:Promise(inst):Yield()), "Never bound")
 
 		expect(firedInst).toEqual(inst)
 		expect(firedClass).toEqual(binder:Get(inst))
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("fires removing then removed on unbind", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(makeTrackingClass())
-		env.boot()
+		local binder = controller.addBinder(makeTrackingClass())
+		controller.boot()
 
 		local order = {}
 		binder:GetClassRemovingSignal():Connect(function()
@@ -512,7 +379,7 @@ describe("Binder signals", function()
 			table.insert(order, "removed")
 		end)
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Tag(inst)
 		assert((binder:Promise(inst):Yield()), "Never bound")
 
@@ -522,16 +389,16 @@ describe("Binder signals", function()
 		expect(order[1]).toEqual("removing")
 		expect(order[2]).toEqual("removed")
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("destroys the bound class when it is removed", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(makeTrackingClass())
-		env.boot()
+		local binder = controller.addBinder(makeTrackingClass())
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Tag(inst)
 		local ok, class = binder:Promise(inst):Yield()
 		assert(ok, "Never bound")
@@ -541,18 +408,18 @@ describe("Binder signals", function()
 
 		expect(class.destroyed).toEqual(true)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("Binder:ObserveInstance()", function()
 	it("fires with the class on bind and nil on unbind", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(makeTrackingClass())
-		env.boot()
+		local binder = controller.addBinder(makeTrackingClass())
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 
 		-- Wrap each emission so a nil value is still recorded (table.insert(t, nil) is a no-op).
 		local emissions = {}
@@ -573,16 +440,16 @@ describe("Binder:ObserveInstance()", function()
 
 		cleanup()
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("returns a cleanup that stops future callbacks", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(makeTrackingClass())
-		env.boot()
+		local binder = controller.addBinder(makeTrackingClass())
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 
 		local count = 0
 		local cleanup = binder:ObserveInstance(inst, function()
@@ -595,34 +462,34 @@ describe("Binder:ObserveInstance()", function()
 
 		expect(count).toEqual(0)
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("throws for a non-instance or non-function", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(function() end)
-		env.boot()
+		local binder = controller.addBinder(function() end)
+		controller.boot()
 
 		expect(function()
 			binder:ObserveInstance(5 :: any, function() end)
 		end).toThrow()
 		expect(function()
-			binder:ObserveInstance(env.newInstance(), 5 :: any)
+			binder:ObserveInstance(controller.newInstance(), 5 :: any)
 		end).toThrow()
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("Binder:Observe()", function()
 	it("emits the current value on subscribe and updates on bind", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(makeTrackingClass())
-		env.boot()
+		local binder = controller.addBinder(makeTrackingClass())
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 
 		-- Wrap each emission so the initial nil value is still recorded.
 		local emissions = {}
@@ -630,7 +497,6 @@ describe("Binder:Observe()", function()
 			table.insert(emissions, { value = class })
 		end)
 
-		-- First emission is the (nil) current value.
 		expect(#emissions).toEqual(1)
 		expect(emissions[1].value).toBeNil()
 
@@ -641,81 +507,80 @@ describe("Binder:Observe()", function()
 		expect(emissions[2].value).toEqual(binder:Get(inst))
 
 		sub:Destroy()
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("Binder:Promise()", function()
 	it("resolves immediately when already bound", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(makeTrackingClass())
+		local binder = controller.addBinder(makeTrackingClass())
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Tag(inst)
-		env.boot()
+		controller.boot()
 
 		local promise = binder:Promise(inst)
 		expect(promise:IsFulfilled()).toEqual(true)
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("throws when passed a non-instance", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(function() end)
-		env.boot()
+		local binder = controller.addBinder(function() end)
+		controller.boot()
 
 		expect(function()
 			binder:Promise(5 :: any)
 		end).toThrow()
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("Binder:_add() dedupe", function()
 	it("does not rebind an already-bound instance", function()
-		local env = setup()
+		local controller = setup()
 
 		local constructed = 0
-		local binder = env.addBinder(function(inst)
+		local binder = controller.addBinder(function(inst)
 			constructed += 1
 			return { instance = inst }
 		end)
-		env.boot()
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Tag(inst)
 		assert((binder:Promise(inst):Yield()), "Never bound")
 
-		-- Re-tagging an already-tagged instance must not reconstruct.
 		binder:Tag(inst)
 		task.wait()
 
 		expect(constructed).toEqual(1)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("Binder teardown", function()
 	it("removes and destroys all bound classes when the service bag is destroyed", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.addBinder(makeTrackingClass())
-		env.boot()
+		local binder = controller.addBinder(makeTrackingClass())
+		controller.boot()
 
-		local inst = env.newInstance()
+		local inst = controller.newInstance()
 		binder:Tag(inst)
 		local ok, class = binder:Promise(inst):Yield()
 		assert(ok, "Never bound")
 
-		env.destroyServiceBag()
+		controller.destroyServiceBag()
 
 		expect(class.destroyed).toEqual(true)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)