Contract Test using Postman

Postman은 API 개발을 보다 쉽고 빠르게 만들어주고, 개발한 API를 테스트하고 결과를 공유하여 생산성을 높여주는 플랫폼입니다. 일반적으로 API 테스트, 특히 REST API 테스트 시에 Postman을 사용하는 경우가 많습니다.

postman은 native 앱을 제공하고 있어 설치하여 사용할 수 있으며 크롬의 확장 프로그램 또한 제공하고 있습니다. 그러나 확장 프로그램의 경우 old version으로 제공되고 있으며 추후 deprecated 될 예정이라고 합니다. (Postman을 다운로드하고 설치하는 방법은 각각 링크를 통해 확인하실 수 있습니다)

가장 일반적인 HTTP 메서드인 GET, POST, PUT, DELETE를 포함하여 PATCH, HEAD, LOCK 등 다양한 요청을 지원합니다. 또한 요청을 보낼 때에 헤더에 정보를 넣거나, 파라미터나 바디에 데이터를 실어 보낼 수도 있습니다.  이에 대한 응답은 상태 코드와 메시지를 받게 됩니다. 개발자가 직접 응답을 보면서 확인할 수도 있지만, 테스트 스크립트를 작성하여 요청에 대한 응답이 의도한 대로 왔는지 확인할 수도 있습니다. 보통 테스트 자동화 시에 많이 사용하지만, 비동기로 동작하는 서비스를 테스트하는 경우에는 원하는 대로 동작하지 않을 수 있습니다.  이에 대한 자세한 내용은 아래, (2) automation에서 다루도록 하겠습니다. 

 

 

(1) postman basic concepts

 

포스트맨은 몇 가지 주요한 기본 기능을 제공합니다.

 - workspaces : postman의 모든 것들은 workspaces를 통해 공유될 수 있습니다. 팀을 위한 워크스페이스는 별도로 권한을 주어 변경 권한을 주지 않을 수도 있습니다. 리얼타임으로 동기화되므로 협업을 하기에 용이합니다.

 - collections : 개별적인 요청들을 그룹화하여 저장하고, 재사용하고 공유할 수 있도록 해주는 방법입니다. API 동작을 테스트하기 위해서, 문서화하여 다른 사용자에게 API 사용 법을 보여주기 위해서 collection를 사용합니다. 

 - environment : server configurations, 테스트를 위한 사용자 credentials 등을 팀원 간에 공유하기 쉽게 해 주고, 개인정보를 감추는 역할을 합니다. 로컬 시스템, 개발 서버, 프로덕션 API에 대해 서로 다른 설정이 필요한 경우, environment를 사용하여 요청을 변경하지 않고 쉽게 전환할 수 있습니다. 

 - test and scripts : API 응답의 정확성을 보장하는 방법으로, 요청 간에 데이터를 전달하고, 요청 및 collection에 동적 행동을 추가할 수 있도록 해줍니다. 테스트를 작성하고, 요청들을 체이닝 하고, 자동화할 수 있습니다. 

 - syncing : 데이터를 백업하고, 클라우드에 저장할 수 있습니다. 편집, 추가, 삭제와 같은 변경 사항은 계정에 연결된 모든 장치 간에 동기화됩니다. 마찬가지로 구글 서버와 동기화되어 클라우드에 저장될 수 있습니다. 

 - running a collection : 컬렉션 내 일련의 요청들을 environment에 상응하여 실행시킵니다. 컬렉션이 반복되는 횟수를 지정할 수 있으며, 각 요청 간에 지연 시간을 줄 수도 있습니다. 

 - mock an api response : postman 모의 서버를 사용하여 실제로 엔드포인트를 구축하기 이전에 서버 응답을 시뮬레이션할 수 있습니다. 모의 서버는 기본적으로 공개되어 있어 누구나 액세스 할 수 있지만, 요청 헤더에 poastman api key를 추가하여 비공개로 만들 수도 있습니다. 이 경우 팀 또는 특정 팀 구성원과 공유하고 편집할 수 있도록 권한을 제공할 수 있습니다. 

 

