@quenty/playerthumbnailutils 10.20.0 → 10.21.0

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.21.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/playerthumbnailutils@10.20.0...@quenty/playerthumbnailutils@10.21.0) (2026-07-23)
+
+### Bug Fixes
+
+- Additional fixes ([8714d52](https://github.com/Quenty/NevermoreEngine/commit/8714d52ed996f2e41e6daa191554acca35860e36))
+
+### Features
+
+- Add baseline player-mock and support across Nevermore for mocked players. ([567d121](https://github.com/Quenty/NevermoreEngine/commit/567d121ffc014b42391554088189a1a6296dda83))
+
 # [10.20.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/playerthumbnailutils@10.19.0...@quenty/playerthumbnailutils@10.20.0) (2026-07-18)
 
 **Note:** Version bump only for package @quenty/playerthumbnailutils

package/deploy.nevermore.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/playerthumbnailutils",
-  "version": "10.20.0",
+  "version": "10.21.0",
   "description": "Reimplementation of Player:GetUserThumbnailAsync but as a promise with retry logic",
   "keywords": [
     "Roblox",
@@ -29,10 +29,13 @@
   ],
   "dependencies": {
     "@quenty/loader": "10.11.0",
-    "@quenty/promise": "10.20.0"
+    "@quenty/nevermore-test-runner": "1.5.0",
+    "@quenty/playermock": "1.1.0",
+    "@quenty/promise": "10.21.0",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "647acfad93dca41c38f59cda247d2bfc0fff36d4"
+  "gitHead": "1de37218a2bedb8e3f8614a2e09bba9eddc812da"
 }

package/src/Shared/PlayerThumbnailUtils.lua

@@ -10,10 +10,19 @@ local require = require(script.Parent.loader).load(script)
 
 local Players = game:GetService("Players")
 
+local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
 
 local MAX_TRIES = 5
 
+-- What each ThumbnailType is called in an rbxthumb:// content URL, which is the shape
+-- GetUserThumbnailAsync itself resolves -- so a mock's thumbnail can derive from its UserId alone.
+local THUMBNAIL_TYPE_TO_RBXTHUMB_TYPE = {
+	[Enum.ThumbnailType.HeadShot] = "AvatarHeadShot",
+	[Enum.ThumbnailType.AvatarBust] = "AvatarBust",
+	[Enum.ThumbnailType.AvatarThumbnail] = "Avatar",
+}
+
 local PlayerThumbnailUtils = {}
 
 --[=[
@@ -35,17 +44,36 @@ function PlayerThumbnailUtils.promiseUserThumbnail(
 	thumbnailSize: Enum.ThumbnailSize?
 ): Promise.Promise<string>
 	assert(type(userId) == "number", "Bad userId")
-	thumbnailType = thumbnailType or Enum.ThumbnailType.HeadShot
-	thumbnailSize = thumbnailSize or Enum.ThumbnailSize.Size100x100
+	local resolvedThumbnailType: Enum.ThumbnailType = thumbnailType or Enum.ThumbnailType.HeadShot
+	local resolvedThumbnailSize: Enum.ThumbnailSize = thumbnailSize or Enum.ThumbnailSize.Size100x100
 
 	local promise
 	promise = Promise.spawn(function(resolve, reject)
+		if PlayerMock.getMockByUserId(userId) ~= nil then
+			-- The engine call would reject a fake UserId; derive the rbxthumb content URL it
+			-- would resolve for a real one.
+			local width, height = string.match(resolvedThumbnailSize.Name, "^Size(%d+)x(%d+)$")
+			if width == nil or height == nil then
+				return reject(string.format("Failed to parse thumbnail size %q", resolvedThumbnailSize.Name))
+			end
+
+			return resolve(
+				string.format(
+					"rbxthumb://type=%s&id=%d&w=%s&h=%s",
+					THUMBNAIL_TYPE_TO_RBXTHUMB_TYPE[resolvedThumbnailType],
+					userId,
+					width,
+					height
+				)
+			)
+		end
+
 		local tries = 0
 		repeat
 			tries = tries + 1
 			local content, isReady
 			local ok, err = pcall(function()
-				content, isReady = Players:GetUserThumbnailAsync(userId, thumbnailType, thumbnailSize)
+				content, isReady = Players:GetUserThumbnailAsync(userId, resolvedThumbnailType, resolvedThumbnailSize)
 			end)
 
 			-- Don't retry if we immediately error (timeout exceptions!)
@@ -79,6 +107,13 @@ function PlayerThumbnailUtils.promiseUserName(userId: number): Promise.Promise<s
 
 	local promise
 	promise = Promise.spawn(function(resolve, reject)
+		local mockPlayer = PlayerMock.getMockByUserId(userId)
+		if mockPlayer ~= nil then
+			-- Resolved from the same user-info domain UserServiceUtils reads, so the two
+			-- packages' usernames can never disagree for a mock.
+			return resolve(PlayerMock.readLookup(mockPlayer, "UserService.GetUserInfosByUserIdsAsync", 0).Username)
+		end
+
 		local tries = 0
 		repeat
 			tries = tries + 1

package/src/Shared/PlayerThumbnailUtils.spec.lua

@@ -0,0 +1,81 @@
+--!strict
+--[[
+	@class PlayerThumbnailUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Workspace = game:GetService("Workspace")
+
+local Jest = require("Jest")
+local PlayerMock = require("PlayerMock")
+local PlayerThumbnailUtils = require("PlayerThumbnailUtils")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("PlayerThumbnailUtils.promiseUserThumbnail against a mock", function()
+	it("resolves the derived rbxthumb URL with defaulted type and size", function()
+		local player = PlayerMock.new({ UserId = 90081001 })
+		player.Parent = Workspace
+
+		local outcome, content = PromiseTestUtils.awaitOutcome(PlayerThumbnailUtils.promiseUserThumbnail(90081001))
+
+		expect(outcome).toBe("resolved")
+		expect(content).toBe("rbxthumb://type=AvatarHeadShot&id=90081001&w=100&h=100")
+
+		player:Destroy()
+	end)
+
+	it("derives the URL from the requested type and size", function()
+		local player = PlayerMock.new({ UserId = 90081002 })
+		player.Parent = Workspace
+
+		local outcome, content = PromiseTestUtils.awaitOutcome(
+			PlayerThumbnailUtils.promiseUserThumbnail(
+				90081002,
+				Enum.ThumbnailType.AvatarThumbnail,
+				Enum.ThumbnailSize.Size420x420
+			)
+		)
+
+		expect(outcome).toBe("resolved")
+		expect(content).toBe("rbxthumb://type=Avatar&id=90081002&w=420&h=420")
+
+		player:Destroy()
+	end)
+end)
+
+describe("PlayerThumbnailUtils.promiseUserName against a mock", function()
+	it("resolves the default Name-derived username", function()
+		local player = PlayerMock.new({ UserId = 90081003 })
+		player.Parent = Workspace
+
+		local outcome, name = PromiseTestUtils.awaitOutcome(PlayerThumbnailUtils.promiseUserName(90081003))
+
+		expect(outcome).toBe("resolved")
+		expect(name).toBe(player.Name)
+
+		player:Destroy()
+	end)
+
+	it("resolves an injected username from the shared user-info domain", function()
+		local player = PlayerMock.new({ UserId = 90081004 })
+		player.Parent = Workspace
+		PlayerMock.writeLookup(player, "UserService.GetUserInfosByUserIdsAsync", 0, {
+			Id = 90081004,
+			Username = "shared_domain_name",
+			DisplayName = "Shared",
+			HasVerifiedBadge = false,
+		})
+
+		local outcome, name = PromiseTestUtils.awaitOutcome(PlayerThumbnailUtils.promiseUserName(90081004))
+
+		expect(outcome).toBe("resolved")
+		expect(name).toBe("shared_domain_name")
+
+		player: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": "PlayerThumbnailUtilsTest",
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "$properties": {
+        "LoadStringEnabled": true
+      },
+      "playerthumbnailutils": {
+        "$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.playerthumbnailutils
+local loader = root:FindFirstChild("LoaderUtils", true).Parent
+local require = require(loader).bootstrapGame(root)
+
+local NevermoreTestRunnerUtils = require("NevermoreTestRunnerUtils")
+
+if NevermoreTestRunnerUtils.runTestsIfNeededAsync(root) then
+	return
+end