Check out what’s new from Firebase at Google I/O 2022. Learn more

Testowanie jednostkowe funkcji chmury

Na tej stronie opisano najlepsze praktyki i narzędzia do pisania testów jednostkowych dla funkcji, takich jak testy, które byłyby częścią systemu ciągłej integracji (CI). Aby ułatwić testowanie, Firebase udostępnia pakiet SDK Firebase Test dla Cloud Functions. Jest dystrybuowany w npm jako firebase-functions-test i jest towarzyszącym testowym pakietem SDK do firebase-functions . Pakiet Firebase Test SDK dla Cloud Functions:

  • Zajmuje się odpowiednią konfiguracją i usuwaniem testów, na przykład ustawianiem i usuwaniem ustawień zmiennych środowiskowych wymaganych przez firebase-functions .
  • Generuje przykładowe dane i kontekst zdarzenia, dzięki czemu wystarczy określić tylko pola, które są istotne dla testu.

Konfiguracja testowa

Zainstaluj zarówno firebase-functions-test , jak i Mocha , platformę testową, uruchamiając następujące polecenia w folderze funkcji:

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

Następnie utwórz folder test w folderze funkcji, utwórz w nim nowy plik dla kodu testowego i nazwij go mniej więcej tak jak index.test.js .

Na koniec zmodyfikuj functions/package.json , aby dodać następujące elementy:

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

Po napisaniu testów możesz je uruchomić, uruchamiając npm test w katalogu funkcji.

Inicjowanie pakietu SDK Firebase Test dla funkcji w chmurze

Istnieją dwa sposoby użycia firebase-functions-test :

  1. Tryb online (zalecany): pisz testy, które współdziałają z projektem Firebase przeznaczonym do testowania, tak aby zapisy bazy danych, tworzenie przez użytkowników itp. rzeczywiście miały miejsce, a Twój kod testowy mógł sprawdzić wyniki. Oznacza to również, że będą działać również inne pakiety Google SDK używane w Twoich funkcjach.
  2. Tryb offline: pisz testy jednostkowe w trybie Siled i offline bez skutków ubocznych. Oznacza to, że wszelkie wywołania metod, które wchodzą w interakcję z produktem Firebase (np. zapis do bazy danych lub utworzenie użytkownika), muszą zostać zablokowane. Korzystanie z trybu offline generalnie nie jest zalecane, jeśli masz funkcje Cloud Firestore lub Bazy danych czasu rzeczywistego, ponieważ znacznie zwiększa to złożoność kodu testowego.

Zainicjuj SDK w trybie online (zalecane)

Jeśli chcesz pisać testy, które współdziałają z projektem testowym, musisz podać wartości konfiguracji projektu, które są potrzebne do zainicjowania aplikacji za pomocą firebase-admin , oraz ścieżkę do pliku klucza konta usługi.

Aby pobrać wartości konfiguracyjne projektu Firebase:

  1. Otwórz ustawienia projektu w konsoli Firebase .
  2. W sekcji Twoje aplikacje wybierz żądaną aplikację.
  3. W prawym okienku wybierz opcję pobrania pliku konfiguracyjnego dla aplikacji Apple i Android.

    W przypadku aplikacji internetowych wybierz opcję Konfiguracja , aby wyświetlić wartości konfiguracyjne.

Aby utworzyć plik klucza:

  1. Otwórz panel Konta usług w Google Cloud Console.
  2. Wybierz domyślne konto usługi App Engine i użyj menu opcji po prawej stronie, aby wybrać Utwórz klucz .
  3. Po wyświetleniu monitu wybierz JSON jako typ klucza i kliknij Utwórz .

Po zapisaniu pliku klucza zainicjuj 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');

Zainicjuj SDK w trybie offline

Jeśli chcesz pisać testy całkowicie offline, możesz zainicjować SDK bez żadnych parametrów:

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

Mocowanie wartości konfiguracyjnych

Jeśli używasz functions.config() w kodzie funkcji, możesz zakpić wartości konfiguracyjne. Na przykład, jeśli functions/index.js zawiera następujący kod:

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

Następnie możesz zakpić wartość w pliku testowym w następujący sposób:

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

Importowanie twoich funkcji

Aby zaimportować swoje funkcje, użyj polecenia request, require zaimportować główny plik funkcji jako moduł. Pamiętaj, aby zrobić to dopiero po zainicjowaniu firebase-functions-test i mockowaniu wartości konfiguracyjnych.

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

Jeśli zainicjalizowałeś firebase-functions-test w trybie offline i masz admin.initializeApp() w kodzie funkcji, musisz go opóźnić przed zaimportowaniem funkcji:

// 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');

Testowanie funkcji działających w tle (nie HTTP)

Proces testowania funkcji innych niż HTTP obejmuje następujące kroki:

  1. Zawijaj funkcję, którą chcesz przetestować, za pomocą metody test.wrap
  2. Skonstruuj dane testowe
  3. Wywołaj opakowaną funkcję z utworzonymi danymi testowymi i dowolnymi polami kontekstu zdarzenia, które chcesz określić.
  4. Twórz twierdzenia dotyczące zachowania.

Najpierw zawiń funkcję, którą chcesz przetestować. Załóżmy, że masz funkcję w functions/index.js o nazwie makeUppercase , którą chcesz przetestować. Napisz następujące w functions/test/index.test.js

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