(2) automation

 

지난 뉴스클리핑에서 다루었던 postman 기본 개념들을 이용하면 테스트 자동화를 구성할 수 있습니다. 

먼저, 도메인에 대한 컬렉션을 만들고 컬렉션 내에 이 도메인의 API 요청을 만들어줍니다. url을 기재하고, 필요하다면 헤더 정보를 추가하거나 바디에 데이터를 추가할 수 있습니다. 

그리고 요청하는 API에 대한 응답이 제대로 왔는지 확인하기 위해서 Tests를 작성해주어야 합니다. 이는 기본 개념에서 다룬 바 있으므로 따로 다루지 않겠습니다. (Test Scripts)

요청을 모두 작성하였다면 컬렉션을 Run하여 결과를 확인할 수 있습니다. Collection Runner라는 화면에서 환경변수나 반복 횟수, 지연시간 등을 지정해 줄 수도 있습니다. 테스트를 실행하게 되면 아래와 같이 성공한 경우와 실패한 경우를 직관적으로 확인할 수 있습니다. 

여기에 더해 Newman과 Jenkins를 이용하면 더욱 강력한 테스트 자동화를 구축할 수 있습니다. (Jenkins 대신 GitLab CI를 사용할 수 있습니다. ) 빌드 시스템을 연결하여 포스트맨을 실행하는 과정조차도 단축시킬 수 있습니다.  Newman은 Postman의 CLI로, 각기 다른 환경에서 동일한 방법으로 테스트를 실행할 수 있습니다. Postman이 익숙하다면 Newman을 사용하는 것은 크게 어렵지 않으므로 자세한 내용은 Postman Blog에서 확인해 보시면 됩니다. 

 

(3) advanced features

 

앞서 포스트맨의 기본적인 기능과 자동화에 대하여 다룬 바 있습니다. 여기에서 조금 더 심화하여 API Test시 로그인 세션을 처리하는 방법과 응답에서 데이터를 추출하여 연쇄 요청을 작성하는 방법, 모니터링에 대하여 다루어보도록 하겠습니다.

포스트맨으로 요청을 보낼 경우 권한을 부여하여 인증이 가능하도록 지원합니다. 아래와 같이 Authorization이라는 화면에서 원하는 인증 방법을 선택할 수 있습니다. 

각 인증 종류별로 어떠한 인증인지, 어떻게 설정하면 되는지에 대한 정보는 Authorization에서 확인하실 수 있습니다. 또한 쿠키 기능을 지원하므로, 쿠키에 세션 정보를 저장함으로써, 포스트맨 상에서 지속된 로그인 상태를 유지하도록 만들어 줄 수도 있습니다.

다음으로 Response에서 데이터를 추출하고, 이를 연쇄적인 요청으로 전달하는 방법에 대해 알아보겠습니다.

포스트맨은 응답을 받기 전과 후에 실행되는 스크립트를 작성할 수 있습니다. 이로 인해 응답에서 값을 추출하여 환경변수나 전역 변수에 저장하는 것이 가능합니다. 세션 토큰 혹은 사용자 ID 정보를 이어지는 요청에서 계속적으로 사용해야 할 때 주로 사용합니다. 예를 들어 요청의 결과, 즉 응답이 세션 토큰을 포함한 JSON이라고 가정합니다. 이때 토큰을 추출하기 위해서는 포스트맨이 제공하는 postman.setEnvironmentVariable(key, value)또는 postman.setGlobalVariable(key, value)를 호출하기만 하면 됩니다. 그리고 이렇게 가져온 데이터는 환경 변수 혹은 전역 변수에 저장되고, 이를 다음 요청에서 사용하고자 할 때는 {{key}} 와 같은 형태로 아주 쉽게 사용이 가능합니다.

자세한 내용은 Extracting data from responses and chaining requests에서 확인하실 수 있습니다.

