Bruno는 REST, GraphQL, gRPC와 WebSocket 요청을 로컬 Collection으로 관리하는 API 클라이언트입니다.
Windows x64 설치 파일을 받고 GET 요청을 보내 상태 코드, JSON 응답, Test와 Runner까지 확인합니다.
Bruno는 어떤 프로그램인가요?
요청을 .bru 파일로 저장해 Git에서 변경 내역을 검토할 수 있습니다.
환경 변수, 인증, 스크립트, Tests와 Collection Runner를 한 앱에서 사용합니다.
Bruno 워크스페이스와 환경 변수 실제 화면
공식 화면에서 Collection 탐색기, 요청 편집기, Send, 응답 영역과 환경 변수 표를 확인할 수 있습니다.
| x64 | 일반 EXE·Portable ZIP·MSI |
|---|---|
| Arm64 | EXE·Portable ZIP·MSI |
| 서명 | Bruno Software Inc |
| 저장 | 로컬 .bru 파일 |
| 테스트 | Tests·Collection Runner |
| 계정 | 기본 API Client 사용에 불필요 |
Bruno 4.2.1 설치와 첫 REST 요청
Bruno는 REST, GraphQL, gRPC와 WebSocket 요청을 한 화면에서 만들고 응답을 검사하는 API 클라이언트입니다. Windows x64 일반 설치 파일은 bruno_4.2.1_x64_win.exe이며 공식 GitHub Release 자산으로 배포됩니다.
설치 뒤 샘플 Collection을 만들고 GET 요청을 보낸 다음 상태 코드, 응답 본문과 저장된 .bru 파일까지 확인하는 순서로 진행합니다. 계정 없이 로컬 폴더에 컬렉션을 저장할 수 있습니다.
- Windows 아키텍처에 맞는 EXE를 받고 Bruno Software Inc 서명을 확인합니다.
- Create Collection에서 로컬 저장 폴더를 지정합니다.
- Create Request로 REST GET 요청을 만듭니다.
- Environment에 baseUrl을 만들고 요청 URL에서 참조합니다.
- Send를 눌러 상태 코드와 JSON Body를 확인합니다.
- Tests에 상태 코드 조건을 추가합니다.
- Collection Runner에서 저장한 요청을 다시 실행합니다.
Windows x64와 Arm64 파일 선택
Intel 또는 AMD 기반 Windows PC는 Windows x64 EXE를 선택합니다. Qualcomm 계열 Arm PC는 Windows Arm64 EXE를 선택하며, 설치 권한이 없을 때는 같은 아키텍처의 Portable ZIP을 받아 전체 압축을 풉니다.
MSI는 조직 배포나 관리 도구에 맞는 선택지입니다. x64, Arm64와 Portable을 이름만 보고 섞지 말고 Windows 설정의 시스템 종류를 확인한 뒤 받습니다.
설치 파일과 서명 확인
현재 Windows x64 EXE는 121,897,928바이트이며 파일 버전과 제품 버전이 모두 4.2.1입니다. 파일 속성의 디지털 서명에서 Bruno Software Inc와 유효한 서명을 확인합니다.
다운로드가 중단돼 파일 크기가 지나치게 작거나 서명이 없으면 실행하지 않습니다. 공식 다운로드 페이지에서 다시 받은 뒤 동일한 파일 이름과 버전을 확인합니다.
새 Collection 저장 폴더 정하기
Bruno를 열고 Create Collection을 선택해 이름을 입력한 뒤 저장할 로컬 폴더를 지정합니다. 프로젝트 저장소 안에 api-tests 같은 폴더를 만들면 .bru 요청 파일을 Git 변경 내역으로 검토할 수 있습니다.
동기화 드라이브나 쓰기 권한이 제한된 폴더는 저장 오류를 만들 수 있습니다. 처음에는 사용자 문서 아래의 빈 폴더로 시험하고 collection.bru 또는 bruno.json과 요청 파일이 생기는지 확인합니다.
Create Request로 GET 요청 만들기
Collection 옆 메뉴에서 New Request 또는 Create Request를 선택하고 요청 이름, REST 유형과 저장 위치를 정합니다. 요청 편집기에서 메서드를 GET으로 두고 테스트할 URL을 입력합니다.
인증이 필요한 실제 서비스보다 공개 테스트 엔드포인트나 개발 서버의 health 경로로 먼저 확인합니다. 요청 이름과 파일 이름은 팀이 알아보기 쉽게 동작과 자원을 함께 적습니다.
Send 뒤 응답 읽기
URL 오른쪽 Send를 누르면 아래 응답 영역에 상태 코드, 소요 시간, 크기와 Body가 표시됩니다. 성공 요청은 API 사양에 맞는 2xx 코드인지 보고 JSON 탭에서 필요한 필드가 있는지 확인합니다.
404는 경로, 401과 403은 인증, 5xx는 서버 쪽 문제일 가능성이 큽니다. 응답 본문만 복사하기 전에 Headers와 Timeline을 함께 보면 리디렉션과 실제 요청 주소를 찾기 쉽습니다.
Query와 Params 입력
URL에 직접 물음표를 붙이는 대신 Params 탭에서 키와 값을 행으로 추가하면 활성 체크 상태가 주소에 반영됩니다. 같은 키가 여러 번 필요한 API는 행을 나눠 순서를 확인합니다.
값에 공백, 한글이나 슬래시가 있을 때는 생성된 URL의 인코딩을 확인합니다. 빈 값과 비활성 행이 섞이면 서버가 받은 쿼리가 예상과 달라질 수 있습니다.
Headers와 Content-Type 확인
Headers 탭에서 Accept, Content-Type과 서비스 고유 헤더를 입력합니다. JSON 본문을 보낼 때 Content-Type이 application/json인지 확인하고 중복 헤더가 없는지 봅니다.
토큰을 일반 헤더 값에 그대로 저장하면 컬렉션 파일에 남을 수 있습니다. Authorization은 Auth 탭이나 Secret 환경 변수로 분리하고 저장소에 실제 키를 커밋하지 않습니다.
POST Body 작성
메서드를 POST로 바꾸고 Body 탭에서 JSON을 선택한 뒤 API 문서의 필수 필드를 입력합니다. Send 전에 괄호, 쉼표와 문자열 따옴표가 올바른지 편집기 오류 표시를 확인합니다.
서버가 form-urlencoded나 multipart를 요구하면 JSON을 고집하지 말고 해당 Body 형식을 선택합니다. 파일 업로드는 multipart 행에서 파일 필드를 지정하고 실제 전송된 Content-Type을 Timeline으로 확인합니다.
Auth에서 Bearer 토큰 넣기
Auth 탭에서 Bearer Token을 선택하고 토큰 칸에는 {{token}}처럼 환경 변수 참조를 넣습니다. Collection 또는 Folder 수준 인증을 상속할 때 요청 수준이 Override인지 Inherit인지 확인합니다.
Authorization 헤더를 Headers 탭에도 만들면 두 값이 충돌할 수 있습니다. 하나만 남기고 응답이 401이면 토큰 만료, 접두어와 대상 환경부터 점검합니다.
Environment와 baseUrl 사용
Environment를 만들고 baseUrl, token처럼 개발과 운영에서 달라지는 값을 저장합니다. 요청 URL은 {{baseUrl}}/users처럼 작성하고 상단 환경 선택기에서 현재 환경을 고릅니다.
비밀값은 Secret으로 표시하고 값이 컬렉션 파일에 평문으로 남지 않는지 확인합니다. 환경을 바꾼 뒤에는 Send 전에 해석된 URL과 선택된 환경 이름을 다시 봅니다.
Tests에서 상태 코드 검사
요청의 Tests 또는 Assert 영역에 상태 코드 200, 응답 필드와 응답 시간 조건을 추가합니다. Send 뒤 Tests 결과가 모두 통과하는지 보고 실패 항목의 기대값과 실제값을 비교합니다.
본문 구조가 바뀔 수 있는 API에는 값 하나를 고정하기보다 필드 존재와 자료형을 검사합니다. 인증 실패처럼 의도한 오류 응답도 별도 요청으로 저장하면 회귀 테스트에 도움이 됩니다.
Collection Runner로 여러 요청 실행
Collection 메뉴의 Run 또는 Collection Runner를 열고 실행할 폴더, 환경과 반복 횟수를 선택합니다. 인증 요청이 먼저 필요한 구성은 요청 순서와 스크립트에서 저장하는 변수를 확인합니다.
Runner 결과에서 실패한 요청을 펼쳐 상태 코드와 Assertion을 확인합니다. 개별 Send는 성공해도 환경 선택이나 순서가 다르면 Runner에서 실패할 수 있습니다.
Postman과 OpenAPI 가져오기
Import Collection에서 Postman Collection, OpenAPI 또는 지원되는 형식을 선택합니다. 가져온 뒤 폴더 구조, 인증 상속, 환경 변수와 스크립트 변환 경고를 확인합니다.
가져오기는 완전한 실행 보장을 뜻하지 않습니다. 대표 GET과 인증이 필요한 POST를 직접 보내고 Body, 변수 이름과 테스트가 원본 의도대로 옮겨졌는지 비교합니다.
Git에서 .bru 파일 검토
Bruno 컬렉션은 로컬 폴더에 읽을 수 있는 파일로 저장됩니다. 요청을 수정한 뒤 Git diff에서 URL, 헤더, Body와 테스트 변경을 검토하고 비밀값이 들어가지 않았는지 확인합니다.
자동 생성 파일과 개인 환경 파일의 커밋 범위는 팀 규칙에 맞춥니다. 충돌이 생기면 두 요청을 합친 뒤 Bruno에서 다시 열고 Send와 Runner를 재실행합니다.
요청이 저장되지 않을 때
Collection 폴더가 읽기 전용인지, 보안 프로그램이 파일 생성을 막는지 확인합니다. 창 제목의 저장 상태를 보고 요청을 수정한 뒤 해당 .bru 파일의 수정 시간이 바뀌는지 확인합니다.
네트워크 드라이브에서 문제가 반복되면 로컬 폴더로 Collection을 복사해 엽니다. 같은 이름의 요청 파일 충돌과 Windows에서 사용할 수 없는 파일 이름 문자도 함께 점검합니다.
TLS와 프록시 오류 해결
회사 프록시 환경에서는 Settings의 Proxy 구성을 확인하고 운영체제 프록시와 중복되지 않게 합니다. 사설 인증서를 쓰는 개발 서버는 신뢰할 CA를 등록하는 방법을 우선 사용합니다.
인증서 검증을 끄는 설정은 원인을 가릴 수 있으므로 임시 테스트에만 제한합니다. 호스트 이름, 인증서 만료와 프록시가 바꾼 인증서를 확인한 뒤 정상 검증으로 되돌립니다.
응답이 오래 걸리거나 멈출 때
Timeline에서 DNS, 연결, 리디렉션과 스크립트 실행 구간을 확인합니다. 대용량 응답이나 반복 리디렉션이면 URL과 서버 로그를 먼저 점검합니다.
Pre-request 또는 Post-response 스크립트를 잠시 비활성화해 지연 원인을 분리합니다. 같은 URL을 새 빈 요청에서 보내 정상이라면 Collection 변수와 스크립트를 차례로 복원합니다.
환경 변수가 치환되지 않을 때
{{baseUrl}} 문자열이 그대로 보이면 환경 선택기, 변수 철자와 활성 상태를 확인합니다. Collection, Folder, Request와 Runtime 변수의 같은 이름이 어떤 값을 덮어쓰는지도 봅니다.
대소문자와 앞뒤 공백이 다르면 별개 변수로 처리될 수 있습니다. 테스트용 변수 하나를 단순한 값으로 바꿔 실제 URL에 반영되는지 확인합니다.
Request History로 이전 응답 비교
같은 요청을 여러 번 보냈다면 Request History에서 실행 시각과 응답을 찾아 변경 전후를 비교합니다. 서버 데이터가 달라진 것인지 요청의 Header, Body와 환경이 달라진 것인지 함께 확인합니다.
재현해야 할 실패 요청은 현재 Collection에 별도 이름으로 저장하고 비밀값을 제거합니다. History만 믿고 끝내지 말고 저장한 요청을 다시 Send해 같은 상태 코드와 오류 본문이 나오는지 확인합니다.
Dev Tools와 Timeline으로 실제 전송값 확인
화면 아래 Dev Tools와 요청 결과의 Timeline을 열면 Bruno가 만든 실제 URL, 리디렉션, 스크립트 로그와 네트워크 순서를 확인할 수 있습니다. 변수 치환 뒤 주소가 예상과 같은지 먼저 봅니다.
문제를 공유할 때는 토큰, 쿠키와 개인정보를 가린 뒤 상태 코드와 재현 단계를 기록합니다. Send 직전의 환경 이름과 요청 파일도 함께 확인하면 다른 PC에서 같은 실패를 재현하기 쉽습니다.
완료 확인: 저장부터 Runner까지
샘플 Collection에 GET 요청을 저장하고 Environment의 baseUrl을 사용해 Send합니다. 2xx 상태, JSON 본문과 Test 통과를 확인한 뒤 Collection Runner에서 같은 요청을 실행합니다.
Bruno를 닫았다 다시 열어 Collection과 요청이 그대로 보이고 .bru 파일이 로컬 폴더에 남는지 확인합니다. Runner도 다시 통과하면 설치와 첫 API 테스트 작업이 끝납니다.
자주 묻는 질문
Bruno API Client는 무료인가요?
네. 기본 API Client는 무료 오픈소스로 배포됩니다.
Windows에서 어떤 파일을 받나요?
Intel·AMD PC는 x64 EXE, Arm PC는 Arm64 EXE를 받습니다.
Postman Collection을 가져올 수 있나요?
Import Collection에서 Postman 형식을 선택하고 가져온 뒤 인증과 스크립트를 검증합니다.
토큰을 컬렉션에 저장해도 되나요?
실제 토큰은 Secret 환경 변수로 분리하고 저장소에 평문으로 커밋하지 않습니다.
요청은 어디에 저장되나요?
Create Collection에서 고른 로컬 폴더에 .bru 파일로 저장됩니다.
Send와 Runner 결과까지 확인하세요
Collection을 다시 열어 GET 요청과 환경 변수가 남았는지 보고 Send와 Runner가 같은 테스트를 통과하는지 확인합니다.
공식 자료와 확인일
공식 다운로드 · 공식 API Client 소개 · 공식 설치 안내 · 공식 Collection 만들기 · 공식 Request 만들기 · 공식 Environment Variables · 공식 Collection Runner | 2026-10-01T05:32:52.826261+00:00
