Rules-unit-testing 套件

函式

函式 說明
assertFails(未通過審查) 以「權限遭拒」聲明保證遭拒錯誤。可用來聲明要求安全性規則拒絕的特定要求。請參閱以下範例。這個函式可辨識來自資料庫、Firestore 和 Storage JS SDK 的權限遭拒錯誤。
assertSucceeds(四) 以「權限遭拒」聲明保證遭拒錯誤。此為免人工管理函式,可依原樣傳回所傳遞的承諾,但可用於測試程式碼中的文件用途,強調特定要求應成功 (例如規則允許)。
InitialTestEnvironment(config) 初始化規則單元測試的測試環境。請先呼叫此函式以進行測試設定。需要執行模擬器。如果未指定主機和通訊埠,這個函式會嘗試透過環境變數或 Firebase Emulator 中心來探索這些模擬器。強烈建議您為用於測試的模擬器指定安全性規則。請參閱下方的簡短範例。
withFunctionTriggersDisabled(fn) 執行停用背景 Cloud Functions 觸發條件的設定函式。這可以用來將資料匯入即時資料庫或 Cloud Firestore 模擬器,而不觸發本機模擬的 Cloud Functions。這個方法僅適用於 Firebase CLI 8.13.0 以上版本。只有在模擬器中樞主機:通訊埠是由環境變數 FIREBASE_EMULATOR_HUB 指定時,這個超載才會正常運作。
withFunctionTriggersDisabled(hub, fn) 執行停用背景 Cloud Functions 觸發條件的設定函式。這可以用來將資料匯入即時資料庫或 Cloud Firestore 模擬器,而不觸發本機模擬的 Cloud Functions。這個方法僅適用於 Firebase CLI 8.13.0 以上版本。模擬器中心必須處於執行中狀態,以便在這個超載中指定主機和通訊埠。

介面

介面 說明
HostAndPort 包含模擬器主機名稱和通訊埠編號的物件。
RulesTestContext 代表用戶端的測試內容。可用於存取規則單元測試的模擬器。
RulesTestEnvironment 用來控制規則單元測試環境的物件。可用於針對不同驗證情況建立 RulesTestContext。
TestEnvironmentConfig 單元測試環境設定,包括模擬器。

型別別名

類型別名 說明
EmulatorConfig 特定模擬器的設定。
TokenOptions 用於測試模擬使用者權杖的其他選項,包括開發人員指定的自訂憑證附加資訊,或 Firebase 驗證權杖酬載的選用覆寫值。

assertFails()

以「權限遭拒」聲明保證遭拒錯誤。

可用來聲明特定要求遭到安全性規則拒絕。請參閱以下範例。這個函式可辨識來自資料庫、Firestore 和 Storage JS SDK 的權限遭拒錯誤。

簽名:

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

參數

參數 類型 說明
承諾<任何> 承諾接受的承諾

傳回:

承諾<任何>

如 pr 遭拒並顯示「權限遭拒」的承諾使用合約。如果 pr 因其他錯誤或已解決而遭拒,傳回的保證會遭拒。

範例

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

assertSucceeds()

聲明承諾可以成功。

這是不作業函式,可依原樣傳回所傳遞的承諾,但可用於測試程式碼中的文件目的,強調特定要求應成功 (例如,規則允許)。

簽名:

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'), { ... });

InitialTestEnvironment()

初始化規則單元測試的測試環境。請先呼叫此函式進行測試設定。

必須使用模擬器才能執行。如果未指定主機和通訊埠,這個函式會嘗試透過環境變數或透過 Firebase Emulator 中心來探索這些模擬器。強烈建議您為用於測試的模擬器指定安全性規則。請參閱下方的簡短範例。

簽名:

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

參數

參數 類型 說明
config TestEnvironmentConfig 以便進行模擬器的設定如果可以找到這些欄位,則大多數為選用欄位

傳回:

Promise<RulesTestEnvironment>

保證能夠以準備好測試的環境解決,或拒絕出現錯誤。

範例

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 觸發條件的設定函式。這可以用來將資料匯入即時資料庫或 Cloud Firestore 模擬器,而不觸發本機模擬 Cloud Functions。

這個方法僅適用於 Firebase CLI 8.13.0 以上版本。只有在模擬器中樞主機:通訊埠是由環境變數 FIREBASE_EMULATOR_HUB 指定時,這個超載才會正常運作。

簽名:

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

參數

參數 類型 說明
fn () =>結果 |承諾<TResult> 可同步或非同步的函式 (傳回承諾產品)

傳回:

承諾<TResult>

withFunctionTriggersDisabled()

執行停用背景 Cloud Functions 觸發條件的設定函式。這可以用來將資料匯入即時資料庫或 Cloud Firestore 模擬器,而不觸發本機模擬 Cloud Functions。

這個方法僅適用於 Firebase CLI 8.13.0 以上版本。模擬器中心必須處於執行中狀態,以便在這個超載中指定主機和通訊埠。

簽名:

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

參數

參數 類型 說明
中樞 { host: string;通訊埠:號碼;} Emulator Hub 的主機和通訊埠 (例如:{host: 'localhost', port: 4400})
fn () =>結果 |承諾<TResult> 可同步或非同步的函式 (傳回承諾產品)

傳回:

承諾<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;
};