마지막은 모니터링입니다. 포스트맨은 테스트 결과에 대한 모니터링 결과를 리포팅해줍니다. 테스트를 전부 자동화해둔 뒤에는 개발자가 일일이 테스트 결과를 확인하는 것은 번거로운 일이 될 것입니다. 그러므로 모니터링 기능을 활용하게 되면, 분, 시, 날짜 단위로 모니터링을 지정할 수 있고, 모니터링 리포트를 통해 결과에 대한 정보를 확인할 수 있습니다.

 

좀 더 이해를 돕기 위해, Chained Request 에 대한 간단한 샘플 코드를 다루어 보겠습니다. 덧붙여 Postman이 어떻게 로그인 유지를 수행하는 지도 알아보겠습니다. 

먼저 Chaind Request입니다. 게시물을 삽입하는 요청과 삽입된 게시물 ID를 받아 첨부된 이미지 파일을 삽입하는 요청이 있다고 가정해 봅시다.

게시물 정보에 대한 요청의 결과로 boardId를 반환하게 됩니다. 

response로부터 받은 데이터를 환경변수 혹은 전역 변수로 등록해줍니다. 이렇게 등록된 boardId는 이어지는 요청에서 {{boardId}}와 같이 사용이 가능합니다. 

다음으로 Postman이 로그인에 대한 정보를 어떻게 유지하는 지 알아보겠습니다. 세션을 사용하여 로그인을 유지한다고 가정해 봅시다.

일반적으로 서버와 브라우저가 통신할 때 세션이 유지되는 이유는 JSESSIONID라는 세션 식별자 때문입니다. 서버에서 Response 헤더에 세션 식별자인 JSESSIONID를 set-cookie로 추가하여 응답을 보내면, 클라이언트 헤더가 이를 읽고 다음 요청 시에 cookies에 JESSIONID를 추가하여 전송하게 됩니다. 서버는 JSESSIONID를 통해 세션 정보를 특정화하여 사용할 수 있게 되는 것입니다. 이는 브라우저가 이를 수행하기 때문인데, Postman 역시 동일하게 수행됩니다. 아래와 같이 로그인 요청 후 응답에 set-cookie가 설정된 것을 볼 수 있습니다. 

또한 이어지는 요청에서 헤더에 cookie로 동일한 JSESSIONID가 넘어가는 것을 볼 수 있습니다. 따라서 로그인 요청을 보낸 후 이어지는 요청이 로그인이 필요한 경우 서버에서 세션에 등록만 해주면 브라우저와 통신하는 것과 동일하게 사용이 가능합니다.

쿠키가 등록되었기 때문에, 앱 화면 우측부의 Cookies창에서 사용된 JSESSIONID를 확인할 수 있으며 여기서 삽입, 삭제, 변경 또한 가능합니다. 

 

또 다른 advanced feature로는 Jenkins를 이용한 Test 자동화입니다. 이 기능을 사용하기 위해서는 jenkins가 설치된 서버에 newman이 반드시 설치되어 있어야 하며, 테스트를 하기 위한 Collection 역시 서버 내에 존재해야 합니다. 로컬에서 newman을 이용하여 테스팅하는 것과 동일하게, 젠킨스가 서버 내 존재하는 Collection 파일을 newman을 이용하여 실행하는 것이기 때문입니다. 

 

그럼 예시를 다루어보겠습니다. 먼저, Jenkins project를 생성하고, build의 execute shell을 작성합니다.

만약 실패한 리퀘스트가 있는 경우에는 Console Output 결과는 Failed로 출력됩니다. 

모든 결과가 Success된 경우, newman으로 실행할 때와 동일한 결과가 Console Output에 출력되는 것을 확인할 수 있습니다.

 

Tip!

 

Postman은 데이터를 file이나 URL의 형태로 export, import가 가능합니다.

 

import의 경우 json외에도 cUR, RAML, Swagger, WADL 데이터 포맷이 import 가능합니다. swagger의 경우에는 v1, v2를 지원하며, WADL은 아직 모든 측면을 지원하지는 않지만 다양한 매개변수를 올바르게 생성할 수 있습니다.  각자 데이터 포맷에 맞춰 저장된 파일을 단순히 import 하기만 하면, 내부적으로 변환을 거쳐 적용됩니다.