雲功能的單元測試

本頁介紹了為您的功能編寫單元測試的最佳實踐和工具，例如將成為持續集成 (CI) 系統一部分的測試。為了簡化測試，Firebase 提供了適用於 Cloud Functions 的 Firebase Test SDK。它作為firebase-functions-test在 npm 上分發，並且是firebase-functions的配套測試 SDK。用於 Cloud Functions 的 Firebase 測試 SDK：

• 負責為您的測試進行適當的設置和拆卸，例如設置和取消設置firebase-functions所需的環境變量。
• 生成示例數據和事件上下文，以便您只需指定與測試相關的字段。

測試設置

通過在函數文件夾中運行以下命令來安裝firebase-functions-test和測試框架Mocha ：

npm install --save-dev firebase-functions-test
npm install --save-dev mocha

接下來在 functions 文件夾中創建一個test文件夾，在其中為您的測試代碼創建一個新文件，並將其命名為index.test.js之類的名稱。

最後，修改functions/package.json添加以下內容：

"scripts": {
  "test": "mocha --reporter spec"
}

編寫測試後，您可以通過在函數目錄中運行npm test來運行它們。

為 Cloud Functions 初始化 Firebase 測試 SDK

有兩種使用firebase-functions-test方法：

1. 在線模式（推薦）：編寫與專用於測試的 Firebase 項目交互的測試，以便數據庫寫入、用戶創建等實際發生，並且您的測試代碼可以檢查結果。這也意味著您的函數中使用的其他 Google SDK 也可以正常工作。
2. 離線模式：編寫沒有副作用的孤立和離線單元測試。這意味著任何與 Firebase 產品交互的方法調用（例如寫入數據庫或創建用戶）都需要存根。如果您有 Cloud Firestore 或實時數據庫功能，通常不建議使用離線模式，因為它會大大增加您的測試代碼的複雜性。

在線模式初始化SDK（推薦）

如果您想編寫與測試項目交互的測試，則需要提供通過firebase-admin初始化應用程序所需的項目配置值，以及服務帳戶密鑰文件的路徑。

要獲取 Firebase 項目的配置值：

1. 在Firebase 控制台中打開您的項目設置。
2. 在您的應用中，選擇所需的應用。

3. 在右側窗格中，選擇下載 Apple 和 Android 應用程序配置文件的選項。

   對於 Web 應用程序，選擇配置以顯示配置值。

要創建密鑰文件：

1. 打開 Google Cloud Console 的服務帳戶面板。
2. 選擇 App Engine 默認服務帳戶，然後使用右側的選項菜單選擇Create key 。
3. 出現提示時，選擇 JSON 作為密鑰類型，然後單擊創建。

保存密鑰文件後，初始化SDK：

// At the top of test/index.test.js
const test = require('firebase-functions-test')({
  databaseURL: 'https://my-project.firebaseio.com',
  storageBucket: 'my-project.appspot.com',
  projectId: 'my-project',
}, 'path/to/serviceAccountKey.json');

離線模式初始化SDK

如果您想編寫完全離線的測試，您可以不帶任何參數初始化 SDK：

// At the top of test/index.test.js
const test = require('firebase-functions-test')();

模擬配置值

如果您在函數代碼中使用functions.config() ，則可以模擬配置值。例如，如果functions/index.js包含以下代碼：

const functions = require('firebase-functions');
const key = functions.config().stripe.key;

然後你可以像這樣模擬你的測試文件中的值：

// Mock functions config values
test.mockConfig({ stripe: { key: '23wr42ewr34' }});

導入你的函數

要導入您的函數，請使用require將您的主要函數文件作為模塊導入。請確保僅在初始化firebase-functions-test和模擬配置值後執行此操作。

// after firebase-functions-test has been initialized
const myFunctions = require('../index.js'); // relative path to functions code

如果您在離線模式下初始化了firebase-functions-test ，並且您的函數代碼中有admin.initializeApp() ，那麼您需要在導入函數之前對其進行存根：

// If index.js calls admin.initializeApp at the top of the file,
// we need to stub it out before requiring index.js. This is because the
// functions will be executed as a part of the require process.
// Here we stub admin.initializeApp to be a dummy function that doesn't do anything.
adminInitStub = sinon.stub(admin, 'initializeApp');
// Now we can require index.js and save the exports inside a namespace called myFunctions.
myFunctions = require('../index');
test.offline.js

測試後台（非 HTTP）功能

測試非 HTTP 功能的過程包括以下步驟：

1. 用test.wrap方法包裝你想測試的函數
2. 構建測試數據
3. 使用您構建的測試數據和您想要指定的任何事件上下文字段調用包裝函數。
4. 對行為做出斷言。

