@quenty/playerutils 8.40.2 → 8.41.1

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [8.41.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/playerutils@8.41.0...@quenty/playerutils@8.41.1) (2026-08-14)
+
+**Note:** Version bump only for package @quenty/playerutils
+
+# [8.41.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/playerutils@8.40.2...@quenty/playerutils@8.41.0) (2026-07-28)
+
+### Features
+
+- Mock player utils + Player mock ([4caed96](https://github.com/Quenty/NevermoreEngine/commit/4caed968ad05b1bce254fbafb0998a7a1b207f29))
+
 ## [8.40.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/playerutils@8.40.1...@quenty/playerutils@8.40.2) (2026-07-27)
 
 **Note:** Version bump only for package @quenty/playerutils

package/deploy.nevermore.json

@@ -0,0 +1,10 @@
+{
+  "targets": {
+    "test": {
+      "universeId": 9716264427,
+      "placeId": 109313722555246,
+      "project": "test/default.project.json",
+      "scriptTemplate": "test/scripts/Server/ServerMain.server.lua"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/playerutils",
-  "version": "8.40.2",
+  "version": "8.41.1",
   "description": "Player utility functions",
   "keywords": [
     "Roblox",
@@ -31,14 +31,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@quenty/brio": "14.35.1",
-    "@quenty/characterutils": "12.40.2",
-    "@quenty/instanceutils": "13.35.1",
-    "@quenty/loader": "10.11.0",
-    "@quenty/maid": "3.11.0",
-    "@quenty/playermock": "1.5.2",
-    "@quenty/promise": "10.23.0",
-    "@quenty/rx": "13.33.0"
+    "@quenty/brio": "14.35.2",
+    "@quenty/characterutils": "12.41.1",
+    "@quenty/instanceutils": "13.35.2",
+    "@quenty/loader": "10.11.1",
+    "@quenty/maid": "3.11.1",
+    "@quenty/nevermore-test-runner": "1.5.1",
+    "@quenty/playermock": "1.6.1",
+    "@quenty/promise": "10.23.1",
+    "@quenty/rx": "13.33.1",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
-  "gitHead": "b2fa2984c2ea6e83136e5a7cbf57b14038d9a265"
+  "gitHead": "f084360c3729ea424d49d9bc42f8f0d1c128fa82"
 }

package/src/Shared/PlayerUtils.lua

@@ -5,6 +5,8 @@
 
 local require = require(script.Parent.loader).load(script)
 
+local Players = game:GetService("Players")
+
 local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
 
@@ -23,10 +25,10 @@ local PlayerUtils = {}
 	@return string -- Formatted name
 ]=]
 function PlayerUtils.formatName(player: Player): string
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
+	assert((typeof(player) == "Instance" and player:IsA("Player")) or PlayerMock.isMock(player), "Bad player")
 
 	local name = player.Name
-	local displayName = player.DisplayName
+	local displayName = if PlayerMock.isMock(player) then PlayerMock.read(player, "DisplayName") else player.DisplayName
 
 	return PlayerUtils.formatDisplayName(name, displayName)
 end
@@ -134,18 +136,20 @@ function PlayerUtils.promiseLoadCharacter(player: Player): Promise.Promise<Model
 	assert((typeof(player) == "Instance" and player:IsA("Player")) or PlayerMock.isMock(player), "Bad player")
 
 	return Promise.spawn(function(resolve, reject)
+		local character: Model?
 		local ok, err = pcall(function()
 			if PlayerMock.isMock(player) then
-				PlayerMock.loadCharacterAsync(player)
+				character = PlayerMock.loadCharacterAsync(player)
 			else
 				player:LoadCharacterAsync()
+				character = player.Character
 			end
 		end)
 		if not ok then
 			return reject(err or "Failed to load character")
 		end
 
-		return resolve()
+		return resolve(character)
 	end)
 end
 
@@ -160,21 +164,32 @@ function PlayerUtils.promiseLoadCharacterWithHumanoidDescription(
 	player: Player,
 	humanoidDescription: HumanoidDescription
 ): Promise.Promise<Model>
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
+	assert((typeof(player) == "Instance" and player:IsA("Player")) or PlayerMock.isMock(player), "Bad player")
 	assert(
 		typeof(humanoidDescription) == "Instance" and humanoidDescription:IsA("HumanoidDescription"),
 		"Bad humanoidDescription"
 	)
 
 	return Promise.spawn(function(resolve, reject)
+		local character: Model?
 		local ok, err = pcall(function()
-			player:LoadCharacterWithHumanoidDescriptionAsync(humanoidDescription)
+			if PlayerMock.isMock(player) then
+				-- The engine builds the rig from the description before spawning it; the mock's spawn
+				-- path takes the built rig, which is the same split the engine call does internally.
+				character = PlayerMock.loadCharacterAsync(
+					player,
+					Players:CreateHumanoidModelFromDescription(humanoidDescription, Enum.HumanoidRigType.R15)
+				)
+			else
+				player:LoadCharacterWithHumanoidDescriptionAsync(humanoidDescription)
+				character = player.Character
+			end
 		end)
 		if not ok then
 			return reject(err or "Failed to load character")
 		end
 
-		return resolve()
+		return resolve(character)
 	end)
 end
 

package/src/Shared/PlayerUtils.spec.lua

@@ -0,0 +1,169 @@
+--!strict
+local require = require(script.Parent.loader).load(script)
+
+local Players = game:GetService("Players")
+
+local Jest = require("Jest")
+local Maid = require("Maid")
+local PlayerMock = require("PlayerMock")
+local PlayerUtils = require("PlayerUtils")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function setup(): any
+	local maid = Maid.new()
+
+	local controller = {
+		newPlayer = function(overrides: { [string]: any }?): Player
+			local player = PlayerMock.new(overrides)
+			player.Parent = Players
+			maid:GiveTask(player)
+			return player
+		end,
+		destroy = function()
+			maid:DoCleaning()
+		end,
+	}
+
+	return controller
+end
+
+describe("PlayerUtils.formatDisplayName", function()
+	it("returns the display name when it matches the username", function()
+		expect(PlayerUtils.formatDisplayName("oot", "oot")).toBe("oot")
+	end)
+
+	it("ignores case when comparing", function()
+		expect(PlayerUtils.formatDisplayName("MARTXN", "martxn")).toBe("martxn")
+	end)
+
+	it("qualifies the display name with the username when they differ", function()
+		expect(PlayerUtils.formatDisplayName("martxn", "oot")).toBe("oot (@martxn)")
+	end)
+end)
+
+describe("PlayerUtils.formatDisplayNameFromUserInfo", function()
+	it("formats without a badge", function()
+		expect(PlayerUtils.formatDisplayNameFromUserInfo({
+			Username = "martxn",
+			DisplayName = "oot",
+			HasVerifiedBadge = false,
+		})).toBe("oot (@martxn)")
+	end)
+
+	it("appends the verified badge", function()
+		expect(PlayerUtils.formatDisplayNameFromUserInfo({
+			Username = "martxn",
+			DisplayName = "oot",
+			HasVerifiedBadge = true,
+		})).toBe(PlayerUtils.addVerifiedBadgeToName("oot (@martxn)"))
+	end)
+
+	it("rejects a malformed userInfo", function()
+		expect(function()
+			PlayerUtils.formatDisplayNameFromUserInfo({ Username = "martxn" } :: any)
+		end).toThrow()
+	end)
+end)
+
+describe("PlayerUtils.getDefaultNameColor", function()
+	it("is stable for the same name", function()
+		expect(PlayerUtils.getDefaultNameColor("oot")).toEqual(PlayerUtils.getDefaultNameColor("oot"))
+	end)
+
+	it("returns a Color3", function()
+		expect(typeof(PlayerUtils.getDefaultNameColor("oot"))).toBe("Color3")
+	end)
+end)
+
+describe("PlayerUtils.formatName", function()
+	it("returns the mock's name when its display name stand-in matches", function()
+		local controller = setup()
+
+		local player = controller.newPlayer({ UserId = 8675309 })
+		expect(PlayerUtils.formatName(player)).toBe(player.Name)
+
+		controller.destroy()
+	end)
+
+	it("qualifies the mock's display name stand-in with its name", function()
+		local controller = setup()
+
+		local player = controller.newPlayer({ UserId = 8675309, DisplayName = "oot" })
+		expect(PlayerUtils.formatName(player)).toBe(string.format("oot (@%s)", player.Name))
+
+		controller.destroy()
+	end)
+
+	it("follows a display name written mid-test", function()
+		local controller = setup()
+
+		local player = controller.newPlayer({ UserId = 8675309 })
+		PlayerMock.write(player, "DisplayName", "oot")
+		expect(PlayerUtils.formatName(player)).toBe(string.format("oot (@%s)", player.Name))
+
+		controller.destroy()
+	end)
+
+	it("rejects an instance that is neither a Player nor a mock", function()
+		expect(function()
+			PlayerUtils.formatName(Instance.new("Folder") :: any)
+		end).toThrow()
+	end)
+end)
+
+describe("PlayerUtils.promiseLoadCharacter", function()
+	it("spawns the mock's character and resolves it", function()
+		local controller = setup()
+
+		local player = controller.newPlayer({ UserId = 8675309 })
+		local outcome, character = PromiseTestUtils.awaitOutcome(PlayerUtils.promiseLoadCharacter(player), 30)
+
+		expect(outcome).toBe("resolved")
+		expect(character).toBe(PlayerMock.read(player, "Character"))
+		expect(character.Parent).toBe(workspace)
+
+		controller.destroy()
+	end)
+
+	it("rejects an instance that is neither a Player nor a mock", function()
+		expect(function()
+			PlayerUtils.promiseLoadCharacter(Instance.new("Folder") :: any)
+		end).toThrow()
+	end)
+end)
+
+describe("PlayerUtils.promiseLoadCharacterWithHumanoidDescription", function()
+	it("spawns a rig built from the description and resolves it", function()
+		local controller = setup()
+
+		local player = controller.newPlayer({ UserId = 8675309 })
+		local description = Instance.new("HumanoidDescription")
+
+		local outcome, character = PromiseTestUtils.awaitOutcome(
+			PlayerUtils.promiseLoadCharacterWithHumanoidDescription(player, description),
+			30
+		)
+
+		expect(outcome).toBe("resolved")
+		expect(character).toBe(PlayerMock.read(player, "Character"))
+		expect(character:FindFirstChildOfClass("Humanoid")).never.toBeNil()
+
+		description:Destroy()
+		controller.destroy()
+	end)
+
+	it("rejects a bad humanoidDescription", function()
+		local controller = setup()
+
+		local player = controller.newPlayer({ UserId = 8675309 })
+		expect(function()
+			PlayerUtils.promiseLoadCharacterWithHumanoidDescription(player, Instance.new("Folder") :: any)
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)

package/src/Shared/RxPlayerUtils.lua

@@ -11,6 +11,8 @@ local Players = game:GetService("Players")
 local Brio = require("Brio")
 local Maid = require("Maid")
 local Observable = require("Observable")
+local PlayerMock = require("PlayerMock")
+local PlayerMockUtils = require("PlayerMockUtils")
 local Rx = require("Rx")
 local RxBrioUtils = require("RxBrioUtils")
 local RxCharacterUtils = require("RxCharacterUtils")
@@ -38,11 +40,17 @@ function RxPlayerUtils.observePlayersBrio(predicate: Rx.Predicate<Player>?): Obs
 			end
 		end
 
+		local function handleRemoving(player: Player)
+			maid[player] = nil
+		end
+
 		maid:GiveTask(Players.PlayerAdded:Connect(handlePlayer))
+		maid:GiveTask(Players.PlayerRemoving:Connect(handleRemoving))
 
-		maid:GiveTask(Players.PlayerRemoving:Connect(function(player)
-			maid[player] = nil
-		end))
+		-- Mocks are invisible to the Players service, so their tag lifecycle is the counterpart of
+		-- the join events, feeding the same handlers.
+		maid:GiveTask(PlayerMock.getMockAddedSignal():Connect(handlePlayer))
+		maid:GiveTask(PlayerMock.getMockRemovingSignal():Connect(handleRemoving))
 
 		for _, player in Players:GetPlayers() do
 			task.spawn(function()
@@ -50,6 +58,12 @@ function RxPlayerUtils.observePlayersBrio(predicate: Rx.Predicate<Player>?): Obs
 			end)
 		end
 
+		for _, player in PlayerMock.getMocks() do
+			task.spawn(function()
+				handlePlayer(player)
+			end)
+		end
+
 		return maid
 	end) :: any
 end
@@ -82,9 +96,20 @@ end
 	@return Observable<Brio<Player>>
 ]=]
 function RxPlayerUtils.observeLocalPlayerBrio(): Observable.Observable<Brio.Brio<Player>>
-	return RxInstanceUtils.observePropertyBrio(Players, "LocalPlayer", function(value)
-		return value ~= nil
-	end)
+	-- Headless tests have no Players.LocalPlayer; a test designates a PlayerMock instead. Observed
+	-- rather than read once, so a designation made after subscribing still resolves.
+	return Rx.combineLatest({
+		real = RxInstanceUtils.observeProperty(Players, "LocalPlayer"),
+		mocked = PlayerMockUtils.observeMockedLocalPlayer(),
+	}):Pipe({
+		Rx.map(function(state: any): Player?
+			return state.real or state.mocked
+		end) :: any,
+		Rx.distinct() :: any,
+		RxBrioUtils.switchToBrio(function(player)
+			return player ~= nil
+		end) :: any,
+	}) :: any
 end
 
 --[=[
@@ -116,6 +141,7 @@ function RxPlayerUtils.observePlayers(predicate: Rx.Predicate<Player>?): Observa
 		end
 
 		maid:GiveTask(Players.PlayerAdded:Connect(handlePlayer))
+		maid:GiveTask(PlayerMock.getMockAddedSignal():Connect(handlePlayer))
 
 		for _, player in Players:GetPlayers() do
 			task.spawn(function()
@@ -123,6 +149,12 @@ function RxPlayerUtils.observePlayers(predicate: Rx.Predicate<Player>?): Observa
 			end)
 		end
 
+		for _, player in PlayerMock.getMocks() do
+			task.spawn(function()
+				handlePlayer(player)
+			end)
+		end
+
 		return maid
 	end) :: any
 end
@@ -136,8 +168,13 @@ end
 function RxPlayerUtils.observeFirstAppearanceLoaded(player: Player): Observable.Observable<()>
 	assert(typeof(player) == "Instance", "Bad player")
 
+	local isMock = PlayerMock.isMock(player)
+
 	return Observable.new(function(sub)
-		if player:HasAppearanceLoaded() then
+		local alreadyLoaded = if isMock
+			then PlayerMock.read(player, "HasAppearanceLoaded")
+			else player:HasAppearanceLoaded()
+		if alreadyLoaded then
 			sub:Fire()
 			sub:Complete()
 			return
@@ -145,18 +182,24 @@ function RxPlayerUtils.observeFirstAppearanceLoaded(player: Player): Observable.
 
 		local maid = Maid.new()
 
+		local characterAppearanceLoaded: RBXScriptSignal<...any> = if isMock
+			then PlayerMock.getSignal(player, "CharacterAppearanceLoaded")
+			else player.CharacterAppearanceLoaded
+
 		-- In case this works
-		maid:GiveTask(player.CharacterAppearanceLoaded:Connect(function()
+		maid:GiveTask(characterAppearanceLoaded:Connect(function()
 			sub:Fire()
 			sub:Complete()
 		end))
 
 		maid:GiveTask(task.spawn(function()
-			while not player:HasAppearanceLoaded() and player:IsDescendantOf(game) do
+			local loaded = false
+			while not loaded and player:IsDescendantOf(game) do
 				task.wait(0.05)
+				loaded = if isMock then PlayerMock.read(player, "HasAppearanceLoaded") else player:HasAppearanceLoaded()
 			end
 
-			if player:HasAppearanceLoaded() then
+			if loaded then
 				sub:Fire()
 				sub:Complete()
 			else

package/src/Shared/RxPlayerUtils.spec.lua

@@ -0,0 +1,391 @@
+--!strict
+local require = require(script.Parent.loader).load(script)
+
+local Players = game:GetService("Players")
+
+local Jest = require("Jest")
+local Maid = require("Maid")
+local PlayerMock = require("PlayerMock")
+local PromiseTestUtils = require("PromiseTestUtils")
+local RxPlayerUtils = require("RxPlayerUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local TEST_USER_ID = 8675309
+
+local function isTestPlayer(player: Player): boolean
+	return PlayerMock.isMock(player) and PlayerMock.read(player, "UserId") == TEST_USER_ID
+end
+
+local function findLivingBrio(brios: { any }, value: any): any
+	for _, brio in brios do
+		if not brio:IsDead() and brio:GetValue() == value then
+			return brio
+		end
+	end
+	return nil
+end
+
+local function contains(values: { any }, value: any): boolean
+	return table.find(values, value) ~= nil
+end
+
+local function setup(): any
+	local maid = Maid.new()
+
+	local controller = {
+		newPlayer = function(overrides: { [string]: any }?): Player
+			local player = PlayerMock.new(overrides or { UserId = TEST_USER_ID })
+			player.Parent = Players
+			maid:GiveTask(player)
+			return player
+		end,
+		designateLocalPlayer = function(player: Player?)
+			PlayerMock.setMockedLocalPlayer(player)
+			maid:GiveTask(function()
+				if player ~= nil and PlayerMock.getMockedLocalPlayer() == player then
+					PlayerMock.setMockedLocalPlayer(nil)
+				end
+			end)
+		end,
+		record = function(observable: any): { any }
+			local values = {}
+			maid:GiveTask(observable:Subscribe(function(value)
+				table.insert(values, value)
+			end))
+			return values
+		end,
+		awaitCount = function(values: { any }, count: number): boolean
+			return PromiseTestUtils.awaitValue(function()
+				return #values >= count
+			end)
+		end,
+		destroy = function()
+			maid:DoCleaning()
+		end,
+	}
+
+	return controller
+end
+
+describe("RxPlayerUtils.observePlayers", function()
+	it("emits a mock that is already in the game", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		local players = controller.record(RxPlayerUtils.observePlayers())
+
+		expect(controller.awaitCount(players, 1)).toBe(true)
+		expect(contains(players, player)).toBe(true)
+
+		controller.destroy()
+	end)
+
+	it("emits a mock that joins after subscribing", function()
+		local controller = setup()
+
+		local players = controller.record(RxPlayerUtils.observePlayers())
+		local player = controller.newPlayer()
+
+		expect(controller.awaitCount(players, 1)).toBe(true)
+		expect(contains(players, player)).toBe(true)
+
+		controller.destroy()
+	end)
+
+	it("skips mocks the predicate rejects", function()
+		local controller = setup()
+
+		local rejected = controller.newPlayer({ UserId = TEST_USER_ID + 1 })
+		local accepted = controller.newPlayer()
+		local players = controller.record(RxPlayerUtils.observePlayers(isTestPlayer))
+
+		expect(controller.awaitCount(players, 1)).toBe(true)
+		expect(contains(players, accepted)).toBe(true)
+		expect(contains(players, rejected)).toBe(false)
+
+		controller.destroy()
+	end)
+end)
+
+describe("RxPlayerUtils.observePlayersBrio", function()
+	it("emits a living brio for a mock already in the game", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		local brios = controller.record(RxPlayerUtils.observePlayersBrio(isTestPlayer))
+
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+		expect(findLivingBrio(brios, player)).never.toBeNil()
+
+		controller.destroy()
+	end)
+
+	it("emits a living brio for a mock that joins after subscribing", function()
+		local controller = setup()
+
+		local brios = controller.record(RxPlayerUtils.observePlayersBrio(isTestPlayer))
+		local player = controller.newPlayer()
+
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+		expect(findLivingBrio(brios, player)).never.toBeNil()
+
+		controller.destroy()
+	end)
+
+	it("kills the brio when the mock is destroyed", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		local brios = controller.record(RxPlayerUtils.observePlayersBrio(isTestPlayer))
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+
+		local brio = findLivingBrio(brios, player)
+		player:Destroy()
+
+		expect(PromiseTestUtils.awaitValue(function()
+			return brio:IsDead()
+		end)).toBe(true)
+
+		controller.destroy()
+	end)
+
+	it("kills the brio when the mock is kicked", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		local brios = controller.record(RxPlayerUtils.observePlayersBrio(isTestPlayer))
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+
+		local brio = findLivingBrio(brios, player)
+		-- A kick unparents rather than destroys, which is what drops the mock out of the game
+		PlayerMock.kick(player, "Kicked by a test")
+
+		expect(PromiseTestUtils.awaitValue(function()
+			return brio:IsDead()
+		end)).toBe(true)
+
+		controller.destroy()
+	end)
+
+	it("skips mocks the predicate rejects", function()
+		local controller = setup()
+
+		local rejected = controller.newPlayer({ UserId = TEST_USER_ID + 1 })
+		controller.newPlayer()
+		local brios = controller.record(RxPlayerUtils.observePlayersBrio(isTestPlayer))
+
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+		expect(findLivingBrio(brios, rejected)).toBeNil()
+
+		controller.destroy()
+	end)
+end)
+
+describe("RxPlayerUtils.observeCharactersBrio", function()
+	it("emits a brio holding the mock's spawned character", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		local brios = controller.record(RxPlayerUtils.observeCharactersBrio())
+		local character = PlayerMock.loadMinimalCharacterAsync(player)
+
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+		expect(findLivingBrio(brios, character)).never.toBeNil()
+
+		controller.destroy()
+	end)
+
+	it("kills the brio when the character despawns", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		local brios = controller.record(RxPlayerUtils.observeCharactersBrio())
+		local character = PlayerMock.loadMinimalCharacterAsync(player)
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+
+		local brio = findLivingBrio(brios, character)
+		PlayerMock.removeCharacter(player)
+
+		expect(PromiseTestUtils.awaitValue(function()
+			return brio:IsDead()
+		end)).toBe(true)
+
+		controller.destroy()
+	end)
+end)
+
+describe("RxPlayerUtils.observeHumanoidsBrio", function()
+	it("emits a brio holding the mock character's humanoid", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		local brios = controller.record(RxPlayerUtils.observeHumanoidsBrio())
+		local character = PlayerMock.loadMinimalCharacterAsync(player)
+
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+		expect(findLivingBrio(brios, character:FindFirstChildOfClass("Humanoid"))).never.toBeNil()
+
+		controller.destroy()
+	end)
+end)
+
+describe("RxPlayerUtils.observeLocalPlayerBrio", function()
+	it("emits nothing while no mock is designated", function()
+		local controller = setup()
+
+		controller.newPlayer()
+		local brios = controller.record(RxPlayerUtils.observeLocalPlayerBrio())
+
+		expect(#brios).toBe(0)
+
+		controller.destroy()
+	end)
+
+	it("emits a living brio for a mock designated before subscribing", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		controller.designateLocalPlayer(player)
+		local brios = controller.record(RxPlayerUtils.observeLocalPlayerBrio())
+
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+		expect(brios[1]:GetValue()).toBe(player)
+
+		controller.destroy()
+	end)
+
+	it("emits a living brio for a mock designated after subscribing", function()
+		local controller = setup()
+
+		local brios = controller.record(RxPlayerUtils.observeLocalPlayerBrio())
+		local player = controller.newPlayer()
+		controller.designateLocalPlayer(player)
+
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+		expect(brios[1]:GetValue()).toBe(player)
+
+		controller.destroy()
+	end)
+
+	it("kills the brio when the designation is cleared", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		controller.designateLocalPlayer(player)
+		local brios = controller.record(RxPlayerUtils.observeLocalPlayerBrio())
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+
+		PlayerMock.setMockedLocalPlayer(nil)
+
+		expect(PromiseTestUtils.awaitValue(function()
+			return brios[1]:IsDead()
+		end)).toBe(true)
+
+		controller.destroy()
+	end)
+end)
+
+describe("RxPlayerUtils.observeLocalPlayerHumanoidBrio", function()
+	it("emits a brio holding the designated mock's humanoid", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		controller.designateLocalPlayer(player)
+		local brios = controller.record(RxPlayerUtils.observeLocalPlayerHumanoidBrio())
+		local character = PlayerMock.loadMinimalCharacterAsync(player)
+
+		expect(controller.awaitCount(brios, 1)).toBe(true)
+		expect(findLivingBrio(brios, character:FindFirstChildOfClass("Humanoid"))).never.toBeNil()
+
+		controller.destroy()
+	end)
+end)
+
+describe("RxPlayerUtils.observeFirstAppearanceLoaded", function()
+	it("does not fire before the mock has spawned", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		local fires = controller.record(RxPlayerUtils.observeFirstAppearanceLoaded(player))
+
+		expect(#fires).toBe(0)
+
+		controller.destroy()
+	end)
+
+	it("fires once the mock spawns", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		local fired = 0
+		local completed = false
+		local maid = Maid.new()
+		maid:GiveTask(RxPlayerUtils.observeFirstAppearanceLoaded(player):Subscribe(
+			function()
+				fired += 1
+			end,
+			nil,
+			function()
+				completed = true
+			end
+		))
+
+		PlayerMock.loadMinimalCharacterAsync(player)
+
+		expect(PromiseTestUtils.awaitValue(function()
+			return fired == 1 and completed
+		end)).toBe(true)
+
+		maid:DoCleaning()
+		controller.destroy()
+	end)
+
+	it("fires immediately when the mock has already spawned", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		PlayerMock.loadMinimalCharacterAsync(player)
+
+		local fired = 0
+		local completed = false
+		local maid = Maid.new()
+		maid:GiveTask(RxPlayerUtils.observeFirstAppearanceLoaded(player):Subscribe(
+			function()
+				fired += 1
+			end,
+			nil,
+			function()
+				completed = true
+			end
+		))
+
+		expect(fired).toBe(1)
+		expect(completed).toBe(true)
+
+		maid:DoCleaning()
+		controller.destroy()
+	end)
+
+	it("fails when the mock leaves before spawning", function()
+		local controller = setup()
+
+		local player = controller.newPlayer()
+		local failure: any = nil
+		local maid = Maid.new()
+		maid:GiveTask(RxPlayerUtils.observeFirstAppearanceLoaded(player):Subscribe(nil, function(err)
+			failure = err
+		end))
+
+		PlayerMock.kick(player, "Kicked by a test")
+
+		expect(PromiseTestUtils.awaitValue(function()
+			return failure ~= nil
+		end)).toBe(true)
+
+		maid:DoCleaning()
+		controller.destroy()
+	end)
+end)

package/src/jest.config.lua

@@ -0,0 +1,3 @@
+return {
+	testMatch = { "**/*.spec" },
+}

package/test/default.project.json

@@ -0,0 +1,25 @@
+{
+  "name": "PlayerUtilsTest",
+  "globIgnorePaths": [
+    "**/.package-lock.json",
+    "**/.pnpm",
+    "**/.pnpm-workspace-state-v1.json",
+    "**/.modules.yaml",
+    "**/.ignored",
+    "**/.ignored_*"
+  ],
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "$properties": {
+        "LoadStringEnabled": true
+      },
+      "playerutils": {
+        "$path": ".."
+      },
+      "Script": {
+        "$path": "scripts/Server"
+      }
+    }
+  }
+}

package/test/scripts/Server/ServerMain.server.lua

@@ -0,0 +1,13 @@
+--[[
+	@class ServerMain
+]]
+local ServerScriptService = game:GetService("ServerScriptService")
+
+local root = ServerScriptService.playerutils
+local loader = root:FindFirstChild("LoaderUtils", true).Parent
+local require = require(loader).bootstrapGame(root)
+
+local NevermoreTestRunnerUtils = require("NevermoreTestRunnerUtils")
+if NevermoreTestRunnerUtils.runTestsIfNeededAsync(root) then
+	return
+end