[Hurl] 여러 API 호출 시나리오를 로컬에서 테스트하기

Hurl

 

Hurl은 HTTP 요청을 실행할 수 있을 뿐만 아니라 HTTP 응답을 테스트하는 데에도 사용할 수 있다 .

 

들어가며

이번 태스크는 화면에서 직접 호출하는 API가 아니라, 여러 API 호출을 이어주는 Domain Handler를 개발하는 작업이었다.

Handler 하나를 검증하려면 로그인부터 프로젝트 생성, 파이프라인 생성, 연결 정보 저장 등 수많은 선행 API를 먼저 호출해야 했다.

Playwright도 고민했지만, 화면 역시 내부적으로는 API를 호출하는 과정일 뿐이었다.

내가 검증하고 싶었던 것은 UI가 아니라 특정 Handler를 실행하기 위한 API 호출 흐름이었다.

처음에는 JUnit 기반 E2E 테스트도 고려했다.

하지만 복잡한 테스트 코드보다 여러 API 호출 시나리오를 선언적으로 관리하고 반복 실행하는 것이 목적이었고, 그 과정에서 `Hurl`을 사용하게 되었다.

 

흐름도

 

Hurl이란?

API 테스트를 하다 보면 `Postman`이나 `Insomnia`를 많이 사용한다.

하지만 CI/CD 환경이나 자동화 테스트에서는 GUI 도구보다 텍스트 기반으로 API를 관리하고 실행할 수 있는 도구가 더 유리한 경우가 많다.

최근 HTTP 테스트 도구를 찾다가 `Hurl`이라는 오픈소스를 알게 되었고, 생각보다 사용성이 좋아 간단하게 정리해 보려고 한다.

 

Hurl

`Hurl`은 `HTTP` 요청과 응답 검증을 하나의 파일에 작성하여 실행할 수 있는 `CLI` 기반 테스트 도구이다.

확장자는 `.hurl`을 사용하며 사람이 읽기 쉬운 문법을 제공한다.

예를 들어 아래처럼 작성하면 된다.

GET https://httpbin.org/get

HTTP 200

실행

hurl test.hurl

응답이 200이 아니면 즉시 실패한다.

별도의 코드 작성 없이도 API 테스트가 가능하다.

 

왜 Hurl인가?

Hurl은 HTTP 요청과 응답을 선언적으로 작성하는 DSL(Domain Specific Language)이다.

프로그래밍 언어 대신 HTTP 시나리오 자체를 기술하는 데 초점을 맞추고 있어 테스트 코드라기보다 실행 가능한 시나리오 문서에 가깝다.

 

왜 Hurl을 사용할까?

기존에는 API 테스트를 위해

• curl
• Postman
• Rest Assured
• JUnit

등을 많이 사용했다.

하지만 각각 아쉬운 점이 존재한다.

curl

요청은 쉽지만 응답 검증이 어렵다.

curl https://example.com

응답 코드나 Body를 직접 확인해야 한다.

 

Postman

GUI 환경에서는 매우 편리하다.

하지만

• Git으로 관리하기 어렵고
• 코드 리뷰가 어렵고
• CI/CD 연동 시 추가 작업이 필요하다.

 

Rest Assured

Java 프로젝트에서는 강력하다.

하지만 단순 API 테스트를 위해 테스트 코드 작성이 필요하다.

given()
.when()
.get("/users")
.then()
.statusCode(200);

간단한 API 하나를 검증하는데도 코드가 필요하다.

 

Hurl

Hurl은 요청과 검증을 한 파일에서 관리할 수 있다.

GET https://httpbin.org/get

HTTP 200

header "Content-Type" contains "application/json"

jsonpath "$.url" == "https://httpbin.org/get"

요청과 검증 내용이 한눈에 보인다.

 

POST 요청

Body도 쉽게 작성 가능하다.

POST https://httpbin.org/post
Content-Type: application/json

{
    "name":"jihye"
}

HTTP 200

jsonpath "$.json.name" == "jihye"

`JSON` 검증도 매우 직관적이다.

 

변수 사용

변수도 사용할 수 있다.

GET {{host}}/users

HTTP 200

실행

hurl \
    --variable host=https://example.com \
    test.hurl

환경별 URL 변경도 간단하다.

 

여러 API 시나리오 테스트

로그인 후 조회하는 시나리오도 작성 가능하다.

POST https://example.com/login

{
    "id":"admin",
    "password":"1234"
}

HTTP 200

[Captures]
token: jsonpath "$.token"

GET https://example.com/user

Authorization: Bearer {{token}}

HTTP 200

