Wprowadzenie

Dzisiaj kolejny wpis o Postmanie. W ostatnim pokazałem Ci, w jaki sposób dodawać asserty do żądań w Postmanie, aby weryfikować poprawność działania aplikacji. Na końcu zobaczyłeś, jak uruchamiać testy z wykorzystaniem wbudowanego runnera. Jest on wygodny w momencie, gdy pracujemy nad zmianami w api. Natomiast w celu systematycznej weryfikacji poprawności działania aplikacji sprawdza się średnio. Na szczęście testy można wykonywać automatycznie w ramach buildów aplikacji. Ten właśnie temat poruszę w tym artykule. Pokażę Ci, jak automatycznie wykonać testy Postmana w Azure DevOps.

Newman

Twórcy Postmana udostępniają aplikację Newman, które umożliwia wykonywanie żądań z kolekcji z poziomu wiersza poleceń. Właśnie tę aplikację wykorzystam do wykonywania testów w Azure DevOps.

Newmana najlepiej zainstalować z wykorzystaniem node.js (musisz go pobrać i zainstalować, o ile go nie masz – http://nodejs.org/download/).

Mając zainstalowanego node.js, wystarczy wykonać komendę:

npm install -g newman

aby zainstalować Newmana, który będzie dostępny w każdym folderze w systemie.

Mając już zainstalowanego Newmana, możemy wykonać testy z poziomu wiersza poleceń. Najbardziej podstawowa komenda wygląda tak:

newman run Blog.postman_collection.json

Run powoduje wykonanie wszystkich żądań z pliku kolekcji przekazanej jako parametr (w tym przypadku Blog.postman_collection.json). Po uruchomieniu powyższej kolekcji zostaną wykonane wszystkie żądania z kolekcji.

W przypadku, gdy w kolekcji wykorzystywaliśmy zmienne środowiskowe, należy w pierwszej kolejności wyeksportować środowisko do pliku json. W widoku zarządzania środowiskami klikamy w przycisk Download Enviroment:

Mając już plik z środowiskiem, możemy użyć przełącznika -e, w którym przekazujemy ścieżkę do zapisanego pliku. W efekcie komentarz wygląda tak:

newman run Blog.postman_collection.json -e Blog.Dev.postman_environment.json

Po wykonaniu powyższej komendy w konsoli zobaczymy mniej więcej coś takiego (jest to końcowy fragment tego, co wyświetlił Newman):

W pierwszej kolejności Newman wyświetla informacje o wykonanych żądaniach, następnie na końcu podsumowanie, a w przypadku gdy jakieś asserty wykonały się z błędem, również o tym się dowiemy w podsumowaniu.

Newman ma też kilka innych przydatnych przełączników, które wykorzystamy później w Azure DevOps:

• –folder [nazwa] – wykonuje tylko testy z określonego folderu w kolekcji, np. –folder Automatic
• -r [nazwa] – wynik wykonanych żądań i testów jest zapisany w formacie przekazanym w wartości przełącznika (np. -r junit). Azure DevOps wspiera różne formaty, dzięki czemu później zobaczymy ładną stronę z podsumowaniem wykonanych testów.

Przełączników jest więcej, najlepiej przejrzeć je na dedykowanej stronie Newmana – https://learning.getpostman.com/docs/postman/collection_runs/command_line_integration_with_newman/.

Postman i Azure DevOps

Na potrzeby wpisu przygotowałem prosty projekt w Azure DevOps, który w praktyce pokazuje, w jaki sposób można wykonać automatycznie testy Postmana. Projekt korzysta z repozytorium na githubie – https://github.com/danielplawgo/WebApiTests. Testowa aplikacja jest wrzucana na Azure App Service, na której następnie zostaną wykonane testy.

Jak wspomniałem w poprzednim wpisie, na potrzeby automatycznych testów w Postmanie tworzę dedykowane środowisko, z którego korzystam tylko do wykonywania testów Postmana.

Definicja builda w Azure DevOps nie ma nic specyficznego dla Postmana poza jedną drobną rzeczą – skopiowaniem folderu z testami, aby później były one dostępne podczas wykonywania wdrożenia aplikacji. Testy będziemy wykonywali po wdrożeniu nowej wersji aplikacji z mastera na to dedykowane środowisko testowe.

Wspomniany dodatkowy krok wygląda mniej więcej tak:

Korzystamy z taska PublishPipelineArtifact@1, który publikuje zawartość folderu Tests z głównego folderu w repozytorium. W folderze tym znajdują się wyeksportowana kolekcja z testami oraz wyeksportowane środowisko.

Cała zawartość azure-pipelines.yml użyta w przykładzie znajduje się na githubie – https://github.com/danielplawgo/WebApiTests/blob/master/azure-pipelines.yml.

Ważniejsze rzeczy dzieją się w definicji release.

Release

Definicja release użyta w przykładzie wygląda tak:

Składa się ona z czterech kroków. Pierwszym jest wdrożenie zbudowanej wcześniej aplikacji na Azure App Service. W tym miejscu prawdopodobnie będziesz miał inną liczbę zadań, specyficzną dla twojego projektu.

Kolejne trzy kroki są już specyficzne dla naszych testów:

• instalacja Newmana z wykorzystaniem node.js
• wykonanie testów przy użyciu Newmana
• publikacja wyników testów, aby później były one widoczne w dashboard w Azure DevOps.

Przejdę teraz przez konfigurację poszczególnych kroków (pominę pierwszy – wdrożenie aplikacji – ponieważ nie jest on tematem tego wpisu).

Instalacja Newmana

Na początku musimy zainstalować Newmana, aby można było go później wykorzystać. W tym celu dodajemy zadanie npm do release, a następnie konfigurujemy je w następujący sposób:

W Display name wpisujemy nazwę naszego zadania (punkt 1 na zrzucie); może to być dowolna nazwa. Natomiast w polu Command (punkt 2) wybieramy opcję custom. Na końcu w polu Command and arguments (punkt 3) wpisujemy „install newman -g”. Najlepiej zainstalować Newmana globalnie, aby później nie było problemów z wykonywaniem testów z jakiegoś podfolderu.

Uruchomienie Newmana

Ten krok możemy zrealizować na dwa sposoby: wywołać ręcznie Newmana z wiersza poleceń (task Command Line) lub skorzystać z dedykowanego zadania, które najpierw trzeba zainstalować – https://marketplace.visualstudio.com/items?itemName=carlowahlstedt.NewmanPostman. Co prawda zadanie jest nie oficjalnym zadaniem od twórców Postmana, ale robi swoją robotę. Aby zainstalować task, należy skorzystać z przycisku „Get it free” i postąpić zgodnie z wytycznymi na kolejnych stronach.

Przed przystąpieniem do konfiguracji zadania należy w Postmanie przygotować drugie środowisko, w którym adres aplikacji wskazuje na tę naszą testową aplikację w Azure App Service. W moim przypadku jest to środowisko Postman Azure Tests widoczne na pierwszym zrzucie ekranu. Eksportujemy to środowisko i wrzucamy do repozytorium.

Sama konfiguracja zadania wygląda tak (musiałem to rozbić na dwa niezależne zrzuty ekranu):

W zadaniu ustawiamy wartości dla kilku pól:

• Display Name (punkt 1) – nazwa wyświetla – wartość dowolna
• Collection File Source (punkt 2) – wybieramy folder, w którym znajdują się testy – to jest ten folder, który dodatkowo publikowaliśmy w definicji builda
• Contents (punkt 3) – wyrażenia do wyszukiwania plików kolekcji z folderu wybranego w wcześniejszym polu – warto zweryfikować, czy wartość domyślna pozwoli na znalezienie naszego pliku kolekcji – wartość: „**/*collection.json”
• Folder (punkt 4) – folder w kolekcji do uruchomienia – jest to wartość przełączniku –folder opisywanym wcześniej
• Enviroment File (punkt 5) – wybieramy wyeksportowany plik środowiska
• Reporters (punkt 6) – wybieramy format raportu, w jakim ma zostać zapisany wynik testów – Azure DevOps ma wsparcie dla JUnit, więc można wybrać tę wartość.

Po konfiguracji tych wszystkich pól w efekcie uzyskamy mniej więcej taką komendę:

run Blog.postman_collection.json -e PostmanAzureTests.postman_environment.json --folder "Automatic" -x -r junit

Oczywiście w razie potrzeby możemy również skonfigurować inne dostępne pola. Ja już nie będę się skupiał na pozostałych możliwych opcjach.

Publikacja wyników testów

Ostatnim krokiem jest opublikowanie wyników działania Newmana. Dzięki temu będziemy mogli później przeglądać je z poziomu Azure DevOps.

Konfiguracja tego zadania jest dość prosta i wygląda tak:

Konfigurujemy trzy pola:

• Display Name (punkt 1) – nazwa wyświetlana
• Test result format (punkt 2) – jest to właśnie ten sam format, który wybraliśmy we wcześniejszym kroku – w naszym przypadku JUnit
• Test results files (punkt 3) – wyrażenie, które zostanie użyte do przeszukania plików z wynikami – w przypadku naszej konfiguracji zadania Newmana możemy użyć wyrażenia „**/newman-*.xml”

Po skonfigurowaniu tego zadania wszystko powinno już ładnie działać.

Wykonywanie buildów oraz release’ów możemy ustawić w zależności od własnych preferencji. U mnie na ogół testy Postmana automatycznie się wykonują (build oraz release) po merge’u do mastera (zatwierdzeniu pull requesta i wciągnięciu zmian). Dodatkowo ręcznie uruchamiany jest test w Azure DevOps na wybranym branchu.

W efekcie wykonania release’a opisanego powyżej otrzymujemy ładną informację o testach i ich wynikach z poziomu Azure DevOps:

Przykład

Do pracy nad tym wpisem użyłem przykładu z wpisu poprzedniego – https://github.com/danielplawgo/WebApiTests. Dalej możesz użyć tego kodu do własnych testów, ale będziesz musiał go przerzucić do swojego repozytorium, a następnie do folderu Tests dodać własne wyeksportowane środowisko, w którym będzie zapisany adres do testowej aplikacji w Azure App Service.

W tym momencie aplikacja dalej nie korzysta z bazy, dlatego zabawa z wykonywaniem testów Postmana w Azure DevOps jest łatwiejsza.

Podsumowanie

Automatyczne testy Api zwiększają szansę, że nasza aplikacja będzie działała poprawnie. Do tego automatyczne ich wykonywanie podczas procesu budowania oraz wdrażania powoduje, że dużo szybciej wyłapiemy błędy (w szczególności błędy regresji), które pojawią w trakcie pracy nad nią. Oczywiście wszystko zależy od liczby oraz jakości testów, które mamy w aplikacji.

W kolejnym wpisie zostaniemy jeszcze w tym temacie. Zastanowimy się, w jaki sposób możemy obsłużyć reset danych w testowej aplikacji, aby testy były powtarzalne.