首先包裝您要測試的功能。假設你在functions/index.js中有一個名為makeUppercase的函數，你想測試它。在functions/test/index.test.js中寫入如下內容

// "Wrap" the makeUpperCase function from index.js
const myFunctions = require('../index.js');
const wrapped = test.wrap(myFunctions.makeUppercase);

wrapped是一個在調用時調用makeUppercase函數。 wrapped有兩個參數：

1. 數據（必需）：發送到makeUppercase數據。這直接對應於發送到您編寫的函數處理程序的第一個參數。 firebase-functions-test提供了構建自定義數據或示例數據的方法。
2. eventContextOptions （可選）：您要指定的事件上下文的字段。事件上下文是發送到您編寫的函數處理程序的第二個參數。如果您在調用wrapped時不包含eventContextOptions參數，則仍會生成帶有合理字段的事件上下文。您可以通過在此處指定來覆蓋某些生成的字段。請注意，您只需包含要覆蓋的字段。將生成您未覆蓋的任何字段。

const data = … // See next section for constructing test data

// Invoke the wrapped function without specifying the event context.
wrapped(data);

// Invoke the function, and specify params
wrapped(data, {
  params: {
    pushId: '234234'
  }
});

// Invoke the function, and specify auth and auth Type (for real time database functions only)
wrapped(data, {
  auth: {
    uid: 'jckS2Q0'
  },
  authType: 'USER'
});

// Invoke the function, and specify all the fields that can be specified
wrapped(data, {
  eventId: 'abc',
  timestamp: '2018-03-23T17:27:17.099Z',
  params: {
    pushId: '234234'
  },
  auth: {
    uid: 'jckS2Q0' // only for real time database functions
  },
  authType: 'USER' // only for real time database functions
});

構建測試數據

包裝函數的第一個參數是用於調用底層函數的測試數據。有許多方法可以構建測試數據。

使用自定義數據

firebase-functions-test有許多函數可用於構建測試函數所需的數據。例如，使用test.firestore.makeDocumentSnapshot創建 Firestore DocumentSnapshot 。第一個參數是數據，第二個參數是完整的引用路徑，還有一個可選的第三個參數用於您可以指定的快照的其他屬性。

// Make snapshot
const snap = test.firestore.makeDocumentSnapshot({foo: 'bar'}, 'document/path');
// Call wrapped function with the snapshot
const wrapped = test.wrap(myFunctions.myFirestoreDeleteFunction);
wrapped(snap);

如果您正在測試onUpdate或onWrite函數，則需要創建兩個快照：一個用於之前狀態，一個用於之後狀態。然後，您可以使用makeChange方法使用這些快照創建Change對象。

// Make snapshot for state of database beforehand
const beforeSnap = test.firestore.makeDocumentSnapshot({foo: 'bar'}, 'document/path');
// Make snapshot for state of database after the change
const afterSnap = test.firestore.makeDocumentSnapshot({foo: 'faz'}, 'document/path');
const change = test.makeChange(beforeSnap, afterSnap);
// Call wrapped function with the Change object
const wrapped = test.wrap(myFunctions.myFirestoreUpdateFunction);
wrapped(change);

有關所有其他數據類型的類似功能，請參閱API 參考。

使用示例數據

如果您不需要自定義測試中使用的數據，那麼firebase-functions-test提供了為每種函數類型生成示例數據的方法。

// For Firestore onCreate or onDelete functions
const snap = test.firestore.exampleDocumentSnapshot();
// For Firestore onUpdate or onWrite functions
const change = test.firestore.exampleDocumentSnapshotChange();

有關獲取每種函數類型的示例數據的方法，請參閱API 參考。

使用存根數據（用於離線模式）

如果您在離線模式下初始化了 SDK，並且正在測試 Cloud Firestore 或實時數據庫功能，則應使用帶有存根的普通對象，而不是創建實際的DocumentSnapshot或DataSnapshot 。

假設您正在為以下函數編寫單元測試：

// Listens for new messages added to /messages/:pushId/original and creates an
// uppercase version of the message to /messages/:pushId/uppercase
exports.makeUppercase = functions.database.ref('/messages/{pushId}/original')
    .onCreate((snapshot, context) => {
      // Grab the current value of what was written to the Realtime Database.
      const original = snapshot.val();
      functions.logger.log('Uppercasing', context.params.pushId, original);
      const uppercase = original.toUpperCase();
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to the Firebase Realtime Database.
      // Setting an "uppercase" sibling in the Realtime Database returns a Promise.
      return snapshot.ref.parent.child('uppercase').set(uppercase);
    });
index.js

在函數內部， snap使用了兩次：

• snap.val()
• snap.ref.parent.child('uppercase').set(uppercase)

在測試代碼中，創建一個普通對象，這兩個代碼路徑都可以在其中工作，並使用Sinon來存根這些方法。

