@dereekb/firebase-server 13.2.2 → 13.3.1

package/test/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.2.2",
+  "version": "13.3.1",
   "peerDependencies": {
-    "@dereekb/date": "13.2.2",
-    "@dereekb/firebase": "13.2.2",
-    "@dereekb/firebase-server": "13.2.2",
-    "@dereekb/model": "13.2.2",
-    "@dereekb/nestjs": "13.2.2",
-    "@dereekb/rxjs": "13.2.2",
-    "@dereekb/util": "13.2.2",
+    "@dereekb/date": "13.3.1",
+    "@dereekb/firebase": "13.3.1",
+    "@dereekb/firebase-server": "13.3.1",
+    "@dereekb/model": "13.3.1",
+    "@dereekb/nestjs": "13.3.1",
+    "@dereekb/rxjs": "13.3.1",
+    "@dereekb/util": "13.3.1",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/testing": "^11.0.0",
+    "@nestjs/common": "^11.1.16",
+    "@nestjs/testing": "^11.1.14",
     "firebase-admin": "^13.0.0",
     "firebase-functions": "^7.0.0",
     "firebase-functions-test": "3.4.1",

package/test/src/lib/firebase/firebase.admin.auth.d.ts

@@ -9,10 +9,27 @@ import { type WrappedBlockingFunction, type WrappedBlockingFunctionWithHandler,
 import { type ScheduledEvent } from 'firebase-functions/scheduler';
 import { type AuthData } from '@dereekb/firebase-server';
 import { type AuthBlockingEvent } from 'firebase-functions/identity';
+/**
+ * Union of all cloud function wrapper types that can be invoked via {@link AuthorizedUserTestContext.callCloudFunction}.
+ *
+ * Includes gen 1 wrapped functions, gen 2 wrapped functions, blocking functions, and scheduled functions.
+ */
 export type CallCloudFunction = WrappedCloudFunctionV1<any> | WrappedBlockingFunctionWithHandler<any, any> | WrappedBlockingFunction | WrappedV2Function<any> | WrappedCloudFunctionV1<any>;
+/**
+ * Infers the input parameter type for a given wrapped cloud function type.
+ *
+ * Used to extract the expected params type when calling a cloud function in tests.
+ */
 export type CallCloudFunctionParams<F> = F extends WrappedFunction<infer I> ? I : unknown | undefined | void;
 /**
- * Testing context for a single user.
+ * Test context interface representing an authorized Firebase user.
+ *
+ * Provides access to the user's UID, record, tokens, and the ability to invoke
+ * wrapped Firebase Cloud Functions (callable, scheduled, blocking, and event-based)
+ * as that user. Used within Jest test suites to simulate authenticated function calls.
+ *
+ * @see {@link AuthorizedUserTestContextInstance} for the concrete implementation
+ * @see {@link authorizedUserContextFactory} to create test contexts via a factory
  */
 export interface AuthorizedUserTestContext {
     readonly uid: FirebaseAuthUserId;
@@ -39,6 +56,13 @@ export interface AuthorizedUserTestContext {
     callCloudFunction<F extends WrappedCloudFunctionV1<any>, O = unknown>(fn: F, params: CallCloudFunctionParams<F>, skipJsonConversion?: boolean): Promise<O>;
     callCloudFunction<F extends WrappedFunction<any>, O = unknown>(fn: F, params: CallCloudFunctionParams<F>, skipJsonConversion?: boolean): Promise<O>;
 }
+/**
+ * Fixture wrapper for {@link AuthorizedUserTestContextInstance} that delegates all
+ * {@link AuthorizedUserTestContext} operations to the underlying instance.
+ *
+ * Manages the lifecycle of the authorized user test context within the Jest test fixture hierarchy.
+ * Use this as the primary handle in test suites; it is created automatically by {@link authorizedUserContextFactory}.
+ */
 export declare class AuthorizedUserTestContextFixture<PI extends FirebaseAdminTestContext = FirebaseAdminTestContext, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends AuthorizedUserTestContextInstance<PI> = AuthorizedUserTestContextInstance<PI>> extends AbstractChildTestContextFixture<I, PF> implements AuthorizedUserTestContext {
     get uid(): FirebaseAuthUserId;
     loadUserRecord(): Promise<UserRecord>;
@@ -58,7 +82,24 @@ export declare class AuthorizedUserTestContextFixture<PI extends FirebaseAdminTe
     callCloudFunction<F extends WrappedCloudFunctionV1<any>, O = unknown>(fn: F, params: CallCloudFunctionParams<F>, skipJsonConversion?: boolean): Promise<O>;
     callCloudFunction<F extends WrappedFunction<any>, O = unknown>(fn: F, params: CallCloudFunctionParams<F>, skipJsonConversion?: boolean): Promise<O>;
 }
+/**
+ * Partial event context for gen 1 event-triggered cloud functions, with the `auth` field omitted
+ * since it is injected automatically by the test context.
+ *
+ * @deprecated Used only with gen 1 event cloud functions via {@link AuthorizedUserTestContextInstance.callEventCloudFunction}.
+ */
 export type CallEventFunctionEventContext = Partial<Omit<EventContext, 'auth'>>;
+/**
+ * Concrete implementation of {@link AuthorizedUserTestContext} that holds a Firebase user UID
+ * and a reference to the parent {@link FirebaseAdminTestContext}.
+ *
+ * Provides methods to load the user's record/token, build context options, and invoke
+ * wrapped Cloud Functions (callable, scheduled, blocking, and event-based) as the authorized user.
+ * Automatically handles JSON round-trip simulation for function parameters unless `skipJsonConversion` is set.
+ *
+ * Created by {@link authorizedUserContextFactory} during test setup; typically accessed
+ * through the {@link AuthorizedUserTestContextFixture} wrapper.
+ */
 export declare class AuthorizedUserTestContextInstance<PI extends FirebaseAdminTestContext = FirebaseAdminTestContext> implements AuthorizedUserTestContext {
     readonly uid: FirebaseAuthUserId;
     readonly testContext: PI;
@@ -162,6 +203,10 @@ export interface AuthorizedUserTestContextParams<PI extends FirebaseAdminTestCon
  * Convenience function for using authorizedUserContextFactory directly and passing buildTests.
  */
 export declare function authorizedUserContext<PI extends FirebaseAdminTestContext = FirebaseAdminTestContext, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends AuthorizedUserTestContextInstance<PI> = AuthorizedUserTestContextInstance<PI>, F extends AuthorizedUserTestContextFixture<PI, PF, I> = AuthorizedUserTestContextFixture<PI, PF, I>>(config: AuthorizedUserTestContextParams<PI, PF, I, F>, buildTests: (u: F) => void): void;
+/**
+ * Configuration for {@link authorizedUserContextFactory}, which is {@link AuthorizedUserTestContextParams}
+ * without the fixture reference (`f`). The fixture is provided separately when the factory is invoked.
+ */
 export type AuthorizedUserTestContextFactoryConfig<PI extends FirebaseAdminTestContext = FirebaseAdminTestContext, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends AuthorizedUserTestContextInstance<PI> = AuthorizedUserTestContextInstance<PI>, F extends AuthorizedUserTestContextFixture<PI, PF, I> = AuthorizedUserTestContextFixture<PI, PF, I>> = Omit<AuthorizedUserTestContextParams<PI, PF, I, F>, 'f'>;
 export interface AuthorizedUserTestContextFactoryParams<PI extends FirebaseAdminTestContext = FirebaseAdminTestContext, PF extends TestContextFixture<PI> = TestContextFixture<PI>> {
     readonly f: PF;
@@ -180,7 +225,19 @@ export interface AuthorizedUserTestContextFactoryParams<PI extends FirebaseAdmin
      */
     readonly template?: GetterOrValue<AuthorizedUserTestContextDetailsTemplate>;
 }
+/**
+ * Factory that generates unique random email addresses for test users.
+ *
+ * Used by {@link authorizedUserContextFactory} when `addContactInfo` is enabled
+ * and no explicit email is provided in the user details template.
+ */
 export declare const AUTHORIZED_USER_RANDOM_EMAIL_FACTORY: import("@dereekb/util").RandomEmailFactory;
+/**
+ * Factory that generates unique random E.164 phone numbers for test users.
+ *
+ * Used by {@link authorizedUserContextFactory} when `addContactInfo` is enabled
+ * and no explicit phone number is provided in the user details template.
+ */
 export declare const AUTHORIZED_USER_RANDOM_PHONE_NUMBER_FACTORY: import("@dereekb/util").RandomPhoneNumberFactory;
 /**
  * Creates a new Jest Context that has a random user for authorization for use in firebase server tests.
@@ -192,6 +249,12 @@ export declare function authorizedUserContextFactory<PI extends FirebaseAdminTes
  * Has the format 'test-uid-<number>'
  */
 export declare const testUidFactory: Factory<FirebaseAuthUserId>;
+/**
+ * An encoded JWT string representing a Firebase custom token created for testing.
+ *
+ * @see {@link createEncodedTestFirestoreTokenForUserRecord} to create one
+ * @see {@link decodeEncodedCreateCustomTokenResult} to decode one
+ */
 export type TestEncodedFirestoreToken = string;
 /**
  * Structure of the token created by Auth.createCustomToken().
@@ -231,5 +294,23 @@ export declare function createTestFirestoreTokenForUserRecord(auth: Auth, userRe
  * @returns
  */
 export declare function createEncodedTestFirestoreTokenForUserRecord(auth: Auth, userRecord: UserRecord): Promise<TestEncodedFirestoreToken>;
+/**
+ * Decodes an encoded custom token (JWT) into a {@link DecodedIdToken} suitable for test assertions.
+ *
+ * The custom token created by `Auth.createCustomToken()` nests custom claims under a `claims` key
+ * in the JWT payload. This function flattens those claims onto the top-level decoded token to match
+ * the structure of a real `DecodedIdToken`, and injects `auth_time` from the `iat` field.
+ *
+ * @see {@link createEncodedTestFirestoreTokenForUserRecord} for creating the encoded token
+ */
 export declare function decodeEncodedCreateCustomTokenResult(token: TestEncodedFirestoreToken): DecodedIdToken;
+/**
+ * Builds a claims object from a {@link UserRecord} that mirrors the structure of a real {@link DecodedIdToken}.
+ *
+ * Copies standard identity fields (email, email_verified, picture) and merges in any
+ * custom claims already set on the user record. The resulting object is used as the
+ * custom claims parameter for `Auth.createCustomToken()` in test token generation.
+ *
+ * @see {@link createEncodedTestFirestoreTokenForUserRecord}
+ */
 export declare function testFirestoreClaimsFromUserRecord(userRecord: UserRecord): object;

package/test/src/lib/firebase/firebase.admin.collection.d.ts

@@ -3,7 +3,15 @@ import { type AsyncGetterOrValue, type PromiseOrValue } from '@dereekb/util';
 import { type TestContextFixture, AbstractChildTestContextFixture } from '@dereekb/util/test';
 import { type FirebaseAdminTestContext } from './firebase.admin';
 /**
- * Testing context for a single model.
+ * Test context interface representing a single Firestore document/model instance.
+ *
+ * Provides convenient access to the document's identifiers (ID, key, flat key),
+ * its {@link DocumentReference}, and the typed {@link FirestoreDocument} wrapper.
+ * Used within Jest test suites to interact with a specific document that was
+ * created during test setup.
+ *
+ * @see {@link ModelTestContextInstance} for the concrete implementation
+ * @see {@link modelTestContextFactory} to create model test contexts via a factory
  */
 export interface ModelTestContext<T, D extends FirestoreDocument<T> = FirestoreDocument<T>> {
     get documentId(): FirestoreModelId;
@@ -13,6 +21,13 @@ export interface ModelTestContext<T, D extends FirestoreDocument<T> = FirestoreD
     get documentRef(): DocumentReference<T>;
     get document(): D;
 }
+/**
+ * Fixture wrapper for {@link ModelTestContextInstance} that delegates all
+ * {@link ModelTestContext} operations to the underlying instance.
+ *
+ * Manages the lifecycle of the model test context within the Jest test fixture hierarchy.
+ * Use this as the primary handle in test suites; it is created automatically by {@link modelTestContextFactory}.
+ */
 export declare class ModelTestContextFixture<T, D extends FirestoreDocument<T> = FirestoreDocument<T>, PI extends FirebaseAdminTestContext = FirebaseAdminTestContext, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends ModelTestContextInstance<T, D, PI> = ModelTestContextInstance<T, D, PI>> extends AbstractChildTestContextFixture<I, PF> implements ModelTestContext<T, D> {
     get documentId(): FirestoreModelId;
     get documentKey(): FirestoreModelKey;
@@ -21,6 +36,16 @@ export declare class ModelTestContextFixture<T, D extends FirestoreDocument<T> =
     get documentRef(): DocumentReference<T>;
     get document(): D;
 }
+/**
+ * Concrete implementation of {@link ModelTestContext} that holds a Firestore collection reference,
+ * a document reference, and the parent {@link FirebaseAdminTestContext}.
+ *
+ * Provides computed properties for the document's various key formats (path, flat, two-way flat)
+ * and lazily loads the typed {@link FirestoreDocument} wrapper on access.
+ *
+ * Created by {@link modelTestContextFactory} during test setup; typically accessed
+ * through the {@link ModelTestContextFixture} wrapper.
+ */
 export declare class ModelTestContextInstance<T, D extends FirestoreDocument<T> = FirestoreDocument<T>, PI extends FirebaseAdminTestContext = FirebaseAdminTestContext> implements ModelTestContext<T, D> {
     readonly collection: FirestoreCollectionLike<T, D>;
     readonly ref: DocumentReference<T>;
@@ -34,7 +59,12 @@ export declare class ModelTestContextInstance<T, D extends FirestoreDocument<T>
     get document(): D;
 }
 /**
- * authorizedUserContext/authorizedUserContextFactory parameters.
+ * Configuration for {@link modelTestContextFactory} that controls how model test contexts
+ * are created, initialized, and torn down.
+ *
+ * At minimum, `getCollection` must be provided to resolve the Firestore collection from the
+ * parent test context. Other hooks allow customizing fixture creation, document reference creation,
+ * instance construction, initialization, and cleanup.
  */
 export interface ModelTestContextFactoryParams<T, D extends FirestoreDocument<T> = FirestoreDocument<T>, C = any, PI extends FirebaseAdminTestContext = FirebaseAdminTestContext, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends ModelTestContextInstance<T, D, PI> = ModelTestContextInstance<T, D, PI>, F extends ModelTestContextFixture<T, D, PI, PF, I> = ModelTestContextFixture<T, D, PI, PF, I>, CL extends FirestoreCollectionLike<T, D> = FirestoreCollectionLike<T, D>> {
     /**
@@ -70,16 +100,38 @@ export interface ModelTestContextFactoryParams<T, D extends FirestoreDocument<T>
      */
     destroyInstance?(instance: I): PromiseOrValue<void>;
 }
+/**
+ * Alternative params for {@link modelTestContextFactory} that supplies a pre-existing document
+ * instead of creating a new one. When used, the factory skips document creation and
+ * `initDocument`, and instead wraps the provided document.
+ *
+ * Requires `collectionForDocument` to be set in {@link ModelTestContextFactoryParams} so the
+ * factory can resolve the collection for the given document.
+ */
 export interface ModelTestContextDocumentRefParams<D extends FirestoreDocument<any> = FirestoreDocument<any>> {
     /**
      * Custom document to use that is already initialized.
      */
     readonly doc: AsyncGetterOrValue<D>;
 }
+/**
+ * Runtime parameters passed when invoking a model test context factory.
+ *
+ * Always includes the parent fixture (`f`). The remaining fields come from either the
+ * custom config type `C` (for new document creation) or {@link ModelTestContextDocumentRefParams}
+ * (for wrapping an existing document).
+ */
 export type ModelTestContextParams<C = any, PI extends FirebaseAdminTestContext = FirebaseAdminTestContext, PF extends TestContextFixture<PI> = TestContextFixture<PI>> = {
     f: PF;
 } & (C | ModelTestContextDocumentRefParams);
 /**
- * Creates a new Test Context that has a random user for authorization for use in firebase server tests.
+ * Creates a reusable factory function that sets up a {@link ModelTestContextFixture} for a specific
+ * Firestore model type within Jest test suites.
+ *
+ * The returned factory, when called with params and a `buildTests` callback, registers `beforeEach`/`afterEach`
+ * hooks that create a new document (or wrap an existing one via {@link ModelTestContextDocumentRefParams}),
+ * build the test context instance, optionally initialize the document, and clean up after each test.
+ *
+ * @see {@link ModelTestContextFactoryParams} for configuration options
  */
 export declare function modelTestContextFactory<T, D extends FirestoreDocument<T> = FirestoreDocument<T>, C = any, PI extends FirebaseAdminTestContext = FirebaseAdminTestContext, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends ModelTestContextInstance<T, D, PI> = ModelTestContextInstance<T, D, PI>, F extends ModelTestContextFixture<T, D, PI, PF, I> = ModelTestContextFixture<T, D, PI, PF, I>, CL extends FirestoreCollectionLike<T, D> = FirestoreCollectionLike<T, D>>(config: ModelTestContextFactoryParams<T, D, C, PI, PF, I, F, CL>): (params: ModelTestContextParams<C, PI, PF>, buildTests: (u: F) => void) => void;

package/test/src/lib/firebase/firebase.admin.d.ts

@@ -7,8 +7,20 @@ import { type FirebaseAdminCloudFunctionWrapper, type FirebaseAdminCloudFunction
 import { type Storage as GoogleCloudStorage } from '@google-cloud/storage';
 import { GoogleCloudTestFirebaseStorageInstance } from '../storage/storage';
 import { type Auth } from 'firebase-admin/auth';
+/**
+ * Configuration for creating a {@link FirebaseAdminTestContextInstance}.
+ *
+ * Currently empty but exists as an extension point for future per-test configuration.
+ */
 export interface FirebaseAdminTestConfig {
 }
+/**
+ * Provides access to all Firebase Admin services needed during testing.
+ *
+ * Implementations expose the Admin app, authentication, Firestore, and Cloud Storage
+ * along with their corresponding test driver instances and contexts. Also extends
+ * {@link FirebaseAdminCloudFunctionWrapperSource} for wrapping Cloud Functions in tests.
+ */
 export interface FirebaseAdminTestContext extends FirebaseAdminCloudFunctionWrapperSource {
     readonly app: admin.app.App;
     readonly auth: Auth;
@@ -19,6 +31,13 @@ export interface FirebaseAdminTestContext extends FirebaseAdminCloudFunctionWrap
     readonly storageInstance: TestFirebaseStorageInstance;
     readonly storageContext: TestFirebaseStorageContext;
 }
+/**
+ * Test fixture that implements {@link FirebaseAdminTestContext} by forwarding all property access
+ * to the underlying {@link FirebaseAdminTestContextInstance}.
+ *
+ * Used with {@link firebaseAdminTestBuilder} to provide a stable reference that persists across
+ * the setup/teardown lifecycle while the inner instance is created and destroyed per test suite.
+ */
 export declare class FirebaseAdminTestContextFixture extends AbstractTestContextFixture<FirebaseAdminTestContextInstance> implements FirebaseAdminTestContext {
     get app(): admin.app.App;
     get auth(): Auth;
@@ -30,6 +49,17 @@ export declare class FirebaseAdminTestContextFixture extends AbstractTestContext
     get storageContext(): TestFirebaseStorageContext;
     get fnWrapper(): FirebaseAdminCloudFunctionWrapper;
 }
+/**
+ * Wraps a `firebase-admin` {@link admin.app.App} and lazily creates test driver instances
+ * for Firestore and Cloud Storage.
+ *
+ * Each instance initializes its own Admin app with a unique project ID, ensuring test isolation
+ * when running against Firebase emulators. The Firestore and Storage test instances are created
+ * on first access via {@link cachedGetter} so they are only allocated when actually needed.
+ *
+ * @throws Error if {@link fnWrapper} is accessed, since Cloud Function wrapping requires a
+ * subclass (such as one provided by `firebase-functions-test`).
+ */
 export declare class FirebaseAdminTestContextInstance implements FirebaseAdminTestContext {
     readonly app: admin.app.App;
     readonly getTestFirestoreInstance: import("@dereekb/util").CachedFactoryWithInput<GoogleCloudTestFirestoreInstance, unknown>;
@@ -44,6 +74,15 @@ export declare class FirebaseAdminTestContextInstance implements FirebaseAdminTe
     get storageContext(): TestFirebaseStorageContext;
     get fnWrapper(): FirebaseAdminCloudFunctionWrapper;
 }
+/**
+ * Base class for child test context instances that extend a {@link FirebaseAdminTestContextInstance}.
+ *
+ * Forwards all {@link FirebaseAdminTestContext} properties to the `parent` instance, allowing
+ * subclasses to layer additional behavior (e.g., Cloud Function wrapping, custom auth setup)
+ * while reusing the parent's Admin app and emulator connections.
+ *
+ * @typeParam F - The parent instance type, defaults to {@link FirebaseAdminTestContextInstance}.
+ */
 export declare abstract class AbstractFirebaseAdminTestContextInstanceChild<F extends FirebaseAdminTestContextInstance = FirebaseAdminTestContextInstance> implements FirebaseAdminTestContext {
     readonly parent: F;
     constructor(parent: F);
@@ -64,6 +103,20 @@ export declare abstract class AbstractFirebaseAdminTestContextInstanceChild<F ex
  */
 export declare const firebaseAdminTestBuilder: import("@dereekb/util/test").TestContextBuilderFunction<FirebaseAdminTestContextInstance, FirebaseAdminTestContextFixture, FirebaseAdminTestConfig>;
 export type FirebaseAdminTestContextFactory = TestContextFactory<FirebaseAdminTestContextFixture>;
+/**
+ * Default {@link FirebaseAdminTestContextFactory} created with an empty config.
+ *
+ * Use this to quickly set up a Firebase Admin test context in your test suites:
+ *
+ * @example
+ * ```ts
+ * firebaseAdminTestContextFactory((f) => {
+ *   it('should access firestore', () => {
+ *     expect(f.firestore).toBeDefined();
+ *   });
+ * });
+ * ```
+ */
 export declare const firebaseAdminTestContextFactory: FirebaseAdminTestContextFactory;
 /**
  * Convenience function to build a TestFirestoreContextFactory from a FirebaseAdminTestContextFactory.
@@ -74,4 +127,15 @@ export declare const firebaseAdminTestContextFactory: FirebaseAdminTestContextFa
  * @returns
  */
 export declare function firebaseAdminFirestoreContextFixture(factory: TestContextFactory<TestContextFixture<FirebaseAdminTestContextInstance>>): JestTestFirestoreContextFactory;
+/**
+ * Sets up a {@link TestFirestoreContextFixture} as a child context within an existing
+ * {@link FirebaseAdminTestContextInstance} fixture.
+ *
+ * Unlike {@link firebaseAdminFirestoreContextFixture}, this function operates directly on a fixture
+ * reference rather than a factory, making it suitable for composing Firestore tests inside a
+ * `describe` block that already has a Firebase Admin context available.
+ *
+ * @param f - The parent fixture providing the Admin test context instance.
+ * @param buildTests - Callback that receives the Firestore fixture and registers test cases.
+ */
 export declare function firebaseAdminFirestoreContextWithFixture(f: TestContextFixture<FirebaseAdminTestContextInstance>, buildTests: BuildTestsWithContextFunction<TestFirestoreContextFixture>): void;

package/test/src/lib/firebase/firebase.admin.function.d.ts

@@ -6,7 +6,29 @@ import { type TestFirebaseStorageContext, type TestFirebaseStorageInstance, type
 import { AbstractTestContextFixture, type TestContextFactory, type TestContextFixture } from '@dereekb/util/test';
 import { type FirebaseAdminTestContext, FirebaseAdminTestContextInstance } from './firebase.admin';
 import { type Storage as GoogleCloudStorage } from '@google-cloud/storage';
+/**
+ * Initializes (or re-initializes) the firebase-functions-test singleton used by all admin function tests.
+ *
+ * Must be called after {@link initFirebaseAdminTestEnvironment}. When `reroll` is true, a fresh
+ * GCloud project ID is generated so successive test suites run against isolated projects.
+ *
+ * @param reroll - When `true`, generates a new project ID instead of reusing the current one.
+ * @returns The initialized {@link FeaturesList} singleton.
+ *
+ * @throws Error if `initFirebaseAdminTestEnvironment()` has not been called.
+ *
+ * @example
+ * ```ts
+ * setupFirebaseAdminFunctionTestSingleton();
+ * ```
+ */
 export declare function setupFirebaseAdminFunctionTestSingleton(reroll?: boolean): FeaturesList;
+/**
+ * Convenience wrapper around {@link setupFirebaseAdminFunctionTestSingleton} that always generates
+ * a new GCloud project ID, ensuring complete isolation between test runs.
+ *
+ * @returns The re-initialized {@link FeaturesList} singleton.
+ */
 export declare function rerollFirebaseAdminFunctionTestSingleton(): FeaturesList;
 export interface FirebaseAdminFunctionTestConfig {
     /**
@@ -18,9 +40,30 @@ export interface FirebaseAdminFunctionTestConfig {
      */
     useFunctionSingletonContext: boolean;
 }
+/**
+ * Test context type for Firebase Admin function tests.
+ *
+ * Currently an alias for {@link FirebaseAdminTestContext}; exists as a semantic boundary
+ * so function-specific extensions can be added without changing downstream signatures.
+ */
 export type FirebaseAdminFunctionTestContext = FirebaseAdminTestContext;
+/**
+ * Combined interface providing both the {@link FirebaseAdminFunctionTestContext} services
+ * and the {@link TestContextFixture} lifecycle for a {@link FirebaseAdminFunctionTestContextInstance}.
+ *
+ * Useful when test helpers need access to both the Firebase services and the fixture's
+ * `instance` / `parent` references in a single type constraint.
+ */
 export interface FullFirebaseAdminFunctionTestContext extends FirebaseAdminFunctionTestContext, TestContextFixture<FirebaseAdminFunctionTestContextInstance> {
 }
+/**
+ * Fixture that wraps a {@link FirebaseAdminFunctionTestContextInstance} and forwards
+ * all {@link FirebaseAdminFunctionTestContext} properties to the underlying instance.
+ *
+ * Created automatically by {@link firebaseAdminFunctionTestBuilder}; tests receive this
+ * fixture and use it to access the Firebase Admin app, Firestore, Auth, Storage, and the
+ * firebase-functions-test wrapper during each test lifecycle.
+ */
 export declare class FirebaseAdminFunctionTestContextFixture extends AbstractTestContextFixture<FirebaseAdminFunctionTestContextInstance> implements FirebaseAdminFunctionTestContext {
     get app(): admin.app.App;
     get auth(): Auth;
@@ -32,13 +75,37 @@ export declare class FirebaseAdminFunctionTestContextFixture extends AbstractTes
     get storageContext(): TestFirebaseStorageContext;
     get fnWrapper(): import("./firebase.function").FirebaseAdminCloudFunctionWrapper;
 }
+/**
+ * Concrete instance that extends {@link FirebaseAdminTestContextInstance} with the
+ * firebase-functions-test {@link FeaturesList} needed to wrap and invoke Cloud Functions
+ * in an emulated environment.
+ *
+ * Each instance holds a lazily-created {@link FirebaseAdminCloudFunctionWrapper} via `fnWrapper`
+ * so Cloud Functions can be wrapped and invoked against the test project.
+ */
 export declare class FirebaseAdminFunctionTestContextInstance extends FirebaseAdminTestContextInstance implements FirebaseAdminFunctionTestContext {
     readonly instance: FeaturesList;
     private _fnWrapper;
     constructor(instance: FeaturesList, app: admin.app.App);
     get fnWrapper(): import("./firebase.function").FirebaseAdminCloudFunctionWrapper;
 }
+/**
+ * Module-level default for {@link FirebaseAdminFunctionTestConfig.useFunctionSingletonContext}.
+ *
+ * When `false` (the default), each test suite gets its own firebase-functions-test instance
+ * with a unique project ID. Change via {@link setDefaultFirebaseAdminFunctionTestUseFunctionSingleton}.
+ */
 export declare let DEFAULT_FIREBASE_ADMIN_FUNCTION_TEST_USE_FUNCTION_SINGLETON_CONTEXT: boolean;
+/**
+ * Globally sets whether new {@link FirebaseAdminFunctionTestConfig} instances default to
+ * singleton mode. Primarily used in global test setup files.
+ *
+ * @example
+ * ```ts
+ * // in jest globalSetup
+ * setDefaultFirebaseAdminFunctionTestUseFunctionSingleton(true);
+ * ```
+ */
 export declare function setDefaultFirebaseAdminFunctionTestUseFunctionSingleton(use: boolean): void;
 /**
  * A TestContextBuilderFunction for building firebase test context factories using firebase-admin.
@@ -46,5 +113,22 @@ export declare function setDefaultFirebaseAdminFunctionTestUseFunctionSingleton(
  * This can be used to easily build a testing context that sets up RulesTestEnvironment for tests that sets itself up and tears itself down.
  */
 export declare const firebaseAdminFunctionTestBuilder: import("@dereekb/util/test").TestContextBuilderFunction<FirebaseAdminTestContextInstance, FirebaseAdminFunctionTestContextFixture, FirebaseAdminFunctionTestConfig>;
+/**
+ * Factory type that produces a {@link FirebaseAdminFunctionTestContextFixture} for each test suite.
+ */
 export type FirebaseAdminFunctionTestContextFactory = TestContextFactory<FirebaseAdminFunctionTestContextFixture>;
+/**
+ * Pre-built factory using default configuration. Drop this into any test file to get
+ * a fully configured Firebase Admin + functions test context with automatic setup/teardown.
+ *
+ * @example
+ * ```ts
+ * firebaseAdminFunctionTestContextFactory((f) => {
+ *   it('should invoke cloud function', async () => {
+ *     const app = f.app;
+ *     // ... test logic
+ *   });
+ * });
+ * ```
+ */
 export declare const firebaseAdminFunctionTestContextFactory: FirebaseAdminFunctionTestContextFactory;