Web-API's testen met Postman Collections

1. Inleiding

Om een ​​web-API grondig te testen, hebben we een soort webclient nodig om toegang te krijgen tot de eindpunten van de API. Postman is een zelfstandige tool die web-API's gebruikt door HTTP-verzoeken van buiten de service te doen.

Als u Postman gebruikt, hoeven we geen HTTP-clientinfrastructuurcode te schrijven alleen om te testen. In plaats daarvan maken we testsuites, verzamelingen genaamd, en laten we Postman communiceren met onze API.

In deze zelfstudie zullen we zien hoe u een Postman-collectie maakt die een REST API kan testen.

2. Installatie

Voordat we aan de slag gaan met onze collectie, moeten we de omgeving instellen.

2.1. Postman installeren

Postman is beschikbaar voor Linux, Mac en Windows. De tool kan worden gedownload en geïnstalleerd vanaf de Postman-website.

Na het sluiten van het startscherm kunnen we de gebruikersinterface zien:

2.2. De server uitvoeren

Postman heeft een live HTTP-server nodig om zijn verzoeken te verwerken. Voor deze tutorial gebruiken we een eerder Baeldung-project, veerlaarssteun, die beschikbaar is op GitHub.

Zoals we uit de titel kunnen raden, spring-boot-rest is een Spring Boot-applicatie. We bouwen de app met het doel van Maven installeren. Eenmaal gebouwd, lanceren we de server met het aangepaste Maven-doel spring-boot: rennen.

Om te controleren of de server actief is, kunnen we deze URL in onze browser gebruiken:

// localhost: 8082 / spring-boot-rest / auth / foos

Deze service maakt gebruik van een in-memory database. Alle records worden gewist wanneer de server wordt gestopt.

3. Een postbode-collectie aanmaken

Een verzameling in Postman is een reeks HTTP-verzoeken. Postman slaat elk aspect van de verzoeken op, inclusief kopteksten en berichttekst. Daarom we kunnen de verzoeken op volgorde uitvoeren als semi-automatische tests.

Laten we beginnen met het maken van een nieuwe collectie. We kunnen op de vervolgkeuzepijl op het Nieuw en selecteer Verzameling:

Wanneer de MAAK EEN NIEUWE COLLECTIE AAN dialoogvenster verschijnt, kunnen we onze collectie een naam geven "foo API-test“. Ten slotte klikken we op het Creëer knop om onze nieuwe collectie te zien verschijnen in de lijst aan de linkerkant:

Zodra onze verzameling is gemaakt, kunnen we de cursor erover bewegen om twee menuknoppen weer te geven. De pijlknop opent een pull-right paneel dat toegang geeft tot het Collectie Runner. Omgekeerd opent de ellipsknop een vervolgkeuzemenu met een aantal bewerkingen op de verzameling.

4. Een POST-verzoek toevoegen

4.1. Een nieuw verzoek aanmaken

Nu we een lege verzameling hebben, kunnen we een verzoek toevoegen dat onze API raakt. Laten we in het bijzonder een POST-bericht naar de URI sturen / auth / foos. Om dat te doen, we openen het ellipsmenu in onze collectie en selecteren Verzoek toevoegen.

Wanneer de VERZOEK OPSLAAN dialoogvenster verschijnt, laten we een beschrijvende naam opgeven, zoals 'Voeg een ... toe foo ”. Klik vervolgens op de knop Opslaan in foo API-test.

Zodra de aanvraag is aangemaakt, kunnen we zien dat onze collectie aangeeft een verzoek. Als onze collectie echter niet is uitgebreid, kunnen we het verzoek nog niet zien. In dat geval kunnen we op de collectie klikken om deze uit te vouwen.

Nu zouden we het nieuwe verzoek onder onze verzameling moeten zien. We kunnen zien dat het nieuwe verzoek standaard een HTTP GET is, wat niet is wat we willen. We lossen dat op in de volgende sectie:

4.2. Het verzoek bewerken

Om het verzoek te bewerken, laten we erop klikken en het aldus in het tabblad verzoekeditor laden:

Hoewel de verzoekeditor talloze opties heeft, hebben we er voorlopig maar een paar nodig.

Laten we eerst de vervolgkeuzelijst gebruiken om de methode te wijzigen van GET naar POST.

Ten tweede hebben we een URL nodig. Rechts van de vervolgkeuzelijst voor de methode staat een tekstvak voor de verzoek-URL. Dus laten we dat nu invoeren:

// localhost: 8082 / spring-boot-rest / auth / foos

