Postman API testen in CI

Integreer Newman in 6 simpele stappen in Jenkins, inclusief JUnit testrapport

Voor het testen en monitoren van web API’s is Postman een populaire tool. De community versie is gratis en bovendien behoorlijk compleet. Ook de Pro versie is best betaalbaar, zeker in vergelijking met bijv. SOAP-UI.

In deze blog wordt beschreven hoe je jouw Postman collectie laat draaien vanuit Jenkins en hoe je hierbij een praktisch JUnit test report krijgt.

Als je reeds een collectie van web requests hebt opgebouwd in Postman, dan kun je deze op een aantal manieren benutten:

• Via de Postman GUI (Chrome extensie of native Windows / Mac applicatie)

• Via de Postman Runner module in de applicatie

• Via Newman, de Command-Line Interface

Methode 1 is volledig handmatig. Dat betekent dat je iedere request handmatig dient te verzenden om de betreffende response te kunnen testen. Hoewel dat prima volstaat om een specifieke request te verifiëren is het behoorlijk omslachtig wanneer je een complete set aan requests na wilt lopen, bijvoorbeeld voor een regressietest van je API. Methode 2 is wel geschikt om een complete collectie te draaien, maar vereist wel dat je handmatig een configuratie instelt in de GUI. Wil je je Postman collectie maximaal automatiseren? Ga dan voor methode 3. Je roept de collectie dan aan middels Newman: de command-line interface van Postman. Newman biedt bovendien de mogelijkheid om je collectie volledig geautomatiseerd te draaien, bijvoorbeeld door het in Jenkins te integreren.

1. Installeer de NodeJS plug-in in Jenkins

Newman is een NodeJS applicatie. Daarom is het zaak om NodeJS te kunnen gebruiken vanuit Jenkins. Om NodeJS te installeren ga je naar:

Jenkins > Manage Jenkins > Manage Plugins

Kijk bij de ‘Installed’ tab of je de NodeJS plug-in ziet. Zo niet, selecteer hem dan in de ‘Available’ tab en klik op ‘Install without restart’.

2. Configureer NodeJS met Newman

Nu Jenkins kan beschikken over NodeJS, gaan we een nieuwe NodeJS installatie aanmaken en de npm packages definiëren die geïnstalleerd dienen te worden. Ga daarvoor naar:

Jenkins > Manage Jenkins > Global Tool Configuration

1. Selecteer daar ‘NodeJS installations’

2. Geef een naam voor de installatie en kies een recente versie van NodeJS

3. Bij ‘global npm packages to install’ geven we alleen ‘newman’ op

4. Klik nu op ‘Save’

3. Maak een nieuw Jenkins project aan

Nu kunnen we in Jenkins een project aanmaken. Ga daarvoor naar:

Jenkins > New Item

Geef het project een naam, selecteer template ‘Freestyle project’ en klik OK.

We gaan hierna 3 stappen toevoegen in dit project: 2 bouwstappen en 1 post-build stap voor het testrapport.

4. Maak een bouwstap aan voor NodeJS

Scroll naar de ‘Build’ sectie en klik op ‘Add build step’. Kies vervolgens ‘Execute NodeJS script’ en selecteer de installatie die je onder stap 2 hebt aangemaakt.

5. Maak een tweede bouwstap aan voor Newman

In deze bouwstap zorgen we ervoor dat Newman je collectie requests (en eventuele tests) uit gaat voeren. Daarvoor moet Newman wel kunnen beschikken over je Postman collectie. Een simpele manier daarvoor is de optie ‘Share collection’ in de Postman applicatie.

Ga naar je Postman collectie en selecteer ‘Share Collection’.

Selecteer de ‘Get Link’ tab en kopieer de link naar je klembord.

Terug in Jenkins, kies nogmaals ‘Add build step’ en selecteer ditmaal ‘Execute Shell’. Hierin plaatsen we het Newman commando:

1. Om de collectie te draaien: newman run <Collection share link van klembord>

2. CLI & JUnit rapporten genereren: --reporters cli,junit

3. Om het JUnit rapport op te slaan: --reporter-junit-export <"newman/report.xml">

Het complete commando wordt dan als volgt:

newman run https://www.getpostman.com/collections/12a34b56c78d90 -r cli,junit
--reporter-junit-export "newman/SmoothieFlavorsTestReport.xml"  

Het JUnit rapport werkt uiteraard alleen als je collectie ook testen bevat. Anders kun je deze commando’s achterwege laten.

6. Publiceer het JUnit testrapport

Het XML-rapport van JUnit is inmiddels aangemaakt, maar voor een leesbare weergave moet het nog gepubliceerd worden binnen Jenkins. Maak een nieuwe ‘Post-build Action’ aan en kies voor ‘Publish JUnit test result report’. De locatie waar de XML-rapporten staan is: “newman/*.xml”. Druk tenslotte op Save om je Jenkins project op te slaan!

Eventuele vervolgstappen

Je bestaande Postman collectie draait nu in Jenkins! Als je een nieuwe bouwpoging start, dan wordt je collectie doorlopen en de resultaten worden door JUnit verwerkt. De bouwpoging slaagt wanneer er geen fouten optreden en faalt indien één van de testen faalt.

Natuurlijk zijn er nog wat mogelijke vervolgstappen om je Postman collectie nog waardevoller te maken voor jou en je project:

1. Maak in Jenkins een Post-build stap aan om het project op de hoogte te houden. Dat kan bijvoorbeeld door middel van een e-mail of Slack-bericht met daarin een korte samenvatting van de resultaten.

2. Voeg een build trigger toe om het je collectie op een vast interval of na een specifiek event te starten.

3. Schakel versiebeheer in (Postman Pro licentie vereist) zodat je gemakkelijker kunt samenwerken en je collectie up-to-date houdt. De gedeelde collectie die we als voorbeeld gebruiken is namelijk statisch, en moet dus met de hand geüpdatet worden na iedere aanpassing.

Leuk dat je dit blog hebt gelezen. Ik ben nieuwsgierig naar jouw ervaringen. Heb je nog tips? Of heb je vragen of opmerkingen? We horen het graag!