// The following lines creates a fake snapshot, 'snap', which returns 'input' when snap.val() is called,
// and returns true when snap.ref.parent.child('uppercase').set('INPUT') is called.
const snap = {
  val: () => 'input',
  ref: {
    parent: {
      child: childStub,
    }
  }
};
childStub.withArgs(childParam).returns({ set: setStub });
setStub.withArgs(setParam).returns(true);
test.offline.js

做出斷言

在初始化 SDK、包裝函數和構造數據後，您可以使用構造的數據調用包裝函數並對行為進行斷言。您可以使用諸如Chai之類的庫來進行這些斷言。

在在線模式下進行斷言

如果您在在線模式下初始化了適用於 Cloud Functions 的 Firebase 測試 SDK，則可以使用firebase-admin SDK 斷言所需的操作（例如數據庫寫入）已經發生。

下面的示例斷言“INPUT”已寫入測試項目的數據庫。

// Create a DataSnapshot with the value 'input' and the reference path 'messages/11111/original'.
const snap = test.database.makeDataSnapshot('input', 'messages/11111/original');

// Wrap the makeUppercase function
const wrapped = test.wrap(myFunctions.makeUppercase);
// Call the wrapped function with the snapshot you constructed.
return wrapped(snap).then(() => {
  // Read the value of the data at messages/11111/uppercase. Because `admin.initializeApp()` is
  // called in functions/index.js, there's already a Firebase app initialized. Otherwise, add
  // `admin.initializeApp()` before this line.
  return admin.database().ref('messages/11111/uppercase').once('value').then((createdSnap) => {
    // Assert that the value is the uppercased version of our input.
    assert.equal(createdSnap.val(), 'INPUT');
  });
});
test.online.js

在離線模式下進行斷言

您可以對函數的預期返回值進行斷言：

const childParam = 'uppercase';
const setParam = 'INPUT';
// Stubs are objects that fake and/or record function calls.
// These are excellent for verifying that functions have been called and to validate the
// parameters passed to those functions.
const childStub = sinon.stub();
const setStub = sinon.stub();
// The following lines creates a fake snapshot, 'snap', which returns 'input' when snap.val() is called,
// and returns true when snap.ref.parent.child('uppercase').set('INPUT') is called.
const snap = {
  val: () => 'input',
  ref: {
    parent: {
      child: childStub,
    }
  }
};
childStub.withArgs(childParam).returns({ set: setStub });
setStub.withArgs(setParam).returns(true);
// Wrap the makeUppercase function.
const wrapped = test.wrap(myFunctions.makeUppercase);
// Since we've stubbed snap.ref.parent.child(childParam).set(setParam) to return true if it was
// called with the parameters we expect, we assert that it indeed returned true.
return assert.equal(wrapped(snap), true);
test.offline.js

您還可以使用Sinon 間諜來斷言某些方法已被調用，並且具有您期望的參數。

測試 HTTP 功能

要測試 HTTP onCall 函數，請使用與測試後台函數相同的方法。

如果您正在測試 HTTP onRequest 函數，則應在以下情況下使用firebase-functions-test ：

• 你使用functions.config()
• 您的函數與 Firebase 項目或其他 Google API 交互，並且您希望使用真實的 Firebase 項目及其憑據進行測試。

HTTP onRequest 函數有兩個參數：一個請求對象和一個響應對象。以下是您可以如何測試addMessage()示例函數：

• 覆蓋響應對像中的重定向函數，因為sendMessage()調用它。
• 在重定向函數中，使用chai.assert來幫助斷言應該使用哪些參數調用重定向函數：

// A fake request object, with req.query.text set to 'input'
const req = { query: {text: 'input'} };
// A fake response object, with a stubbed redirect function which asserts that it is called
// with parameters 303, 'new_ref'.
const res = {
  redirect: (code, url) => {
    assert.equal(code, 303);
    assert.equal(url, 'new_ref');
    done();
  }
};

// Invoke addMessage with our fake request and response objects. This will cause the
// assertions in the response object to be evaluated.
myFunctions.addMessage(req, res);
test.offline.js

測試清理

在測試代碼的最後，調用清理函數。這會取消設置 SDK 在初始化時設置的環境變量，並刪除如果您使用 SDK 創建實時數據庫DataSnapshot或 Firestore DocumentSnapshot可能已經創建的 Firebase 應用程序。

test.cleanup();

查看完整示例並了解更多信息

您可以在 Firebase GitHub 存儲庫中查看完整示例。

• 在在線模式下測試實時數據庫和 HTTP 功能
• 在離線模式下測試實時數據庫和 HTTP 功能

要了解更多信息，請參閱firebase-functions-test的API 參考。