De laatste stap is om een ​​berichttekst op te geven. Onder het URL-adres staat een rij tabkoppen. We klikken op het Lichaam tab header om naar de body editor te gaan.

In de Lichaam tabblad, net boven het tekstgebied, is er een rij keuzerondjes en een vervolgkeuzelijst. Deze bepalen de opmaak en het inhoudstype van het verzoek.

Onze service accepteert JSON-gegevens, dus we selecteren de rauw Radio knop. In de vervolgkeuzelijst aan de rechterkant passen we de JSON (applicatie / json) inhoudstype.

Nadat de codering en het inhoudstype zijn ingesteld, voegen we onze JSON-inhoud toe aan het tekstgebied:

{"name": "Transformers"}

Laten we er ten slotte voor zorgen dat we onze wijzigingen opslaan door op te drukken Ctrl-S of het raken van de Sparen knop. De Sparen knop bevindt zich rechts van de Sturen knop. Zodra we opslaan, kunnen we zien dat het verzoek is bijgewerkt naar POST in de lijst aan de linkerkant:

5. Het verzoek uitvoeren

5.1. Een enkel verzoek uitvoeren

Om een ​​enkel verzoek uit te voeren, klikken we gewoon op het Sturen knop rechts van het URL-adres. Zodra we klikken Sturen, het antwoordpaneel wordt geopend onder het verzoekvenster. Het kan nodig zijn om naar beneden te scrollen om het te zien:

Laten we onze resultaten eens bekijken. Concreet zien we in de koptekstbalk dat ons verzoek is geslaagd met de status 201 Gemaakt. Bovendien laat het antwoordorgaan zien dat onze Transformatoren record ontving een ID van 1.

5.2. De Collection Runner gebruiken

In tegenstelling tot Sturen knop kan de collectieloper een hele collectie uitvoeren. Om de collectieloper te starten, bewegen we de cursor over onze foo API-test verzameling en klik op de pijl naar rechts. In het pull-right paneel zien we een Rennen knop, dus laten we erop klikken:

Als we op het Rennen knop de collectieloper opent in een nieuw venster. Omdat we het uit onze collectie hebben gelanceerd, is de loper al geïnitialiseerd in onze collectie:

De collectieloper biedt opties die van invloed zijn op het proefdraaien, maar die hebben we voor deze oefening niet nodig. Laten we direct naar het Voer foo API-test uit knop onderaan en klik erop.

Wanneer we de verzameling uitvoeren, verandert de weergave in Resultaten uitvoeren. In deze weergave, we zien een lijst met tests die groen zijn gemarkeerd voor succes en rood voor mislukking.

Hoewel ons verzoek is verzonden, geeft de deelnemer aan dat de nultests zijn geslaagd en de nultests zijn mislukt. Dit komt omdat we nog geen tests aan ons verzoek hebben toegevoegd:

6. Testen van de respons

6.1. Tests toevoegen aan een aanvraag

Om een ​​test te maken, gaan we terug naar het verzoekbewerkingspaneel waar we onze POST-methode hebben gebouwd. We klikken op de Tests tabblad dat zich onder de URL bevindt. Als we dat doen, verschijnt het deelvenster Tests:

In het deelvenster Tests schrijven we JavaScript dat wordt uitgevoerd wanneer het antwoord van de server wordt ontvangen.

Postman biedt ingebouwde variabelen die toegang geven tot het verzoek en antwoord. Bovendien kunnen een aantal JavaScript-bibliotheken worden geïmporteerd met behulp van de vereisen() syntaxis.

Er zijn veel te veel scriptfuncties om in deze tutorial te behandelen. De officiële Postman-documentatie is echter een uitstekende bron over dit onderwerp.

Laten we doorgaan met het toevoegen van drie tests aan ons verzoek:

pm.test ("successtatus", () => pm.response.to.be.success); pm.test ("naam is correct", () => pm.expect (pm.response.json (). naam) .to.equal ("Transformers")); pm.test ("id is toegewezen", () => pm.expect (pm.response.json (). id) .to.be.not.null);

Zoals we kunnen zien, deze tests maken gebruik van de global p.m module geleverd door Postman. Met name de tests gebruiken pm.test (), pm.expect (), en pm.response.

De pm.test () functie accepteert een label en een assertiefunctie, zoals verwachten(). We gebruiken pm.expect () om voorwaarden te doen gelden voor de inhoud van de antwoord-JSON.

De pm.response object biedt toegang tot verschillende eigenschappen en bewerkingen op het antwoord dat wordt geretourneerd door de server. Beschikbare eigenschappen zijn onder meer de responsstatus en JSON-inhoud.