`Captures`를 이용하면 이전 응답을 다음 요청에서 그대로 사용할 수 있다.

응답 값을 캡처하여 다음 요청에서 사용할 수 있어서 생각보다 활용도가 높다.

 

CI/CD에서 활용

개인적으로 가장 마음에 들었던 부분이다.

Jenkins나 GitHub Actions에서

hurl api-test.hurl

한 줄만 실행하면 된다.

테스트 실패 시 Exit Code를 반환하므로 파이프라인에서 즉시 실패 처리할 수 있다.

예를 들어

• API Smoke Test
• 배포 후 Health Check
• Gateway 응답 검증
• 인증 API 테스트

등에 활용하기 좋아 보였다.

실제로 DevOps 환경에서는 Postman Collection보다 관리하기 편한 경우도 많을 것 같다.

 

장점

• 문법이 직관적이다.
• `Git` 관리가 쉽다.
• 코드 리뷰가 편하다.
• `CLI` 기반이라 Jenkins, GitHub Actions, GitLab CI 등에서 별도 플러그인 없이 실행할 수 있다.
• `Java`나 `JavaScript` 테스트 코드를 작성하지 않고도 `HTTP` 요청과 검증을 선언적으로 작성할 수 있다.
• 실행 가능한 API 시나리오 문서로 활용할 수도 있다.

 

아쉬운 점

복잡한 조건 분기나 반복 처리, 프로그래밍 수준의 제어가 필요한 테스트는 JUnit이나 Rest Assured가 더 유연하다.

반면 `Hurl`은 `HTTP` 요청과 응답 시나리오를 선언적으로 작성하는 데 강점이 있다.

 

선택한 이유

기능만 놓고 보면 JUnit이나 Rest Assured로도 충분히 구현할 수 있다.

하지만 이번에는 테스트 코드 작성보다 API 호출 시나리오 자체를 관리하는 것에 더 초점을 두었다.

특히 내가 개발한 `handler`를 실행하기 위해서는 프로젝트 생성, 기본 정보 등록, 상세 정보 수정 등 여러 선행 API를 순차적으로 호출해야 했고, 이러한 과정을 반복해서 수행해야 하는 경우가 많았다.

레고를 조립하기 전에 필요한 부품을 먼저 만들어 두는 것처럼, 이후 테스트에서 사용할 기초 데이터를 API 시나리오를 통해 자동으로 생성하고 재사용하고 싶었다.

물론 `JUnit`으로도 구현할 수 있지만, 테스트 코드로 관리하는 것보다 `HTTP` 요청 흐름을 선언적으로 작성하는 편이 훨씬 직관적이었고, 다른 개발자도 별도의 코드 이해 없이 쉽게 실행할 수 있다는 장점이 있었다.

결과적으로 `Hurl`은 단순한 API 테스트 도구라기보다, 반복적으로 실행 가능한 API 시나리오이자 개발용 데이터 생성 스크립트를 관리하는 용도로 더 잘 맞는 선택이었다고 느꼈다.

 

실제 사용

`hurl` 코드 작성 -> 스크립트 작성으로 환경 변수 설정 및 주입 -> 스크립트 실행

IntelliJ에서 각각 실행 시 Service에서 HTTP Request를 확인할 수도 있다.

 

마무리

결국 Hurl을 선택한 이유는 JUnit으로 구현할 수 없어서가 아니었다.

특정 Handler를 실행하기 위해 필요한 여러 API 호출 흐름을 코드보다 시나리오 형태로 관리하고 반복 실행하고 싶었기 때문이었다.

비슷한 상황이라면 Hurl도 충분히 좋은 선택지가 될 수 있을 것 같다.

 

`Hurl`은 학습 비용이 낮고 문법도 직관적이라 빠르게 도입할 수 있는 도구라고 생각한다.

특히 CI/CD 파이프라인에서 HTTP API를 자동 검증해야 하는 환경이라면 한 번쯤 사용해볼 만한 오픈소스인 것 같다.

 

다음에는 실제 Jenkins Pipeline에서 Hurl을 이용해 배포 후 Health Check를 수행하는 예제도 정리해볼 예정이다.

이번에는 개발 중 반복적으로 실행해야 하는 API 시나리오를 관리하기 위해 사용했지만, 배포 후 Health Check나 Smoke Test에도 충분히 활용할 수 있을 것 같다.

---

공식 문서

https://hurl.dev/

 

GitHub Repo

https://github.com/Orange-OpenSource/hurl

GitHub - Orange-OpenSource/hurl: Hurl, run and test HTTP requests with plain text.