@quenty/friendutils 12.32.0 → 12.33.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [12.33.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/friendutils@12.32.0...@quenty/friendutils@12.33.0) (2026-07-23)
+
+### Features
+
+- Add baseline player-mock and support across Nevermore for mocked players. ([567d121](https://github.com/Quenty/NevermoreEngine/commit/567d121ffc014b42391554088189a1a6296dda83))
+
 # [12.32.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/friendutils@12.31.0...@quenty/friendutils@12.32.0) (2026-07-18)
 
 **Note:** Version bump only for package @quenty/friendutils

package/deploy.nevermore.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/friendutils",
-  "version": "12.32.0",
+  "version": "12.33.0",
   "description": "Utlity functions to help find friends of a user. Also contains utility to make testing in studio easier.",
   "keywords": [
     "Roblox",
@@ -28,14 +28,18 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/brio": "14.32.0",
+    "@quenty/brio": "14.33.0",
     "@quenty/loader": "10.11.0",
-    "@quenty/maid": "3.10.0",
-    "@quenty/promise": "10.20.0",
-    "@quenty/rx": "13.30.0"
+    "@quenty/maid": "3.11.0",
+    "@quenty/nevermore-test-runner": "1.5.0",
+    "@quenty/pagesutils": "5.22.0",
+    "@quenty/playermock": "1.1.0",
+    "@quenty/promise": "10.21.0",
+    "@quenty/rx": "13.31.0",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "647acfad93dca41c38f59cda247d2bfc0fff36d4"
+  "gitHead": "1de37218a2bedb8e3f8614a2e09bba9eddc812da"
 }

package/src/Shared/FriendUtils.lua

@@ -8,6 +8,9 @@ local require = require(script.Parent.loader).load(script)
 
 local Players = game:GetService("Players")
 
+local PagesDatabase = require("PagesDatabase")
+local PagesProxy = require("PagesProxy")
+local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
 
 local FriendUtils = {}
@@ -113,6 +116,12 @@ function FriendUtils.promiseFriendPages(userId: number): Promise.Promise<FriendP
 	assert(type(userId) == "number", "Bad userId")
 
 	return Promise.spawn(function(resolve, reject)
+		local mockPlayer = PlayerMock.getMockByUserId(userId)
+		if mockPlayer ~= nil then
+			local friends = PlayerMock.readLookup(mockPlayer, "Players.GetFriendsAsync", 0)
+			return resolve(PagesProxy.new(PagesDatabase.fromPageData({ friends })) :: any)
+		end
+
 		local pages
 		local ok, err = pcall(function()
 			pages = Players:GetFriendsAsync(userId)

package/src/Shared/FriendUtils.spec.lua

@@ -0,0 +1,121 @@
+--!strict
+--[[
+	@class FriendUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Workspace = game:GetService("Workspace")
+
+local FriendUtils = require("FriendUtils")
+local Jest = require("Jest")
+local PagesDatabase = require("PagesDatabase")
+local PagesProxy = require("PagesProxy")
+local PlayerMock = require("PlayerMock")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function makeFriendData(userId: number, isOnline: boolean)
+	return {
+		Id = userId,
+		Username = string.format("friend_%d", userId),
+		DisplayName = string.format("Friend %d", userId),
+		IsOnline = isOnline,
+	}
+end
+
+describe("FriendUtils.promiseAllFriends against a mock", function()
+	it("resolves the injected friends list", function()
+		local player = PlayerMock.new({ UserId = 90041001 })
+		player.Parent = Workspace
+		PlayerMock.writeLookup(player, "Players.GetFriendsAsync", 0, {
+			makeFriendData(90041002, true),
+			makeFriendData(90041003, false),
+		})
+
+		local outcome, friends = PromiseTestUtils.awaitOutcome(FriendUtils.promiseAllFriends(90041001))
+
+		expect(outcome).toBe("resolved")
+		expect(#friends).toBe(2)
+		expect(friends[1].Id).toBe(90041002)
+		expect(friends[1].Username).toBe("friend_90041002")
+		expect(friends[2].IsOnline).toBe(false)
+
+		player:Destroy()
+	end)
+
+	it("resolves an empty list for a mock with no injected friends", function()
+		local player = PlayerMock.new({ UserId = 90041004 })
+		player.Parent = Workspace
+
+		local outcome, friends = PromiseTestUtils.awaitOutcome(FriendUtils.promiseAllFriends(90041004))
+
+		expect(outcome).toBe("resolved")
+		expect(friends).toEqual({})
+
+		player:Destroy()
+	end)
+
+	it("stops at limitMaxFriends", function()
+		local player = PlayerMock.new({ UserId = 90041005 })
+		player.Parent = Workspace
+		PlayerMock.writeLookup(player, "Players.GetFriendsAsync", 0, {
+			makeFriendData(90041006, true),
+			makeFriendData(90041007, true),
+			makeFriendData(90041008, true),
+		})
+
+		local outcome, friends = PromiseTestUtils.awaitOutcome(FriendUtils.promiseAllFriends(90041005, 2))
+
+		expect(outcome).toBe("resolved")
+		expect(#friends).toBe(2)
+
+		player:Destroy()
+	end)
+end)
+
+describe("FriendUtils.iterateFriendsYielding", function()
+	it("iterates across page boundaries", function()
+		local pages = PagesProxy.new(PagesDatabase.fromPageData({
+			{ makeFriendData(90041009, true) },
+			{ makeFriendData(90041010, false) },
+		}))
+
+		local seen = {}
+		for userData in FriendUtils.iterateFriendsYielding(pages :: any) do
+			table.insert(seen, userData.Id)
+		end
+
+		expect(seen).toEqual({ 90041009, 90041010 })
+	end)
+end)
+
+describe("FriendUtils.onlineFriends", function()
+	it("filters to online friends only", function()
+		local friends = {
+			makeFriendData(90041011, true),
+			makeFriendData(90041012, false),
+		}
+
+		local online = FriendUtils.onlineFriends(friends)
+
+		expect(#online).toBe(1)
+		expect(online[1].Id).toBe(90041011)
+	end)
+end)
+
+describe("FriendUtils.friendsNotInGame", function()
+	it("filters out friends whose player is in the game", function()
+		-- Mocks are not in Players:GetPlayers(), so all injected friends count as not in game
+		local friends = {
+			makeFriendData(90041013, true),
+		}
+
+		local notInGame = FriendUtils.friendsNotInGame(friends)
+
+		expect(#notInGame).toBe(1)
+	end)
+end)

package/src/Shared/RxFriendUtils.lua

@@ -7,6 +7,7 @@
 
 local require = require(script.Parent.loader).load(script)
 
+local CollectionService = game:GetService("CollectionService")
 local Players = game:GetService("Players")
 local RunService = game:GetService("RunService")
 local StarterGui = game:GetService("StarterGui")
@@ -14,14 +15,24 @@ local StarterGui = game:GetService("StarterGui")
 local Brio = require("Brio")
 local Maid = require("Maid")
 local Observable = require("Observable")
+local PlayerMock = require("PlayerMock")
 
 local RxFriendUtils = {}
 
+local function getUserId(player: Player): number
+	return if PlayerMock.isMock(player) then PlayerMock.read(player, "UserId") else player.UserId
+end
+
 --[=[
 	Observe friends in the current server (not including the LocalPlayer!), useful for social GUIs.
 	The lifetimes exist for the whole duration another player is a friend and in your server.
 	This means if a player is unfriended + friended multiple times per session, they will have emitted multiple friend lifetimes.
 
+	Works against [PlayerMock] players on either side: mocks in the DataModel are enumerated
+	alongside real players, friendship resolves from the mock's "Player.IsFriendsWithAsync" lookup
+	domain, and a mid-test [PlayerMock.writeLookup] to that domain stands in for the CoreGui
+	friended/unfriended events -- the observable re-reads and emits/kills lifetimes accordingly.
+
 	@param player Player?
 	@return Observable<Brio<Player>>
 ]=]
@@ -30,6 +41,8 @@ function RxFriendUtils.observeFriendsInServerAsBrios(player: Player?): Observabl
 
 	assert(typeof(player) == "Instance", "Bad player")
 
+	local observedPlayer: Player = player :: Player
+
 	-- Note that 'PlayerFriendedEvent' and 'PlayerUnfriendedEvent' are currently unreliable.
 	-- See: https://devforum.roblox.com/t/getcores-playerfriendedevent-and-playerunfriendedevent-bindableevents-firing-at-inappropriate-times/570403/4
 	-- Due to players initially starting with an 'unknown' friend value, they fire for all players in the game at launch, and on the first time another player that joins the server.
@@ -38,6 +51,11 @@ function RxFriendUtils.observeFriendsInServerAsBrios(player: Player?): Observabl
 	return Observable.new(function(sub)
 		local maid = Maid.new()
 
+		-- Per-otherPlayer wiring (mock friendship-changed connections). Separate from the brio keyed
+		-- under maid[otherPlayer]: an unfriend kills the brio but the wiring must survive so a
+		-- re-friend emits a new lifetime. Both die together when the other player leaves.
+		local listenMaid = maid:Add(Maid.new())
+
 		local function handleFriendState(otherPlayer: Player, isFriendsWith: boolean)
 			if otherPlayer == Players.LocalPlayer then
 				return
@@ -57,45 +75,91 @@ function RxFriendUtils.observeFriendsInServerAsBrios(player: Player?): Observabl
 		end
 
 		local function handleNewPlayerAsync(otherPlayer: Player)
-			if otherPlayer ~= player then
-				local isFriendsWith = false
-				local ok = pcall(function()
-					isFriendsWith = player:IsFriendsWithAsync(otherPlayer.UserId)
-				end)
-				if not ok then
-					warn(
-						string.format(
-							"[RxFriendUtils.observeFriendsInServerAsBrios] Couldn't get friendship status with %q!",
-							otherPlayer.Name
-						)
-					)
+			if otherPlayer == observedPlayer then
+				return
+			end
 
-					-- If the call failed, then 'isFriendsWith' will be nil.
-					-- We'll assume that this player isn't a friend on failure.
-					handleFriendState(otherPlayer, false)
-					return
+			-- Friendship is symmetric, so with only one side mocked the injected state lives on
+			-- whichever player is the mock; with both mocked, on the observed player.
+			local lookupMock: Player? = nil
+			local lookupKey: number? = nil
+			if PlayerMock.isMock(observedPlayer) then
+				lookupMock = observedPlayer
+				lookupKey = getUserId(otherPlayer)
+			elseif PlayerMock.isMock(otherPlayer) then
+				lookupMock = otherPlayer
+				lookupKey = getUserId(observedPlayer)
+			end
+
+			if lookupMock ~= nil and lookupKey ~= nil then
+				local mock: Player, key: number = lookupMock, lookupKey
+
+				local function readFriendState()
+					handleFriendState(otherPlayer, PlayerMock.readLookup(mock, "Player.IsFriendsWithAsync", key))
 				end
 
-				handleFriendState(otherPlayer, isFriendsWith)
+				-- The lookup attribute's changed signal stands in for the CoreGui friended /
+				-- unfriended events below, which only the engine can fire.
+				listenMaid[otherPlayer] = PlayerMock.getLookupChangedSignal(mock, "Player.IsFriendsWithAsync", key)
+					:Connect(readFriendState)
+
+				readFriendState()
+				return
 			end
+
+			local isFriendsWith = false
+			local ok = pcall(function()
+				isFriendsWith = observedPlayer:IsFriendsWithAsync(getUserId(otherPlayer))
+			end)
+			if not ok then
+				warn(
+					string.format(
+						"[RxFriendUtils.observeFriendsInServerAsBrios] Couldn't get friendship status with %q!",
+						otherPlayer.Name
+					)
+				)
+
+				-- If the call failed, then 'isFriendsWith' will be nil.
+				-- We'll assume that this player isn't a friend on failure.
+				handleFriendState(otherPlayer, false)
+				return
+			end
+
+			handleFriendState(otherPlayer, isFriendsWith)
 		end
 
-		-- Handle players leaving / joining.
-		maid:GiveTask(Players.PlayerRemoving:Connect(function(otherPlayer: Player)
+		local function handlePlayerRemoving(otherPlayer: Player)
+			listenMaid[otherPlayer] = nil
 			maid[otherPlayer] = nil
-		end))
+		end
+
+		-- Handle players leaving / joining.
+		maid:GiveTask(Players.PlayerRemoving:Connect(handlePlayerRemoving))
 		maid:GiveTask(Players.PlayerAdded:Connect(handleNewPlayerAsync))
 
+		-- Mocks never appear in Players:GetPlayers()/PlayerAdded; enumerate them through their tag,
+		-- mirroring the DataModel-scoped engine calls (see [PlayerMock.TAG]).
+		maid:GiveTask(CollectionService:GetInstanceAddedSignal(PlayerMock.TAG):Connect(function(instance)
+			handleNewPlayerAsync((instance :: any) :: Player)
+		end))
+		maid:GiveTask(CollectionService:GetInstanceRemovedSignal(PlayerMock.TAG):Connect(function(instance)
+			handlePlayerRemoving((instance :: any) :: Player)
+		end))
+
 		for _, otherPlayer in Players:GetPlayers() do
 			task.spawn(handleNewPlayerAsync, otherPlayer)
 		end
 
+		for _, tagged in CollectionService:GetTagged(PlayerMock.TAG) do
+			task.spawn(handleNewPlayerAsync, (tagged :: any) :: Player)
+		end
+
 		-- Handle changes for players already in this server.
 		-- There's a non-zero chance these get removed someday... :(
 		-- https://devforum.roblox.com/t/playerfriendedevent-was-deleted-from-corescripts/696683
 		-- So just incase these connections throw, use a new thread so we don't error out the whole observable.
 		-- Only allow this while the game is running too
-		if player == Players.LocalPlayer and RunService:IsRunning() then
+		if observedPlayer == Players.LocalPlayer and RunService:IsRunning() then
 			task.spawn(function()
 				maid:GiveTask(StarterGui:GetCore("PlayerFriendedEvent").Event:Connect(function(otherPlayer: Player)
 					handleFriendState(otherPlayer, true)

package/src/Shared/RxFriendUtils.spec.lua

@@ -0,0 +1,133 @@
+--!strict
+--[[
+	@class RxFriendUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Workspace = game:GetService("Workspace")
+
+local Brio = require("Brio")
+local Jest = require("Jest")
+local Maid = require("Maid")
+local PlayerMock = require("PlayerMock")
+local RxFriendUtils = require("RxFriendUtils")
+
+local afterEach = Jest.Globals.afterEach
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("RxFriendUtils.observeFriendsInServerAsBrios", function()
+	local maid = Maid.new()
+
+	afterEach(function()
+		maid:DoCleaning()
+	end)
+
+	local function makeMock(userId: number): Player
+		local player = PlayerMock.new({ UserId = userId })
+		player.Parent = Workspace
+		maid:GiveTask(player)
+		return player
+	end
+
+	local function trackBrios(observer: Player): { Brio.Brio<Player> }
+		local emissions: { Brio.Brio<Player> } = {}
+		maid:GiveTask(RxFriendUtils.observeFriendsInServerAsBrios(observer):Subscribe(function(brio)
+			table.insert(emissions, brio)
+		end))
+		return emissions
+	end
+
+	it("emits an initial lifetime for a mock that is already a friend", function()
+		local observer = makeMock(90051001)
+		local friend = makeMock(90051002)
+		PlayerMock.writeLookup(observer, "Player.IsFriendsWithAsync", 90051002, true)
+
+		local emissions = trackBrios(observer)
+
+		expect(#emissions).toBe(1)
+		expect(emissions[1]:GetValue()).toBe(friend)
+		expect(emissions[1]:IsDead()).toBe(false)
+	end)
+
+	it("emits nothing when no mock is a friend", function()
+		local observer = makeMock(90051003)
+		makeMock(90051004)
+
+		local emissions = trackBrios(observer)
+
+		expect(#emissions).toBe(0)
+	end)
+
+	it("emits when friendship is written mid-test and kills the lifetime on unfriend", function()
+		local observer = makeMock(90051005)
+		local friend = makeMock(90051006)
+
+		local emissions = trackBrios(observer)
+		expect(#emissions).toBe(0)
+
+		PlayerMock.writeLookup(observer, "Player.IsFriendsWithAsync", 90051006, true)
+		expect(#emissions).toBe(1)
+		expect(emissions[1]:GetValue()).toBe(friend)
+
+		PlayerMock.writeLookup(observer, "Player.IsFriendsWithAsync", 90051006, false)
+		expect(emissions[1]:IsDead()).toBe(true)
+	end)
+
+	it("emits a fresh lifetime per re-friend", function()
+		local observer = makeMock(90051007)
+		makeMock(90051008)
+
+		local emissions = trackBrios(observer)
+
+		PlayerMock.writeLookup(observer, "Player.IsFriendsWithAsync", 90051008, true)
+		PlayerMock.writeLookup(observer, "Player.IsFriendsWithAsync", 90051008, false)
+		PlayerMock.writeLookup(observer, "Player.IsFriendsWithAsync", 90051008, true)
+
+		expect(#emissions).toBe(2)
+		expect(emissions[1]:IsDead()).toBe(true)
+		expect(emissions[2]:IsDead()).toBe(false)
+	end)
+
+	it("does not emit a duplicate lifetime for a repeated friended signal", function()
+		local observer = makeMock(90051009)
+		makeMock(90051010)
+		PlayerMock.writeLookup(observer, "Player.IsFriendsWithAsync", 90051010, true)
+
+		local emissions = trackBrios(observer)
+
+		-- The CoreGui friended event this wiring stands in for can fire repeatedly; a re-write of
+		-- the same state must not open a second lifetime.
+		PlayerMock.writeLookup(observer, "Player.IsFriendsWithAsync", 90051010, true)
+
+		expect(#emissions).toBe(1)
+	end)
+
+	it("emits for a friend mock that joins after subscription", function()
+		local observer = makeMock(90051011)
+		PlayerMock.writeLookup(observer, "Player.IsFriendsWithAsync", 90051012, true)
+
+		local emissions = trackBrios(observer)
+		expect(#emissions).toBe(0)
+
+		local friend = makeMock(90051012)
+
+		expect(#emissions).toBe(1)
+		expect(emissions[1]:GetValue()).toBe(friend)
+	end)
+
+	it("kills the lifetime when the friend mock leaves", function()
+		local observer = makeMock(90051013)
+		local friend = makeMock(90051014)
+		PlayerMock.writeLookup(observer, "Player.IsFriendsWithAsync", 90051014, true)
+
+		local emissions = trackBrios(observer)
+		expect(#emissions).toBe(1)
+
+		friend:Destroy()
+
+		expect(emissions[1]:IsDead()).toBe(true)
+	end)
+end)

package/src/jest.config.lua

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

package/test/default.project.json

@@ -0,0 +1,17 @@
+{
+  "name": "FriendUtilsTest",
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "$properties": {
+        "LoadStringEnabled": true
+      },
+      "friendutils": {
+        "$path": ".."
+      },
+      "Script": {
+        "$path": "scripts/Server"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,12 @@
+--!nonstrict
+local ServerScriptService = game:GetService("ServerScriptService")
+
+local root = ServerScriptService.friendutils
+local loader = root:FindFirstChild("LoaderUtils", true).Parent
+local require = require(loader).bootstrapGame(root)
+
+local NevermoreTestRunnerUtils = require("NevermoreTestRunnerUtils")
+
+if NevermoreTestRunnerUtils.runTestsIfNeededAsync(root) then
+	return
+end