Zoals altijd slaan we onze wijzigingen op met Ctrl-S of de Sparen knop.

6.2. De tests uitvoeren

Nu we onze tests hebben, laten we het verzoek opnieuw uitvoeren. Druk op de Sturen knop geeft de resultaten weer in de Test resultaten tabblad van het antwoordpaneel:

Op dezelfde manier toont de verzamelloper nu onze testresultaten. In het bijzonder toont de samenvatting linksboven de bijgewerkte geslaagd en mislukt totalen. Onder de samenvatting is een lijst met elke test met zijn status:

6.3. De Postman-console bekijken

De Postman Console is een handig hulpmiddel voor het maken en debuggen van scripts. We kunnen de console vinden onder het Visie menu met de itemnaam Toon Postman Console. Bij het opstarten wordt de console geopend in een nieuw venster.

Terwijl de console open is, worden alle HTTP-verzoeken en reacties geregistreerd. Bovendien, wanneer scripts gebruiken console.log (), de Postman Console geeft die berichten weer:

7. Een reeks verzoeken aanmaken

Tot nu toe hebben we ons gefocust op één HTTP-verzoek. Laten we nu eens kijken wat we kunnen doen met meerdere verzoeken. Door een reeks verzoeken aan elkaar te koppelen, kunnen we een client-server-workflow simuleren en testen.

Laten we in dit gedeelte toepassen wat we hebben geleerd om een ​​reeks verzoeken te maken. Concreet voegen we nog drie verzoeken toe om uit te voeren na het POST-verzoek dat we al hebben gemaakt. Dit zullen een GET, een DELETE en tot slot nog een GET zijn.

7.1. Antwoordwaarden vastleggen in variabelen

Voordat we onze nieuwe verzoeken maken, moeten we een wijziging aanbrengen in ons bestaande POST-verzoek. Omdat we niet weten welke ID de server elk zal toewijzen foo we kunnen bijvoorbeeld een variabele gebruiken om de id vast te leggen die door de server wordt geretourneerd.

Om die id vast te leggen, voegen we nog een regel toe aan het einde van het testscript van het POST-verzoek:

pm.variables.set ("id", pm.response.json (). id);

De pm.variables.set () functie neemt een waarde en wijst deze toe aan een tijdelijke variabele. In dit geval maken we een ID kaart variabele om de id-waarde van ons object op te slaan. Eenmaal ingesteld, hebben we toegang tot deze variabele in latere verzoeken.

7.2. Een GET-verzoek toevoegen

Laten we nu, met behulp van de technieken uit vorige secties, een GET-verzoek toevoegen na het POST-verzoek.

Met dit GET-verzoek halen we hetzelfde op foo instantie die het POST-verzoek heeft gemaakt. Laten we dit GET-verzoek een naam geven als 'krijg een foo“.

De URL van het GET-verzoek is:

// localhost: 8082 / spring-boot-rest / auth / foos / {{id}}

In deze URL verwijzen we naar de ID kaart variabele die we eerder hebben ingesteld tijdens het POST-verzoek. Het GET-verzoek moet dus dezelfde instantie ophalen die is gemaakt door de POST.

Wanneer variabelen buiten scripts verschijnen, wordt er naar verwezen met behulp van de syntaxis met dubbele accolades {{ID kaart}}.

Aangezien er geen hoofdtekst is voor een GET-verzoek, gaan we rechtstreeks naar het Tests tabblad. Omdat de tests vergelijkbaar zijn, kunnen we de tests van het POST-verzoek kopiëren en vervolgens een paar wijzigingen aanbrengen.

Ten eerste, we hoeven de ID kaart weer variabel, dus laten we die regel niet kopiëren.

Ten tweede weten we welke id we deze keer kunnen verwachten, dus laten we die id verifiëren. We kunnen de ID kaart variabele om dat te doen:

pm.test ("successtatus", () => pm.response.to.be.success); pm.test ("naam is correct", () => pm.expect (pm.response.json (). naam) .to.equal ("Transformers")); pm.test ("id is correct", () => pm.expect (pm.response.json (). id) .to.equal (pm.variables.get ("id"))));

Omdat de syntaxis met dubbele accolades geen geldige JavaScript is, gebruiken we de pm.variables.get () functie om toegang te krijgen tot het ID kaart variabele.

Laten we tot slot de wijzigingen opslaan zoals we eerder hebben gedaan.

7.3. Een DELETE-verzoek toevoegen

Vervolgens voegen we een DELETE-verzoek toe waarmee het foo object van de server.

