@quenty/grouputils 10.22.0 → 10.23.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.
 
+## [10.23.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/grouputils@10.23.0...@quenty/grouputils@10.23.1) (2026-07-23)
+
+**Note:** Version bump only for package @quenty/grouputils
+
+# [10.23.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/grouputils@10.22.0...@quenty/grouputils@10.23.0) (2026-07-23)
+
+### Features
+
+- Add baseline player-mock and support across Nevermore for mocked players. ([567d121](https://github.com/Quenty/NevermoreEngine/commit/567d121ffc014b42391554088189a1a6296dda83))
+
 # [10.22.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/grouputils@10.21.0...@quenty/grouputils@10.22.0) (2026-07-18)
 
 **Note:** Version bump only for package @quenty/grouputils

package/deploy.nevermore.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/grouputils",
-  "version": "10.22.0",
+  "version": "10.23.1",
   "description": "Group utility functions for Roblox",
   "keywords": [
     "Roblox",
@@ -30,10 +30,13 @@
   ],
   "dependencies": {
     "@quenty/loader": "10.11.0",
-    "@quenty/promise": "10.20.0"
+    "@quenty/nevermore-test-runner": "1.5.0",
+    "@quenty/playermock": "1.1.1",
+    "@quenty/promise": "10.21.0",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "647acfad93dca41c38f59cda247d2bfc0fff36d4"
+  "gitHead": "5ea0583dedebba6492f9ac6d719d32b45c5543fa"
 }

package/src/Shared/GroupTestUtils.lua

@@ -0,0 +1,66 @@
+--!strict
+--[=[
+	Helpers for injecting group membership onto a [PlayerMock] in tests.
+
+	[GroupUtils] answers rank and role from two engine calls -- `GetRolesInGroupAsync`
+	(primary) and `GetGroupsAsync` (fallback) -- and only those calls are intercepted for
+	mocks, so its parsing and fallback logic runs for real in tests. [GroupTestUtils.assignGroupInfo]
+	writes both injected results from one rank/role pair so the answer is coherent whichever
+	path production code takes.
+
+	@class GroupTestUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local PlayerMock = require("PlayerMock")
+
+local GroupTestUtils = {}
+
+export type AssignedGroupInfo = {
+	rank: number,
+	role: string,
+}
+
+--[=[
+	Injects membership in a group for a mock at both engine calls [GroupUtils] reads, replacing
+	any earlier assignment for the same group. Assign multiple groups by calling once per group.
+
+	```lua
+	GroupTestUtils.assignGroupInfo(playerMock, 372, { rank = 230, role = "Admin" })
+	-- GroupUtils.promiseRankInGroup(playerMock, 372) resolves 230,
+	-- promiseRoleInGroup(playerMock, 372) resolves "Admin"
+	```
+
+	@param player Player -- must be a PlayerMock
+	@param groupId number
+	@param groupInfo { rank: number, role: string }
+]=]
+function GroupTestUtils.assignGroupInfo(player: Player, groupId: number, groupInfo: AssignedGroupInfo)
+	assert(PlayerMock.isMock(player), "Not a PlayerMock")
+	assert(type(groupId) == "number", "Bad groupId")
+	assert(type(groupInfo) == "table", "Bad groupInfo")
+	assert(type(groupInfo.rank) == "number", "Bad groupInfo.rank")
+	assert(type(groupInfo.role) == "string", "Bad groupInfo.role")
+
+	PlayerMock.writeLookup(player, "GroupService.GetRolesInGroupAsync", groupId, {
+		IsMember = true,
+		Roles = { { Name = groupInfo.role, Rank = groupInfo.rank } },
+	})
+
+	local groups = PlayerMock.readLookup(player, "GroupService.GetGroupsAsync", 0)
+	local updated = {}
+	for _, existing in groups do
+		if existing.Id ~= groupId then
+			table.insert(updated, existing)
+		end
+	end
+	table.insert(updated, {
+		Id = groupId,
+		Rank = groupInfo.rank,
+		Role = groupInfo.role,
+	})
+	PlayerMock.writeLookup(player, "GroupService.GetGroupsAsync", 0, updated)
+end
+
+return GroupTestUtils

package/src/Shared/GroupUtils.lua

@@ -9,6 +9,7 @@ local require = require(script.Parent.loader).load(script)
 
 local GroupService = game:GetService("GroupService")
 
+local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
 
 local GroupUtils = {}
@@ -48,17 +49,34 @@ type GetGroupDictionary = {
 }
 type GetGroupsAsyncResult = { GetGroupDictionary }
 
-local function _getRankAndRoleFallback(userId: number, groupId: number): (number, string?)
+-- The mock interception point is the engine call itself (see [PlayerMock.writeLookup]), not the
+-- promise wrappers below -- so the highest-role scan, fallback ordering, and reject paths all
+-- run for mocks too. A PlayerMock is in no real Roblox group, so answering from the injected
+-- result avoids the (flaky, fake-UserId) group lookup.
+local function _getRolesInGroupAsync(player: Player, groupId: number): GetRolesInGroupAsyncResult
+	if PlayerMock.isMock(player) then
+		return PlayerMock.readLookup(player, "GroupService.GetRolesInGroupAsync", groupId)
+	end
+
+	return GroupService:GetRolesInGroupAsync(player.UserId, groupId) :: GetRolesInGroupAsyncResult
+end
+
+local function _getRankAndRoleFallbackAsync(player: Player, groupId: number): (number, string?)
 	-- euvin: i yoinked this from
 	-- https://devforum.roblox.com/t/groupservicegetrolesingroupasync-is-not-enabled-yet-wiki-tells-me-to-use-it/4660969
 
 	--? The GetRankInGroup method is deprecated and unstable now.
 	--? https://devforum.roblox.com/t/excessive-rate-limits-when-checking-gamepasses-group-ranks/3549665
-	local groups = GroupService:GetGroupsAsync(userId) :: GetGroupsAsyncResult
+	local groups: GetGroupsAsyncResult
+	if PlayerMock.isMock(player) then
+		groups = PlayerMock.readLookup(player, "GroupService.GetGroupsAsync", 0)
+	else
+		groups = GroupService:GetGroupsAsync(player.UserId) :: GetGroupsAsyncResult
+	end
 
-	for _, GroupInfo: GetGroupDictionary in groups do
-		if GroupInfo.Id == groupId then
-			return GroupInfo.Rank, GroupInfo.Role
+	for _, groupInfo: GetGroupDictionary in groups do
+		if groupInfo.Id == groupId then
+			return groupInfo.Rank, groupInfo.Role
 		end
 	end
 
@@ -73,7 +91,7 @@ end
 	@return Promise<number> -- Generally from 0 to 255
 ]=]
 function GroupUtils.promiseRankInGroup(player: Player, groupId: number): Promise.Promise<number>
-	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(type(groupId) == "number", "Bad groupId")
 
 	return Promise.spawn(function(resolve, reject)
@@ -82,7 +100,7 @@ function GroupUtils.promiseRankInGroup(player: Player, groupId: number): Promise
 			-- GetRankInGroupAsync is deprecated, changed from GetRankInGroupAsync to GetRolesInGroupAsync
 			-- ... but GetRolesInGroupAsync fails for some reason and hasn't been fixed (June 2, 2026)
 			-- so we will fall back to a deprecated method anyway
-			local result = GroupService:GetRolesInGroupAsync(player.UserId, groupId) :: GetRolesInGroupAsyncResult
+			local result = _getRolesInGroupAsync(player, groupId)
 			if result.IsMember then
 				local highestRoleTable = _getHighestRoleTable(result.Roles)
 				if highestRoleTable then
@@ -92,7 +110,7 @@ function GroupUtils.promiseRankInGroup(player: Player, groupId: number): Promise
 		end)
 		if not rank then
 			ok, err = pcall(function()
-				local gotRank, _ = _getRankAndRoleFallback(player.UserId, groupId)
+				local gotRank, _ = _getRankAndRoleFallbackAsync(player, groupId)
 				rank = gotRank
 			end)
 		end
@@ -117,13 +135,13 @@ end
 	@return Promise<string>
 ]=]
 function GroupUtils.promiseRoleInGroup(player: Player, groupId: number): Promise.Promise<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")
 	assert(type(groupId) == "number", "Bad groupId")
 
 	return Promise.spawn(function(resolve, reject)
 		local role: string? = nil
 		local ok, err = pcall(function()
-			local result = GroupService:GetRolesInGroupAsync(player.UserId, groupId) :: GetRolesInGroupAsyncResult
+			local result = _getRolesInGroupAsync(player, groupId)
 			if result.IsMember then
 				local highestRoleTable = _getHighestRoleTable(result.Roles)
 				if highestRoleTable then
@@ -134,7 +152,7 @@ function GroupUtils.promiseRoleInGroup(player: Player, groupId: number): Promise
 
 		if not role then
 			ok, err = pcall(function()
-				local _, gotRole = _getRankAndRoleFallback(player.UserId, groupId)
+				local _, gotRole = _getRankAndRoleFallbackAsync(player, groupId)
 				role = gotRole
 			end)
 		end

package/src/Shared/GroupUtils.spec.lua

@@ -0,0 +1,214 @@
+--!strict
+--[[
+	Coverage for GroupUtils rank/role resolution using PlayerMock players. Only the GroupService
+	engine calls are intercepted (raw result shapes injected via PlayerMock.writeLookup /
+	GroupTestUtils.assignGroupInfo), so the highest-role scan, GetGroupsAsync fallback ordering,
+	and reject paths all execute for real.
+
+	@class GroupUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local GroupTestUtils = require("GroupTestUtils")
+local GroupUtils = require("GroupUtils")
+local Jest = require("Jest")
+local PlayerMock = require("PlayerMock")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local GROUP_ID = 372
+
+describe("GroupUtils.promiseRankInGroup", function()
+	it("should resolve 0 for a mock with no injected membership", function()
+		local player = PlayerMock.new({ UserId = 111 })
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRankInGroup(player, GROUP_ID))
+		expect(outcome).toBe("resolved")
+		expect(value).toBe(0)
+
+		player:Destroy()
+	end)
+
+	it("should resolve an assigned rank", function()
+		local player = PlayerMock.new({ UserId = 111 })
+		GroupTestUtils.assignGroupInfo(player, GROUP_ID, { rank = 230, role = "Admin" })
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRankInGroup(player, GROUP_ID))
+		expect(outcome).toBe("resolved")
+		expect(value).toBe(230)
+
+		player:Destroy()
+	end)
+
+	it("should resolve the highest rank when the result carries multiple roles", function()
+		local player = PlayerMock.new({ UserId = 111 })
+		PlayerMock.writeLookup(player, "GroupService.GetRolesInGroupAsync", GROUP_ID, {
+			IsMember = true,
+			Roles = {
+				{ Name = "Member", Rank = 1 },
+				{ Name = "Admin", Rank = 230 },
+				{ Name = "Moderator", Rank = 150 },
+			},
+		})
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRankInGroup(player, GROUP_ID))
+		expect(outcome).toBe("resolved")
+		expect(value).toBe(230)
+
+		player:Destroy()
+	end)
+
+	it("should resolve from the GetGroupsAsync fallback when the primary result reports non-member", function()
+		local player = PlayerMock.new({ UserId = 111 })
+		PlayerMock.writeLookup(player, "GroupService.GetGroupsAsync", 0, {
+			{ Id = GROUP_ID, Rank = 42, Role = "Member" },
+		})
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRankInGroup(player, GROUP_ID))
+		expect(outcome).toBe("resolved")
+		expect(value).toBe(42)
+
+		player:Destroy()
+	end)
+
+	it("should ignore membership assigned for a different group", function()
+		local player = PlayerMock.new({ UserId = 111 })
+		GroupTestUtils.assignGroupInfo(player, 99999, { rank = 255, role = "Owner" })
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRankInGroup(player, GROUP_ID))
+		expect(outcome).toBe("resolved")
+		expect(value).toBe(0)
+
+		player:Destroy()
+	end)
+
+	it("should throw on a non-player value", function()
+		expect(function()
+			GroupUtils.promiseRankInGroup(nil :: any, GROUP_ID)
+		end).toThrow("Bad player")
+	end)
+
+	it("should throw on a bad groupId", function()
+		local player = PlayerMock.new({ UserId = 111 })
+
+		expect(function()
+			GroupUtils.promiseRankInGroup(player, "372" :: any)
+		end).toThrow("Bad groupId")
+
+		player:Destroy()
+	end)
+end)
+
+describe("GroupUtils.promiseRoleInGroup", function()
+	it("should resolve an assigned role", function()
+		local player = PlayerMock.new({ UserId = 111 })
+		GroupTestUtils.assignGroupInfo(player, GROUP_ID, { rank = 230, role = "Admin" })
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRoleInGroup(player, GROUP_ID))
+		expect(outcome).toBe("resolved")
+		expect(value).toBe("Admin")
+
+		player:Destroy()
+	end)
+
+	it("should resolve the highest role's name when the result carries multiple roles", function()
+		local player = PlayerMock.new({ UserId = 111 })
+		PlayerMock.writeLookup(player, "GroupService.GetRolesInGroupAsync", GROUP_ID, {
+			IsMember = true,
+			Roles = {
+				{ Name = "Member", Rank = 1 },
+				{ Name = "Admin", Rank = 230 },
+				{ Name = "Moderator", Rank = 150 },
+			},
+		})
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRoleInGroup(player, GROUP_ID))
+		expect(outcome).toBe("resolved")
+		expect(value).toBe("Admin")
+
+		player:Destroy()
+	end)
+
+	it("should resolve from the GetGroupsAsync fallback when the primary result reports non-member", function()
+		local player = PlayerMock.new({ UserId = 111 })
+		PlayerMock.writeLookup(player, "GroupService.GetGroupsAsync", 0, {
+			{ Id = GROUP_ID, Rank = 42, Role = "Member" },
+		})
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRoleInGroup(player, GROUP_ID))
+		expect(outcome).toBe("resolved")
+		expect(value).toBe("Member")
+
+		player:Destroy()
+	end)
+
+	it("should reject for a mock with no injected membership, like a real non-member", function()
+		local player = PlayerMock.new({ UserId = 111 })
+
+		local outcome, err = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRoleInGroup(player, GROUP_ID))
+		expect(outcome).toBe("rejected")
+		expect(err).toBe("Role is not a string")
+
+		player:Destroy()
+	end)
+end)
+
+describe("GroupTestUtils.assignGroupInfo", function()
+	it("should keep rank and role coherent from one assignment", function()
+		local player = PlayerMock.new({ UserId = 111 })
+		GroupTestUtils.assignGroupInfo(player, GROUP_ID, { rank = 150, role = "Moderator" })
+
+		local _, rank = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRankInGroup(player, GROUP_ID))
+		local _, role = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRoleInGroup(player, GROUP_ID))
+		expect(rank).toBe(150)
+		expect(role).toBe("Moderator")
+
+		player:Destroy()
+	end)
+
+	it("should keep assignments to multiple groups independent", function()
+		local player = PlayerMock.new({ UserId = 111 })
+		GroupTestUtils.assignGroupInfo(player, GROUP_ID, { rank = 230, role = "Admin" })
+		GroupTestUtils.assignGroupInfo(player, 99999, { rank = 5, role = "Member" })
+
+		-- Clearing one group's primary result forces its answer through the shared GetGroupsAsync
+		-- fallback list, proving the second assignment appended rather than replaced it.
+		PlayerMock.writeLookup(player, "GroupService.GetRolesInGroupAsync", GROUP_ID, nil)
+
+		local _, rank = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRankInGroup(player, GROUP_ID))
+		local _, otherRank = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRankInGroup(player, 99999))
+		expect(rank).toBe(230)
+		expect(otherRank).toBe(5)
+
+		player:Destroy()
+	end)
+
+	it("should replace an earlier assignment for the same group", function()
+		local player = PlayerMock.new({ UserId = 111 })
+		GroupTestUtils.assignGroupInfo(player, GROUP_ID, { rank = 10, role = "Member" })
+		GroupTestUtils.assignGroupInfo(player, GROUP_ID, { rank = 20, role = "Moderator" })
+
+		local _, rank = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRankInGroup(player, GROUP_ID))
+		expect(rank).toBe(20)
+
+		PlayerMock.writeLookup(player, "GroupService.GetRolesInGroupAsync", GROUP_ID, nil)
+		local _, fallbackRank = PromiseTestUtils.awaitOutcome(GroupUtils.promiseRankInGroup(player, GROUP_ID))
+		expect(fallbackRank).toBe(20)
+
+		player:Destroy()
+	end)
+
+	it("should throw when passed something that is not a PlayerMock", function()
+		local folder = Instance.new("Folder")
+
+		expect(function()
+			GroupTestUtils.assignGroupInfo(folder :: any, GROUP_ID, { rank = 1, role = "Member" })
+		end).toThrow("Not a PlayerMock")
+
+		folder:Destroy()
+	end)
+end)

package/src/jest.config.lua

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

package/test/default.project.json

@@ -0,0 +1,17 @@
+{
+  "name": "GroupUtilsTest",
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "$properties": {
+        "LoadStringEnabled": true
+      },
+      "grouputils": {
+        "$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.grouputils
+local loader = root:FindFirstChild("LoaderUtils", true).Parent
+local require = require(loader).bootstrapGame(root)
+
+local NevermoreTestRunnerUtils = require("NevermoreTestRunnerUtils")
+
+if NevermoreTestRunnerUtils.runTestsIfNeededAsync(root) then
+	return
+end