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 SDK dla Cloud Functions. Jest dystrybuowany na npm jako firebase-functions-test i jest towarzyszącym testowym zestawem SDK do firebase-functions . Testowy pakiet SDK Firebase dla funkcji w chmurze:

  • Dba o odpowiednią konfigurację i demontaż testów, na przykład ustawianie i rozbrajanie zmiennych środowiskowych wymaganych przez firebase-functions .
  • Generuje przykładowe dane i kontekst zdarzenia, dzięki czemu wystarczy określić tylko pola istotne dla testu.

Konfiguracja testowa

Zainstaluj zarówno firebase-functions-test jak i Mocha , środowisko testowe, 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 z kodem testowym i nazwij go na przykład index.test.js .

Na koniec zmodyfikuj functions/package.json i dodaj 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 zestawu SDK testowego Firebase dla funkcji w chmurze

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

  1. Tryb online (zalecany): pisz testy, które wchodzą w interakcję z projektem Firebase przeznaczonym do testowania, tak aby zapisywanie w bazie danych, tworzenie przez użytkownika itp. faktycznie miało miejsce, a kod testowy mógł sprawdzić wyniki. Oznacza to również, że inne zestawy SDK Google używane w Twoich funkcjach również będą działać.
  2. Tryb offline: pisz testy jednostkowe w trybie offline i w trybie offline bez skutków ubocznych. Oznacza to, że wszelkie wywołania metod, które wchodzą w interakcję z produktem Firebase (np. zapisywanie do bazy danych lub tworzenie użytkownika) muszą zostać zakończone. Korzystanie z trybu offline nie jest generalnie zalecane, jeśli masz funkcje Cloud Firestore lub Realtime Database, ponieważ znacznie zwiększa to złożoność kodu testowego.

Zainicjuj pakiet SDK w trybie online (zalecane)

Jeśli chcesz napisać testy współpracujące z projektem testowym, musisz podać wartości konfiguracyjne projektu, które są potrzebne do inicjowania aplikacji za pośrednictwem firebase-admin oraz ścieżkę do pliku klucza konta usługi.

Aby uzyskać wartości konfiguracyjne projektu Firebase:

  1. Otwórz ustawienia projektu w konsoli Firebase .
  2. W obszarze 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 konsoli Google Cloud.
  2. Wybierz domyślne konto usługi App Engine i użyj menu opcji po prawej stronie, aby wybrać opcję Utwórz klucz .
  3. Po wyświetleniu monitu wybierz typ klucza JSON i kliknij opcję 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 pakiet 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')();

Wyśmiewanie wartości konfiguracyjnych

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

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

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

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

Importowanie funkcji

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

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

Jeśli zainicjowałeś firebase-functions-test w trybie offline i masz admin.initializeApp() w kodzie funkcji, musisz ją odkodować 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 w tle (innych niż HTTP).

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

  1. Zawiń funkcję, którą chcesz przetestować, za pomocą metody test.wrap
  2. Konstruuj dane testowe
  3. Wywołaj opakowaną funkcję ze skonstruowanymi danymi testowymi i dowolnymi polami kontekstu zdarzenia, które chcesz określić.
  4. Twórz twierdzenia na temat zachowania.

Najpierw zawiń funkcję, którą chcesz przetestować. Załóżmy, że masz funkcję w functions/index.js o nazwie makeUppercase , którą chcesz przetestować. Wpisz następujące polecenie 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. dane (wymagane): dane do wysłania do makeUppercase . Odpowiada to bezpośrednio pierwszemu parametrowi wysłanemu do procedury obsługi funkcji, którą napisałeś. firebase-functions-test zapewnia metody konstruowania danych niestandardowych lub przykładowych.
  2. eventContextOptions (opcjonalnie): pola kontekstu zdarzenia, które chcesz określić. Kontekst zdarzenia to drugi parametr wysyłany do napisanej procedury obsługi funkcji. Jeśli nie uwzględnisz parametru eventContextOptions podczas wywoływania wrapped , kontekst zdarzenia będzie 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 te pola, które chcesz zastąpić. Zostaną wygenerowane wszystkie pola, których nie zastąpiłeś.
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, za pomocą których można wywołać funkcję bazową. Istnieje wiele sposobów konstruowania danych testowych.

Korzystanie z niestandardowych danych

firebase-functions-test ma wiele funkcji do konstruowania danych potrzebnych do testowania funkcji. Na przykład użyj test.firestore.makeDocumentSnapshot , aby utworzyć Firestore DocumentSnapshot . Pierwszym argumentem są dane, drugim argumentem jest pełna ścieżka referencyjna, a opcjonalny trzeci argument określa inne 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 , aby zapoznać się z podobnymi funkcjami dla wszystkich pozostałych typów danych.

Korzystając 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 poznać metody pobierania przykładowych danych dla każdego typu funkcji.

Korzystanie z danych pośrednich (w trybie offline)

Jeśli zainicjowałeś pakiet SDK w trybie offline i testujesz funkcję Cloud Firestore lub Realtime Database, powinieneś użyć zwykłego obiektu z wycinkami zamiast tworzyć rzeczywisty 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 ścieżki kodu, i użyj Sinona , aby zablokować metody.

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

Składanie twierdzeń

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. Do formułowania tych twierdzeń możesz używać biblioteki takiej jak Chai .

Dokonywanie asercji w trybie online

Jeśli zainicjowałeś zestaw SDK testowy Firebase dla funkcji w chmurze w trybie online , możesz sprawdzić, czy żądane działania (takie jak zapis w bazie danych) zostały wykonane, korzystając z zestawu SDK firebase-admin .

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

Dokonywanie asercji w trybie offline

Możesz dokonać twierdzeń na temat 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 także użyć szpiegów Sinon , aby potwierdzić, że zostały wywołane określone metody i z oczekiwanymi parametrami.

Testowanie funkcji HTTP

Aby przetestować funkcje HTTP onCall, użyj tego samego podejścia, co przy testowaniu 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 współdziała z projektem Firebase lub innymi interfejsami API Google i chcesz używać prawdziwego projektu Firebase i jego danych uwierzytelniających do swoich testów.

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 formułowaniu asercji na temat parametrów, z którymi funkcja przekierowania powinna zostać 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);

Testowe czyszczenie

Na samym końcu kodu testowego wywołaj funkcję czyszczenia. Spowoduje to rozłączenie zmiennych środowiskowych ustawionych przez zestaw SDK podczas jego inicjalizacji i usunięcie aplikacji Firebase, które mogły zostać utworzone w przypadku użycia zestawu SDK do utworzenia bazy danych czasu rzeczywistego DataSnapshot lub Firestore DocumentSnapshot .

test.cleanup();

Przejrzyj kompletne 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 .