We gaan verder door een nieuw verzoek toe te voegen na de GET en de methode in te stellen op DELETE. We kunnen dit verzoek 'verwijder een foo“.

De URL van de verwijdering is identiek aan de GET-URL:

// localhost: 8082 / spring-boot-rest / auth / foos / {{id}}

Het antwoord heeft geen lichaam om te testen, maar we kunnen de antwoordcode testen. Daarom heeft het DELETE-verzoek slechts één test:

pm.test ("successtatus", () => pm.response.to.be.success);

7.4. Verifiëren van het DELETE

Laten we tot slot nog een kopie van het GET-verzoek toevoegen om te verifiëren dat de DELETE echt werkte. Laten we deze keer ons eerste GET-verzoek dupliceren in plaats van een geheel nieuw verzoek te maken.

Om een ​​verzoek te dupliceren, klikken we met de rechtermuisknop op het verzoek om het vervolgkeuzemenu weer te geven. Vervolgens selecteren we Duplicaat.

Het dubbele verzoek heeft het woord Kopiëren toegevoegd aan zijn naam. Laten we het hernoemen naar 'verifieer verwijderen" om verwarring te voorkomen. De Hernoemen optie is beschikbaar door met de rechtermuisknop op het verzoek te klikken.

Standaard verschijnt het dubbele verzoek onmiddellijk na het oorspronkelijke verzoek. Daarom moeten we het onder het DELETE-verzoek slepen.

De laatste stap is het aanpassen van de tests. Maar voordat we dat doen, laten we van de gelegenheid gebruik maken om een ​​mislukte test te zien.

We hebben het GET-verzoek gekopieerd en verplaatst na de DELETE, maar we hebben de tests nog niet bijgewerkt. Omdat het DELETE-verzoek het object had moeten verwijderen, zouden de tests moeten mislukken.

Laten we ervoor zorgen dat al onze verzoeken worden opgeslagen en vervolgens op klikken Probeer het opnieuw in de collectie runner. Zoals verwacht zijn onze tests mislukt:

Nu onze korte omweg is voltooid, gaan we de tests oplossen.

Door de mislukte tests te bekijken, kunnen we zien dat de server reageert met een 500-status. Daarom zullen we de status in onze test wijzigen.

Bovendien kunt u door de mislukte reactie in het Postman Console, leren we dat het antwoord een oorzaak eigendom. Bovendien is de oorzaak eigenschap bevat de tekenreeks “Geen waarde aanwezig“. We kunnen dat ook testen:

pm.test ("status is 500", () => pm.response.to.have.status (500)); pm.test ("geen waarde aanwezig", () => pm.expect (pm.response.json (). oorzaak) .to.equal ("Geen waarde aanwezig"));

7.5. De volledige collectie uitvoeren

Nu we alle verzoeken hebben toegevoegd, laten we de volledige verzameling uitvoeren in de verzamelingsrunner:

Als alles volgens plan is verlopen, zouden we negen succesvolle tests moeten hebben.

8. De collectie exporteren en importeren

Hoewel Postman onze collecties op een privé, lokale locatie opslaat, willen we de collectie misschien delen. Om dat te doen, exporteren we de collectie naar een JSON-bestand.

De Exporteren commando is beschikbaar in het ellipsmenu van de collectie. Wanneer we om een ​​JSON-bestandsversie worden gevraagd, kiezen we de nieuwste aanbevolen versie.

Nadat we de bestandsversie hebben geselecteerd, vraagt ​​Postman om een ​​bestandsnaam en locatie voor de geëxporteerde collectie. We kunnen bijvoorbeeld een map kiezen binnen ons GitHub-project.

Om een ​​eerder geëxporteerde collectie te importeren, gebruiken we de Importeren knop. We kunnen het vinden in de werkbalk van het hoofdvenster van Postman. Wanneer Postman om een ​​bestandslocatie vraagt, kunnen we navigeren naar het JSON-bestand dat we willen importeren.

Het is vermeldenswaard dat Postman geëxporteerde bestanden niet bijhoudt. Als gevolg hiervan laat Postman geen externe wijzigingen zien totdat we de collectie opnieuw importeren.

9. Conclusie

In dit artikel hebben we Postman gebruikt om semi-automatische tests voor een REST API te maken. Hoewel dit artikel dient als een inleiding tot de basisfuncties van Postman, hebben we nauwelijks de oppervlakte van zijn mogelijkheden bekrast. De online documentatie van Postman is een waardevolle bron voor diepere verkenning.

De collectie die in deze tutorial is gemaakt, is beschikbaar op GitHub.