Postman
Postman és una eina de programari per a la creació, documentació, administració i proves de APIs. És una plataforma gratuïta i de codi obert que està disponible per a Windows, macOS, Linux i Chrome US. Proporciona una interfície fàcil d'usar que permet als desenvolupadors realitzar diverses operacions relacionades amb APIs, com enviar sol·licituds HTTP, analitzar respostes, organitzar i gestionar entorns de prova, i col·laborar amb altres membres de l'equip.
Característiques principals
Postman ofereix una àmplia gamma de característiques que la converteixen en una eina indispensable per a desenvolupadors, administradors i testers de APIs. Entre les seves principals característiques s'inclouen:
- Creació de peticions: Postman permet crear peticions HTTP de manera senzilla i ràpida. Les peticions es poden personalitzar amb paràmetres, headers, bodi i altres elements.
- Documentació de APIs: Postman permet documentar APIs de manera clara i concisa. La documentació es pot generar en format HTML, Markdown o JSON.
- Administració de APIs: Postman permet administrar APIs de forma centralitzada. Les APIs es poden organitzar en col·leccions, compartir amb altres usuaris i provar de manera automàtica.
- Proves de APIs: Postman ofereix una àmplia gamma d'eines per a provar APIs. Les proves es poden realitzar de manera manual o automàtica, i es poden personalitzar amb escenaris, assertions i altres elements.
- Interfície Gràfica d'Usuari (GUI): Postman presenta una interfície gràfica intuïtiva que facilita la creació, l'enviament i la visualització de sol·licituds HTTP. Els desenvolupadors poden realitzar operacions com GET, POST, PUT, DELETE i més amb solo uns pocs clics.
- Col·leccions: Les col·leccions són grups de sol·licituds que es poden organitzar i executar de manera seqüencial o simultània. Això facilita la gestió de proves i l'execució de seqüències d'anomenades a API.
- Entorns: Els entorns permeten configurar variables d'entorn que poden canviar dinàmicament segons l'entorn de desenvolupament, com a desenvolupament, prova o producció. Això facilita la portabilitat de les proves entre diferents configuracions.
- Variables i Scripts: Postman admet l'ús de variables en les sol·licituds i respostes, la qual cosa facilita la parametrització de les proves. A més, es poden utilitzar scripts pre i post-sol·licitud, escrits en JavaScript, per a automatitzar tasques i realitzar accions condicionals.
- Monitoratge: Postman ofereix funcions de monitoratge que permeten als equips supervisar el rendiment de les API al llarg del temps. Pots configurar monitors per a executar col·leccions de manera regular i rebre alertes si hi ha problemes.
- Automatització: Postman s'integra amb diverses eines de CI/CD (Integració Contínua/Lliurament Continu) per a automatitzar proves i assegurar la consistència en el desenvolupament i la implementació.
- Generació de Documentació: Postman permet generar automàticament documentació per a les API provades, la qual cosa facilita la comprensió i el consum de les API per part d'altres desenvolupadors.
- Col·laboració: Els equips poden col·laborar en Postman compartint col·leccions, entorns i altres recursos. A més, Postman proporciona funcions de sincronització en el núvol per a mantenir actualitzats els canvis realitzats per diferents membres de l'equip.
Avantatges de Postman
Postman ofereix una sèrie d'avantatges que la converteixen en una eina de referència per al desenvolupament, administració i proves de APIs. Entre els seus principals avantatges s'inclouen:
- Facilitat d'ús: Postman és una eina fàcil d'aprendre i usar. La seva interfície és intuïtiva i les seves característiques estan ben organitzades.
- Flexibilitat Postman és una eina flexible que es pot adaptar a les necessitats de qualsevol projecte.
- Comunitat: Postman compta amb una àmplia comunitat d'usuaris i desenvolupadors que comparteixen recursos i coneixements.
Creació de Proves amb Postman
Amb Postman, és possible afegir scripts a la nostra petició per a utilitzar variables dinàmiques, passar dades entre peticions i escriure proves. El codi afegit en la pestanya Script previ a la sol·licitud s'executarà abans d'enviar la sol·licitud, i el codi afegit en la pestanya Proves s'executarà després de rebre la resposta.
Les proves són scripts escrits en JavaScript que s'executen després de rebre una resposta. Les proves poden executar-se com a part d'una única sol·licitud o amb una col·lecció de sol·licituds.
En l'aplicació Postman, el generador de sol·licituds de la part superior conté la pestanya Proves, en la qual s'escriuen les proves. El visor de respostes, en la part inferior, conté la pestanya corresponent als resultats de les proves.
Per a començar a crear casos de prova ràpidament, al costat de l'editor de proves apareixen fragments d'ús comú. Seleccioni un fragment per a afegir el codi a l'editor de proves. Si és necessari, actualitzi el stub amb assercions específiques per a la resposta esperada de la seva endpoint. A continuació, enviï la sol·licitud per a veure els resultats de la prova en la part inferior.
Creació d'una Prova
A continuació mostamos els passos per a crear una prova:
Pas 1. Creació d'Una col·lecció de Proves
Punxar en el botó “+” i posar nom a la col·lecció
Pas 2. Creació de la Prova
Punxarem en el botó “New” i a continuació indicarem el tipus de servei que volem provar.
Pas 3. Indicar la URL del endpoint del Servei
Pas 4. Donar d'alta les Variables d'Entorn
Per a això punxarem en l'opció Environments del menú de l'esquerra i seguidament punxant en l'opció “+” crearem un nou entorn. Dins d'aquest entorn crearem les diferents variables d'entorn.
Pas 5. Escriure tests
També podem escriure pròpies proves personalitzades en JavaScript. Postman té una PM API (coneguda com pm.* API) que és la forma més potent d'escriure proves.
pm.test()
La funció pm.test() s'utilitza per a escriure especificacions de proves dins del sandbox de proves de Postman. Escriure proves dins d'aquesta funció ens permet nomenar la prova amb precisió, i assegura que la resta del script no es bloquegi en cas de qualsevol error.
Algunes coses que cal saber sobre la funció pm.test()
- La funció accepta 2 paràmetres, el nom de la prova (com a cadena) i una funció per a retornar un valor booleà.
- Només pot utilitzar-se en la pestanya Tests, després que s'hagi enviat la sol·licitud principal de Postman.
Alguns exemples:
pm.test("Response status code is 200", function () {
pm.response.to.have.status(200);
});
pm.test("First name is a non-empty string", function () {
const responseData = pm.response.json();
pm.expect(responseData.firstName).to.exist.and.to.be.a('string').and.to.have.lengthOf.at.least(1, "Value should not be empty");
});
pm.test("Last name is a non-empty string", function () {
const responseData = pm.response.json();
pm.expect(responseData.lastName).to.exist.and.to.be.a('string').and.to.have.lengthOf.at.least(1, "Value should not be empty");
});
pm.test("Telephone number is in a valid format", function () {
const responseData = pm.response.json();
pm.expect(responseData.telephone).to.match(/^\d{10}$/);
});
function constructVisualizerPayload() {
return { response: pm.response.json() }
}
També hi ha altres comandos que es poden utilitzar juntament amb pm.test().
pm.expect()
La funció d'asserció pm.expect() es va construir sobre la biblioteca de proves de JavaScript ChaiJS BDD. Usant una sintaxi similar, pm.expect() facilita l'escriptura de proves llegibles, i pot tractar amb assercions de dades d'una resposta o variables.
pm.response.to.be.*
L'objecte pm.resonse.to.be proporciona abreviatures per a comprovacions basades en respostes d'ús freqüent. L'ús d'aquesta família d'assercions agilitza les proves per als tipus d'estat de resposta i les variacions del cos.
Test results
Com sabem si les proves estan passant o fallant?
Després d'executar una sol·licitud amb proves, hem d'anar a la pestanya Tests en el visor de respostes. En aquest punt veurem una llista de les proves i si la prova ha passat o fallat. Un booleà avaluat com a veritable és una prova superada, i un booleà avaluat com a fals és una prova fallida.
Execució de tests
Quan executem una col·lecció utilitzant l'executor de col·leccions en l'aplicació Postman, podem veure les proves en execució i els resultats en temps real.
Execució amb Newman
Executar una col·lecció utilitzant l'eina de línia de comandos Newman de Postman, ens permet veure els resultats de la prova en el terminal i possibilita que l'execució es pugui dur a terme des d'una eina d'Integració Contínua com Jenkins o GitHub Actions p.e.
Per a això, abans necessitarem fer una exportació de les col·leccions i variables d'entorn. Per a realitzar l'exportació d'una col·lecció simplement la seleccionarem i pressionant botó de 3 punts seleccionarem l'opció “Export”. De la mateixa manera actuarem amb les varibles d'entorn:
Newman està basat en Node.js. Per a executar Newman, hem d'assegurar-nos de tenir instal·lat Node.js usant Node.js v16 o posterior.
Posteriorment hem d'instal·lar Newman des de npm globalment en el teu sistema, la qual cosa et permetrà executar-lo des de qualsevol lloc:
$ npm install -g newman
//ejecución de pruebas
$ newman run petclinic-backend-postman.json -e environment.json
Performance Testing
Postman permet l'execució de Proves de Rendiment sobre els serveis que estiguem provant. Per a això podem configurar a través de l'opció Performance les condicions d'aquesta execució.
El resultat de l'execució s'anirà mostrant a mesura que es vagin llançant les execucions
Podrem veure la descripció dels errors produïts durant la prova
Plantilla de Projecte
La plantilla de projecte de proves té la següent forma:
backend-test-java
│ environment.json
│ template-backend-postman.json
│ README.md
└───.devcontainer
│ devcontainer.json
│ Dockerfile
| Element |
Descripció |
| environment.json |
Fitxer que conté la defición de les variables d'entorn de la prova.
|
| template-backend-postman.json |
Conté el disseny de les proves de backend. Hem de tenir en compte que hem de substituir en el nom del fitxer:
- template = $nom_de el_projecte
En aquest json, es pot modificar el paràmetre de "name" i incloure el nom del Lot de l'aplicació. Això ajudarà a una millor visió dels resultats en Grafana (veure apartat Grafana més endavant).
|
| README.md |
Fitxer markdown que conté documentació |
| devcontainer.json |
Definició del contenidor on s'executarà la prova en entorn local a través de newman
|
| Dockerfile |
|
Procés de generació de proves
