Cloud Functions 單元測試

本頁將說明為函式編寫單元測試的最佳做法和工具，例如持續整合 (CI) 系統中的測試。為簡化測試流程，Firebase 提供 Cloud Functions 的 Firebase Test SDK。它以 firebase-functions-test 的形式在 npm 上發布，是 firebase-functions 的隨附測試 SDK。Cloud Functions 的 Firebase Test SDK：

• 負責適當的測試設定和拆除作業，例如設定和取消設定 firebase-functions 所需的環境變數。
• 產生樣本資料和事件背景，讓您只需指定與測試相關的欄位。

注意： firebase-functions-test 只能用於使用 firebase-functions 2.0.0 以上版本編寫的函式。

測試設定

請在函式資料夾中執行下列指令，同時安裝 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 Test SDK」

使用 firebase-functions-test 的方式有兩種：

1. 線上模式 (建議)：編寫與專用於測試的 Firebase 專案互動的測試，以便實際執行資料庫寫入、使用者建立等作業，並讓測試程式碼檢查結果。這也表示函式中使用的其他 Google SDK 也能正常運作。
2. 離線模式：編寫無副作用的孤島式和離線單元測試。也就是說，任何與 Firebase 產品互動的呼叫方法 (例如寫入資料庫或建立使用者) 都需要進行暫存。如果您有 Cloud Firestore 或 Realtime Database 函式，一般不建議使用離線模式，因為這會大幅增加測試程式碼的複雜度。

在線上模式下初始化 SDK (建議做法)

如果您想編寫與測試專案互動的測試，就必須提供透過 firebase-admin 初始化應用程式所需的專案設定值，以及服務帳戶金鑰檔案的路徑。

如要取得 Firebase 專案的設定值，請按照下列步驟操作：

1. 在 Firebase 控制台中開啟專案設定。
2. 在「您的應用程式」中，選取所需應用程式。

3. 在右側窗格中，選取下載 Apple 和 Android 應用程式設定檔的選項。

   如果是網頁應用程式，請選取「Config」來顯示設定值。

如要建立金鑰檔案，請按照下列步驟操作：

1. 開啟 Google Cloud 主控台的「Service Accounts」窗格。
2. 選取 App Engine 預設服務帳戶，然後使用右側的選項選單選取「建立金鑰」。
3. 系統提示時，請選取 JSON 做為金鑰類型，然後按一下「Create」。

儲存金鑰檔案後，請初始化 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');

警告： 在程式碼中處理服務帳戶憑證時，請格外小心。請勿將這些金鑰提交至公開存放區、在用戶端應用程式中部署，或以任何可能危害 Firebase 專案安全的方式公開金鑰。

在離線模式下初始化 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/v1');
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()，則您需要在匯入函式之前先建立 Stub：

// 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 會使用 2 個參數：

1. data (必要)：要傳送至 makeUppercase 的資料。這會直接對應至傳送至您編寫的函式處理常式的第 1 個參數。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);

注意： 您只有在以線上模式初始化 SDK 時，才應為 Cloud Firestore 和 Realtime Database 建構自訂資料。否則，您應使用暫存資料，以免發生非預期的行為。

如要瞭解所有其他資料類型的類似函式，請參閱 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();

注意： 如果您是在線上模式中初始化 SDK，請只為 Cloud Firestore 和 Realtime Database 建構範例資料。否則，您應使用暫存資料，以免發生非預期的行為。

如要瞭解如何為每種函式類型取得範例資料，請參閱 API 參考資料。

使用模擬資料 (適用於離線模式)

如果您在離線模式下初始化 SDK，並且要測試 Cloud Firestore 或 Realtime Database 函式，則應使用具有虛設常數的純物件，而非建立實際的 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 Test 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 建立的 Firebase 應用程式 (如果您已使用 SDK 建立即時資料庫 DataSnapshot 或 Firestore DocumentSnapshot)。

test.cleanup();

查看完整範例並瞭解詳情

您可以在 Firebase GitHub 存放區中查看完整範例。

• 在線上模式中測試 Realtime Database 和 HTTP 函式
• 在離線模式中測試 Realtime Database 和 HTTP 函式

如需更多資訊，請參閱 firebase-functions-test 的 API 參考資料。