rules-unit-testing 软件包

函数

函数	说明
assertFails(pr)	使用“没有权限”断言要被拒绝的 promise错误。用于断言要被安全规则拒绝的特定请求。请查看下面的示例。此函数可识别 Database、Firestore 和 Storage JS SDK 中的权限遭拒错误。
assertSucceeds(pr)	使用“没有权限”断言要被拒绝的 promise错误。这是一个空操作函数，按原样返回传递的 promise，但可在测试代码中用作文档记录，以强调特定请求应成功（例如，规则允许）。
initializeTestEnvironment(config)	初始化规则单元测试的测试环境。对于测试设置，请先调用此函数。需要运行模拟器。如果未指定主机和端口，此函数会尝试通过环境变量或 Firebase Emulator Hub 发现这些模拟器。强烈建议为用于测试的模拟器指定安全规则。请参见下面的最小示例。
withFunctionTriggersDisabled(fn)	在停用后台 Cloud Functions 触发器的情况下运行设置函数。此方法可用于将数据导入 Realtime Database 或 Cloud Firestore 模拟器，而不会触发本地模拟的 Cloud Functions 函数。此方法仅适用于 Firebase CLI 8.13.0 或更高版本。只有在环境变量 FIREBASE_EMULATOR_HUB 指定模拟器 hub host:port 时，此过载才有效。
withFunctionTriggersDisabled(hub、fn)	在停用后台 Cloud Functions 触发器的情况下运行设置函数。此方法可用于将数据导入 Realtime Database 或 Cloud Firestore 模拟器，而不会触发本地模拟的 Cloud Functions 函数。此方法仅适用于 Firebase CLI 8.13.0 或更高版本。模拟器 hub 必须正在运行，并且在此过载中指定了主机和端口。

接口

接口	说明
HostAndPort	包含模拟器主机名和端口号的对象。
RulesTestContext	表示客户端的测试上下文。可用于访问模拟器以进行规则单元测试。
RulesTestEnvironment	用于控制规则单元测试环境的对象。可用于针对不同的身份验证情况创建 RulesTestContext。
TestEnvironmentConfig	配置单元测试环境，包括模拟器。

类型别名

类型别名	说明
EmulatorConfig	给定模拟器的配置。
TokenOptions	用于测试的模拟用户令牌的更多选项，包括开发者指定的自定义声明或 Firebase 身份验证令牌载荷的可选替换项。

assertFails()

使用“没有权限”断言要被拒绝的 promise错误。

适用于断言要被安全规则拒绝的特定请求。请查看下面的示例。此函数可识别 Database、Firestore 和 Storage JS SDK 中的权限遭拒错误。

签名：

export declare function assertFails(pr: Promise<any>): Promise<any>;

参数

参数	类型	说明
商品	承诺<any>	要断言的 promise

返回：

承诺<any>

在 pr 因“没有权限”而遭拒时实现的 Promise。如果 pr 因任何其他错误而遭拒或已得到解决，返回的 promise 将拒绝。

示例

const unauthed = testEnv.unauthenticatedContext();
await assertFails(getDoc(unauthed.firestore(), '/private/doc'), { ... });

assertSucceeds()

断言能够成功的承诺。

这是一个空操作函数，按原样返回传递的 promise，但可在测试代码中用作文档记录，以强调特定请求应成功（例如，规则允许）。

签名：

export declare function assertSucceeds<T>(pr: Promise<T>): Promise<T>;

参数

参数	类型	说明
商品	承诺<T>

返回：

承诺<T>

示例

const alice = testEnv.authenticatedContext('alice');
await assertSucceeds(getDoc(alice.firestore(), '/doc/readable/by/alice'), { ... });

initializeTestEnvironment()

初始化规则单元测试的测试环境。对于测试设置，请先调用此函数。

要求模拟器处于运行状态。如果未指定主机和端口，此函数会尝试通过环境变量或 Firebase Emulator Hub 发现这些模拟器。强烈建议为用于测试的模拟器指定安全规则。请参见下面的最小示例。

签名：

export declare function initializeTestEnvironment(config: TestEnvironmentConfig): Promise<RulesTestEnvironment>;

参数

参数	类型	说明
config	TestEnvironmentConfig	模拟器的配置如果可以发现大多数字段，则它们都是选填的

返回：

Promise<RulesTestEnvironment>

一个在准备测试的环境中进行解析或在出现错误时拒绝的 promise。

示例

const testEnv = await initializeTestEnvironment({
  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()

在停用后台 Cloud Functions 触发器的情况下运行设置函数。这可用于将数据导入 Realtime Database 或 Cloud Firestore 模拟器，而不会触发本地模拟的 Cloud Functions 函数。

此方法仅适用于 Firebase CLI 8.13.0 或更高版本。只有在环境变量 FIREBASE_EMULATOR_HUB 指定模拟器 hub host:port 时，此过载才有效。

签名：

export declare function withFunctionTriggersDisabled<TResult>(fn: () => TResult | Promise<TResult>): Promise<TResult>;

参数

参数	类型	说明
Fn	() =>TResult |Promise<TResult>	可能是同步函数或异步函数（返回一个 promise）

返回：

Promise<TResult>

withFunctionTriggersDisabled()

在停用后台 Cloud Functions 触发器的情况下运行设置函数。这可用于将数据导入 Realtime Database 或 Cloud Firestore 模拟器，而不会触发本地模拟的 Cloud Functions 函数。

此方法仅适用于 Firebase CLI 8.13.0 或更高版本。模拟器 hub 必须正在运行，并且在此过载中指定了主机和端口。

签名：

export declare function withFunctionTriggersDisabled<TResult>(hub: {
    host: string;
    port: number;
}, fn: () => TResult | Promise<TResult>): Promise<TResult>;

参数

参数	类型	说明
hub	{ host: string;port：number；}	模拟器中心的主机和端口（例如：{host: 'localhost', port: 4400}）
Fn	() =>TResult |Promise<TResult>	可能是同步函数或异步函数（返回一个 promise）

返回：

Promise<TResult>

模拟器配置

给定模拟器的配置。

签名：

export declare type EmulatorConfig = {
    rules?: string;
} & (HostAndPort | {});

TokenOptions

用于测试的模拟用户令牌的更多选项，包括开发者指定的自定义声明或 Firebase 身份验证令牌载荷的可选替换项。

签名：

export declare type TokenOptions = {
    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?: {
            [provider in FirebaseSignInProvider]?: string[];
        };
    };
    aud?: string;
    iss?: string;
    [claim: string]: unknown;
    uid?: never;
    sub?: never;
    user_id?: never;
};