HTTP API 테스트(.lnh)

파일 → 새로 만들기 → 새 API 테스트는 .lnh 파일로 저장되는 HTTP 클라이언트를 엽니다. 하나의 파일은 엔드포인트(메서드, URL, 헤더, 본문)를 나타내며 왼쪽 목록에 여러 테스트를 보관합니다 — 각 테스트는 URL, 헤더, 본문에서 사용하는 {name} 변수 값과 마지막 실행 결과(상태, 시간, 날짜, 응답 헤더와 본문)를 가집니다. 동등한 curl 명령도 함께 표시됩니다. 같은 일회성 작업은 CLI(http)와 MCP (http_request)에서도 사용할 수 있습니다. 테스터는 curl을 사용하며, curl은 Windows 10과 11에 기본으로 포함되어 있습니다. 없으면 LightNote가 보내기 전에 설치 가이드를 엽니다.

보내기와 응답 확인

Ctrl+Enter로 요청을 보냅니다. 응답이 돌아오기 전까지는 같은 버튼이 중지(또는 Esc)로 바뀌고 대기 시간이 초 단위로 표시됩니다. 응답 배지에는 상태와 시간이, 그 옆에는 형식, 크기, 테스트 실행 시각이 표시됩니다. curl 줄은 입력에 따라 바뀌며 선택한 테스트의 변수가 이미 치환되어 있습니다. 옆의 버튼은 명령을 복사하고, 화살표를 누르면 PowerShell, Python, JavaScript, C#, HTTPie용으로도 복사할 수 있습니다. curl 명령을 URL에 바로 붙여넣으면 테스트를 지우지 않고 메서드, 헤더, 본문을 가져옵니다.

테스트에 값이 없는 변수는 요청에 그대로 전송됩니다(URL에 {id}가 남고, 서버는 이유를 알 수 없는 오류를 반환합니다). 변수 탭이 해당 변수를 강조하고 이름을 알려 줍니다. 목록의 각 테스트 옆 점은 마지막 상태의 색이며, 빈 고리는 아직 실행하지 않은 테스트입니다. 응답에서는 본문 위의 막대로 JSON/XML을 화면에서만 서식 지정하고, 줄을 바꾸고, 본문을 복사하고, 받은 그대로 파일에 저장할 수 있습니다.

요청 만들기. 매개변수 탭은 URL의 쿼리를 목록으로 보여 줍니다. 행을 편집하면 URL이 바뀌고, URL을 편집하면 목록이 바뀝니다. 인증 탭은 헤더를 알아서 만들어 줍니다 — Basic, Bearer, API 키(헤더 또는 URL). 모든 칸에 {variable}을(를) 쓸 수 있으므로 비밀 값은 파일이 아닌 환경에 둘 수 있습니다. 헤더 탭에 같은 헤더가 이미 있으면 그것이 우선합니다. 본문에서는 유형으로 JSON, XML, SOAP, 양식, multipart(텍스트 필드와 파일) 또는 바이너리로 보내는 파일을 고르며, Content-Type을 직접 쓰지 않았으면 자동으로 붙습니다. 파일의 상대 경로는 .lnh 폴더를 기준으로 합니다. multipart나 파일일 때는 PowerShell과 JavaScript가 그 본문을 보낼 수 없으므로 복사 버튼의 화살표 메뉴에서 회색으로 표시됩니다. 옵션 탭에서는 제한 시간(기본 60초)을 바꾸고 리디렉션을 따라가게 할 수 있으며, 따라가지 않으면 3xx 응답 자체가 표시됩니다. 이전 버전의 LightNote에서 열면 파일은 인증과 유형 없이 전송되며, 다른 요청이 되지는 않습니다. 자체 인증서를 쓰는 로컬 서버라면 인증서 검증 안 함 (HTTPS)으로 검증을 끌 수 있습니다. 켜져 있는 동안 응답 줄에 인증서가 검증되지 않음이 표시되고, lnote http-run도 보고서에 적습니다.

