Skip to main content

PromiseTestUtils

Test helpers for awaiting promises with a bounded timeout, so a hung promise fails the test instead of freezing the runner. Awaiting races the promise against a timeout rather than polling with task.wait().

Functions​

awaitSettled​

</>
PromiseTestUtils.awaitSettled(
promise: Promise,
timeout: number?--

Defaults to 5 seconds

) → boolean--

true if the promise settled, false if it timed out

Yields until the promise settles (resolves or rejects) or the timeout elapses. Races the promise against a timeout instead of polling.

awaitFulfilled​

</>
PromiseTestUtils.awaitFulfilled(
promise: Promise.Promise<T...>,
timeout: number?
) → any

Yields until the promise fulfills and returns the first value it resolved with. Errors if the promise rejects, or is still pending once the timeout (5 seconds by default) elapses, so a test fails at the await instead of carrying a missing value forward. Only the first value comes back so the call can be passed straight to expect, which takes one argument. 

local dataStore = PromiseTestUtils.awaitFulfilled(playerDataStoreService:PromiseDataStore(player))

awaitRejected​

</>
PromiseTestUtils.awaitRejected(
promise: Promise.Promise<T...>,
timeout: number?
) → any

Yields until the promise rejects and returns the first value it rejected with. Errors if the promise fulfills, or is still pending once the timeout (5 seconds by default) elapses. 

local err = PromiseTestUtils.awaitRejected(dataStore:Save())

awaitValue​

</>
PromiseTestUtils.awaitValue(
predicate: () → boolean,
timeout: number?--

Defaults to 5 seconds

) → boolean--

The final predicate result

Yields until the predicate returns a truthy value or the timeout elapses. Used when the awaited condition is observable state rather than a promise.

awaitOutcome​

</>
PromiseTestUtils.awaitOutcome(
promise: Promise,
timeout: number?--

Defaults to 5 seconds

) → (
"resolved" | "rejected" | "pending",
any--

The resolved value or rejection error

)

Attaches resolve/reject handlers synchronously (so the rejection is always handled and never surfaces as an uncaught error) and yields for the outcome.

Show raw api
{
    "functions": [
        {
            "name": "awaitSettled",
            "desc": "Yields until the promise settles (resolves or rejects) or the timeout elapses. Races the promise\nagainst a timeout instead of polling.",
            "params": [
                {
                    "name": "promise",
                    "desc": "",
                    "lua_type": "Promise"
                },
                {
                    "name": "timeout",
                    "desc": "Defaults to 5 seconds",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "true if the promise settled, false if it timed out",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 27,
                "path": "src/promise/src/Shared/PromiseTestUtils.lua"
            }
        },
        {
            "name": "awaitFulfilled",
            "desc": "Yields until the promise fulfills and returns the first value it resolved with. Errors if the promise\nrejects, or is still pending once the timeout (5 seconds by default) elapses, so a test fails at the\nawait instead of carrying a missing value forward. Only the first value comes back so the call can be\npassed straight to `expect`, which takes one argument.\n\n```lua\nlocal dataStore = PromiseTestUtils.awaitFulfilled(playerDataStoreService:PromiseDataStore(player))\n```",
            "params": [
                {
                    "name": "promise",
                    "desc": "",
                    "lua_type": "Promise.Promise<T...>"
                },
                {
                    "name": "timeout",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "any\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 57,
                "path": "src/promise/src/Shared/PromiseTestUtils.lua"
            }
        },
        {
            "name": "awaitRejected",
            "desc": "Yields until the promise rejects and returns the first value it rejected with. Errors if the promise\nfulfills, or is still pending once the timeout (5 seconds by default) elapses.\n\n```lua\nlocal err = PromiseTestUtils.awaitRejected(dataStore:Save())\n```",
            "params": [
                {
                    "name": "promise",
                    "desc": "",
                    "lua_type": "Promise.Promise<T...>"
                },
                {
                    "name": "timeout",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "any\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 78,
                "path": "src/promise/src/Shared/PromiseTestUtils.lua"
            }
        },
        {
            "name": "awaitValue",
            "desc": "Yields until the predicate returns a truthy value or the timeout elapses. Used when the awaited\ncondition is observable state rather than a promise.",
            "params": [
                {
                    "name": "predicate",
                    "desc": "",
                    "lua_type": "() -> boolean"
                },
                {
                    "name": "timeout",
                    "desc": "Defaults to 5 seconds",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "The final predicate result",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 99,
                "path": "src/promise/src/Shared/PromiseTestUtils.lua"
            }
        },
        {
            "name": "awaitOutcome",
            "desc": "Attaches resolve/reject handlers synchronously (so the rejection is always handled and never\nsurfaces as an uncaught error) and yields for the outcome.",
            "params": [
                {
                    "name": "promise",
                    "desc": "",
                    "lua_type": "Promise"
                },
                {
                    "name": "timeout",
                    "desc": "Defaults to 5 seconds",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "\"resolved\" | \"rejected\" | \"pending\""
                },
                {
                    "desc": "The resolved value or rejection error",
                    "lua_type": "any"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 116,
                "path": "src/promise/src/Shared/PromiseTestUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "PromiseTestUtils",
    "desc": "Test helpers for awaiting promises with a bounded timeout, so a hung promise fails the test\ninstead of freezing the runner. Awaiting races the promise against a timeout rather than polling\nwith `task.wait()`.",
    "source": {
        "line": 9,
        "path": "src/promise/src/Shared/PromiseTestUtils.lua"
    }
}