Functions

Interfaces

Type Aliases

assertFails()

Assert the promise to be rejected with a "permission denied" error.

Useful to assert a certain request to be denied by Security Rules. See example below. This function recognizes permission-denied errors from Database, Firestore, and Storage JS SDKs.

Signature:

exportdeclarefunctionassertFails(pr:Promise<any>):Promise<any>;

Parameters

Returns:

Promise<any>

a Promise that is fulfilled if pr is rejected with "permission denied". If pr is rejected with any other error or resolved, the returned promise rejects.

Example

constunauthed=testEnv.unauthenticatedContext();awaitassertFails(getDoc(unauthed.firestore(),'/private/doc'),{...});

assertSucceeds()

Assert the promise to be successful.

This is a no-op function returning the passed promise as-is, but can be used for documentational purposes in test code to emphasize that a certain request should succeed (e.g. allowed by rules).

Signature:

exportdeclarefunctionassertSucceeds<T>(pr:Promise<T>):Promise<T>;

Parameters

Returns:

Promise<T>

Example

constalice=testEnv.authenticatedContext('alice');awaitassertSucceeds(getDoc(alice.firestore(),'/doc/readable/by/alice'),{...});

initializeTestEnvironment()

Initializes a test environment for rules unit testing. Call this function first for test setup.

Requires emulators to be running. This function tries to discover those emulators via environment variables or through the Firebase Emulator hub if hosts and ports are unspecified. It is strongly recommended to specify security rules for emulators used for testing. See minimal example below.

Signature:

exportdeclarefunctioninitializeTestEnvironment(config:TestEnvironmentConfig):Promise<RulesTestEnvironment>;

Parameters

Returns:

Promise<RulesTestEnvironment>

a promise that resolves with an environment ready for testing, or rejects on error.

Example

consttestEnv=awaitinitializeTestEnvironment({firestore:{rules:fs.readFileSync("/path/to/firestore.rules","utf8"),// Load rules from file// host and port can be omitted if they can be discovered from the hub.},// ...});

withFunctionTriggersDisabled()

Run a setup function with background Cloud Functions triggers disabled. This can be used to import data into the Realtime Database or Cloud Firestore emulator without triggering locally emulated Cloud Functions.

This method only works with Firebase CLI version 8.13.0 or higher. This overload works only if the Emulator hub host:port is specified by the environment variable FIREBASE_EMULATOR_HUB.

Signature:

exportdeclarefunctionwithFunctionTriggersDisabled<TResult>(fn:()=>TResult|Promise<TResult>):Promise<TResult>;

Parameters

Returns:

Promise<TResult>

withFunctionTriggersDisabled()

Run a setup function with background Cloud Functions triggers disabled. This can be used to import data into the Realtime Database or Cloud Firestore emulator without triggering locally emulated Cloud Functions.

This method only works with Firebase CLI version 8.13.0 or higher. The Emulator hub must be running, which host and port are specified in this overload.

Signature:

exportdeclarefunctionwithFunctionTriggersDisabled<TResult>(hub:{host:string;port:number;},fn:()=>TResult|Promise<TResult>):Promise<TResult>;

Parameters

Returns:

Promise<TResult>

EmulatorConfig

Configuration for a given emulator.

Signature:

exportdeclaretypeEmulatorConfig={rules?:string;} &(HostAndPort|{});

TokenOptions

More options for the mock user token to be used for testing, including developer-specfied custom claims or optional overrides for Firebase Auth token payloads.

Signature:

exportdeclaretypeTokenOptions={iat?:number;exp?:number;auth_time?:number;provider_id?:'anonymous';email?:string;email_verified?:boolean;phone_number?:string;name?:string;picture?:string;firebase?:{sign_in_provider:FirebaseSignInProvider;identities?:{[providerinFirebaseSignInProvider]?:string[];};};aud?:string;iss?:string;[claim:string]:unknown;uid?:never;sub?:never;user_id?:never;};