응답 읽기. 본문은 읽기 전용 코드 편집기에서 열리며, 응답 유형에 따른 강조 표시, 접기, 창 검색(Ctrl+F)을 쓸 수 있습니다. 쿠키 탭은 서버가 저장하라고 보낸 것을 보여 주고, 타임라인은 실제로 나간 요청(curl이 직접 붙인 헤더 포함)과 응답의 원본 헤더를 보여 줍니다. 타임라인은 메모리에만 남습니다. Authorization이 들어 있고 파일은 Git에 들어가기 때문입니다.

검사

검사 탭은 테스트가 통과했는지 알려 줍니다. 각 행은 응답의 한 부분(상태, 헤더, 본문 전체, JSONPath($.user.id, $.items[0].name, $.items.length()), XPath(//Price, count(//Item)) 또는 밀리초 단위 시간)을 예상값과 비교합니다. 비교 방식은 같음, 다름, 큼, 작음, 포함, 정규식과 일치, 존재, 형식 일치입니다. XPath에서는 이름의 접두사를 무시하므로 soap:Envelope와 Envelope는 같은 단계입니다. 검사가 있으면 검사가 결과를 결정합니다. 예상한 404는 통과하고, 필드가 틀린 200은 실패합니다. 각 검사의 결과는 마지막 열에, 요약은 응답 배지 옆에 표시되며, 목록의 테스트 점은 녹색이나 빨간색이 됩니다. 행의 선택을 해제하면 파일에는 남지만 결과에는 포함되지 않습니다.

목록 위쪽의 재생 버튼은 파일의 모든 테스트를 하나씩 실행하고 몇 개가 통과했는지 알려 줍니다. 테스트를 두 번 실행하면 응답 본문 위의 비교 버튼으로 이전 실행과 현재 실행을 나란히 열 수 있으며, 양쪽 본문 모두 서식이 지정됩니다. 이전 실행만 저장됩니다. 파일은 Git에 들어가므로 긴 기록은 모든 차이를 채우게 됩니다.

환경, 캡처와 폴더 전체

환경은 JetBrains와 VS Code의 개방형 형식을 사용합니다. 폴더(또는 상위 폴더)의 http-client.env.json에 환경마다 객체를 하나씩 두고 ({"dev": {"host": "http://localhost:8080"}}), 그 옆의 http-client.private.env.json에는 Git에 넣지 않을 비밀 값을 둡니다. 같은 환경에서는 private 파일이 우선하며 $shared는 모든 환경에 적용됩니다. URL 옆의 선택기로 환경을 고르고, 가져오기/내보내기 메뉴에서 파일을 만들 수 있습니다. 변수는 테스트, 캡처, 환경 순으로 정해지며 변수 탭에 각각의 출처가 표시됩니다.

캡처 탭은 응답의 일부(로그인의 token, 방금 만든 리소스의 id 등)를 변수로 보관해 이 파일과 같은 폴더의 다른 파일의 다음 테스트에서 쓰게 합니다. 이렇게 로그인용 .lnh가 다른 파일의 인증된 호출에 값을 넘깁니다. 캡처한 값은 메모리에만 있고 파일에는 저장되지 않습니다.

폴더가 컬렉션입니다. lnote http-run --path <폴더> --env dev는 폴더의 모든 .lnh를 자연 순서(01-login이 02-profile보다 먼저)로 실행하고, 실패한 테스트가 있으면 오류로 끝나므로 CI에 쓸 수 있습니다. 같은 실행을 MCP의 http_test_run으로도 할 수 있어 AI 에이전트가 직접 작성한 테스트를 실행할 수 있습니다. 기본적으로 파일은 바뀌지 않으며, --save를 쓰면 각 테스트의 마지막 결과를 파일에 저장합니다.

가져오기와 내보내기

OpenAPI 가져오기와 내보내기. 테스트 목록 위쪽의 화살표 버튼에서 OpenAPI 가져오기…와 OpenAPI 내보내기…를 열 수 있습니다. 가져오기는 YAML 또는 JSON 명세를 읽으며, 현재 쓰이는 세 세대 — Swagger 2.0, OpenAPI 3.0, 3.1 — 를 모두 지원하고 테스트를 알아서 구성합니다. 경로의 {parameters}는 .lnh의 {name} 변수와 문법이 같아 그대로 쓰이고, 명세에 선언된 예시는 테스트 값이 되며, 보안 스킴은 Authorization 헤더가 되고, 선언된 서버마다 별도의 테스트가 만들어집니다(검증 환경과 운영 환경을 나란히). 한 .lnh 파일은 엔드포인트 하나를 담으므로, 작업이 여러 개인 명세는 어느 것을 가져올지 묻습니다. 또는 한 번에 전부 저장해 작업마다 .lnh 파일을 하나씩 만들 수도 있습니다.

내보내기는 그 반대 방향으로, 파일에서 OpenAPI 3.0.3 명세를 만듭니다. 서버·매개변수·본문은 템플릿에서, 예시 응답은 기록된 실행에서 나옵니다. 이는 뼈대이지 완전한 계약이 아닙니다 — .lnh는 호출을 기술하므로 타입, 설명, 스키마는 복원되지 않습니다. 테스트는 x-lightnote-tests 필드에 함께 담기므로 파일을 다시 가져오면 그대로 돌아옵니다.

curl 명령 가져오기. 같은 버튼의 curl 명령 가져오기…를 누르면 붙여 넣기 상자가 열립니다. 명령은 디스크가 아니라 거기에서 오며, 클립보드에 curl이 있으면 미리 채워집니다. 같은 명령이 유통되는 세 가지 방언을 이해합니다. Chrome/Firefox의 cURL로 복사(작은 따옴표), Windows의 Copy as cURL (cmd)(^ 사용), 그리고 \로 줄을 나눈 문서 예시입니다. 메서드는 -X에서 가져오며, 없으면 본문이 있을 때 POST, 없을 때 GET으로 판단합니다.

가져오기는 있는 그대로 이루어집니다. 어떤 값도 저절로 {name} 변수가 되지 않습니다. 어느 토큰이 비밀인지 추측하면 틀리기 때문입니다. 몇몇 경우에는 얼버무리지 않고 알려 줍니다. 파일에서 오는 본문(-d @파일)은 읽을 수 없고, 멀티파트 업로드(-F)도 그대로 재현되지 않으므로 해당 항목은 조정할 수 있도록 본문에 텍스트로 들어갑니다.

다른 도구에서 가져오기. 다른 도구에서 가져오기…는 .http/.rest 파일(VS Code의 REST Client, JetBrains, Visual Studio), Postman 컬렉션 또는 환경, Insomnia 내보내기(JSON의 v4 또는 YAML의 v5), 브라우저가 모두 HAR로 저장으로 저장한 HAR, Bruno의 .bru(또는 Bruno 폴더 가져오기…로 폴더 전체), SOAP 서비스의 WSDL을 읽습니다. 형식은 확장자가 아니라 내용으로 인식합니다. 요청은 각각 .lnh가 되고 컬렉션의 폴더는 폴더가 됩니다. 이 파일에 쓸 요청을 하나 고르거나 모두 한 번에 저장하세요. {{name}}은 {name}이 되고, 인증은 헤더가 되며, 환경은 http-client.env.json에 기록됩니다(원본에서 비밀로 표시한 값은 .private로). 이미 있던 값은 바꾸지 않습니다. Bruno의 검사와 캡처, 그리고 Postman의 pm.response.to.have.status는 여기서의 검사와 캡처가 됩니다. HAR에서는 API 호출과 페이지만 가져오고, 브라우저가 받은 응답을 마지막 실행으로 남깁니다. WSDL에서는 작업마다 SOAP 엔벨로프를 만들고 SOAPAction과 각 필드를 변수로 만듭니다.

해당하는 기능이 없는 부분은 그대로 두고 알려 줍니다. 요청 전후의 스크립트는 변환하지 않으며, 동적 변수({{$guid}})와 연결 참조는 그대로 남고, 변수가 든 Basic, multipart 본문, 파일 본문은 인증 탭과 본문의 유형으로 들어가며, 다른 컴퓨터에서 온 파일 경로는 확인할 수 있게 목록에 나옵니다. 컬렉션을 저장하면 이 보고서가 대상 폴더의 노트가 됩니다. .http로 내보내기…는 선택한 테스트로 반대 방향의 변환을 합니다. 템플릿은 {{name}}을 쓰고 값은 @name = 값으로 기록합니다.