wrapped to funkcja, która po wywołaniu wywołuje makeUppercase . wrapped przyjmuje 2 parametry:

  1. data (wymagane): dane do wysłania do makeUppercase . Odpowiada to bezpośrednio pierwszemu parametrowi wysłanemu do programu obsługi funkcji, który napisałeś. firebase-functions-test udostępnia metody konstruowania niestandardowych danych lub przykładowych danych.
  2. eventContextOptions (opcjonalne): pola kontekstu zdarzenia, które chcesz określić. Kontekst zdarzenia jest drugim parametrem wysyłanym do napisanej obsługi funkcji. Jeśli nie uwzględnisz parametru eventContextOptions podczas wywoływania wrapped , kontekst zdarzenia jest nadal generowany z rozsądnymi polami. Możesz zastąpić niektóre wygenerowane pola, określając je tutaj. Pamiętaj, że musisz uwzględnić tylko pola, które chcesz zastąpić. Wszystkie pola, których nie zastąpiłeś, zostaną wygenerowane.
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
});

Konstruowanie danych testowych

Pierwszym parametrem opakowanej funkcji są dane testowe do wywołania funkcji bazowej. Istnieje wiele sposobów konstruowania danych testowych.

Korzystanie z danych niestandardowych

firebase-functions-test posiada szereg funkcji do konstruowania danych potrzebnych do testowania twoich funkcji. Na przykład użyj test.firestore.makeDocumentSnapshot , aby utworzyć DocumentSnapshot Firestore. Pierwszym argumentem są dane, a drugim pełna ścieżka referencyjna, a także opcjonalny trzeci argument dla innych właściwości migawki, które można określić.

// 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);

Jeśli testujesz funkcję onUpdate lub onWrite , musisz utworzyć dwie migawki: jedną dla stanu przed i jedną dla stanu po. Następnie możesz użyć metody makeChange , aby utworzyć obiekt Change z tymi migawkami.

// 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);

Zobacz dokumentację API dla podobnych funkcji dla wszystkich innych typów danych.

Korzystanie z przykładowych danych

Jeśli nie musisz dostosowywać danych używanych w testach, firebase-functions-test oferuje metody generowania przykładowych danych dla każdego typu funkcji.

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

Zobacz dokumentację API, aby uzyskać informacje o metodach pobierania przykładowych danych dla każdego typu funkcji.

Korzystanie z danych pośredniczących (w trybie offline)

Jeśli zainicjowano zestaw SDK w trybie offline i testujesz funkcję Cloud Firestore lub Realtime Database, użyj zwykłego obiektu z kodami pośredniczącymi zamiast tworzenia rzeczywistego DocumentSnapshot lub DataSnapshot .

Załóżmy, że piszesz test jednostkowy dla następującej funkcji:

// 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);
    });

Wewnątrz funkcji snap jest używany dwukrotnie:

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

W kodzie testowym utwórz zwykły obiekt, w którym będą działać obie te ścieżki kodu, i użyj Sinon do skrótu metod.

// 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);

Dokonywanie asercji

Po zainicjowaniu zestawu SDK, zawinięciu funkcji i skonstruowaniu danych można wywołać opakowane funkcje ze skonstruowanymi danymi i dokonać asercji dotyczących zachowania. Możesz użyć biblioteki takiej jak Chai do tworzenia tych asercji.

Dokonywanie asercji w trybie online

Jeśli zainicjowałeś pakiet Firebase Test SDK dla funkcji Cloud Functions w trybie online , możesz potwierdzić, że żądane działania (takie jak zapis bazy danych) zostały wykonane, używając pakietu firebase-admin SDK.

Poniższy przykład potwierdza, że ​​'INPUT' został zapisany w bazie danych projektu testowego.

// 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');
  });
});

Wykonywanie asercji w trybie offline

Możesz tworzyć asercje dotyczące oczekiwanej wartości zwracanej przez funkcję:

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);

Możesz również użyć szpiegów Sinon , aby potwierdzić, że niektóre metody zostały wywołane i mają parametry, których oczekujesz.

Testowanie funkcji HTTP

Aby przetestować funkcje HTTP onCall, użyj tego samego podejścia, co w przypadku testowania funkcji działających w tle .

Jeśli testujesz funkcje HTTP onRequest, powinieneś użyć firebase-functions-test , jeśli:

  • Używasz functions.config()
  • Twoja funkcja wchodzi w interakcję z projektem Firebase lub innymi interfejsami API Google i chcesz używać w testach prawdziwego projektu Firebase i jego danych logowania.

Funkcja HTTP onRequest przyjmuje dwa parametry: obiekt żądania i obiekt odpowiedzi. Oto jak możesz przetestować przykładową funkcję addMessage() :

  • Zastąp funkcję przekierowania w obiekcie odpowiedzi, ponieważ sendMessage() ją wywołuje.
  • W funkcji przekierowania użyj chai.assert , aby pomóc w ustaleniu, z jakimi parametrami funkcja przekierowania powinna być wywołana:
// 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);

Przetestuj czyszczenie

Na samym końcu kodu testowego wywołaj funkcję czyszczenia. Spowoduje to anulowanie ustawień zmiennych środowiskowych ustawionych przez zestaw SDK podczas inicjowania i usunięcie aplikacji Firebase, które mogły zostać utworzone, jeśli użyto zestawu SDK do utworzenia bazy danych czasu rzeczywistego DataSnapshot lub Firestore DocumentSnapshot .

test.cleanup();

Przejrzyj pełne przykłady i dowiedz się więcej

Możesz przejrzeć pełne przykłady w repozytorium Firebase GitHub.

Aby dowiedzieć się więcej, zapoznaj się z dokumentacją API dotyczącą firebase-functions-test .