Công cụ kiểm thử API Headless: Chạy kiểm thử API không giao diện, trong CI

Một công cụ kiểm thử API không giao diện chạy test từ dòng lệnh thay vì yêu cầu mở GUI, nhấp chuột và thao tác thủ công. Cách tiếp cận này giúp bạn chạy cùng một bộ kiểm thử trên laptop, server build và pipeline CI/CD. Bài viết này giải thích “headless” trong kiểm thử API là gì, cách chạy test bằng Apidog CLI, và khi nào nên dùng Newman, Hurl hoặc Hoppscotch CLI.

Dùng thử Apidog ngay hôm nay

“Headless” nghĩa là gì trong kiểm thử API?

“Headless” nghĩa là công cụ chạy mà không cần giao diện đồ họa. Với kiểm thử API, một công cụ headless thường có các đặc điểm sau:

• Chạy bằng CLI, ví dụ trong terminal, script hoặc CI job.
• Không cần màn hình, phiên đăng nhập GUI hoặc thao tác click thủ công.
• Đọc test từ file, collection, project ID hoặc test suite.
• Trả về exit code khác 0 khi test fail để CI đánh dấu build lỗi.
• Xuất báo cáo cho cả người đọc và máy đọc được, ví dụ cli, json, html, junit.

Điểm quan trọng nhất là exit code và report. GUI giúp một người xem kết quả. Công cụ headless giúp pipeline quyết định có cho merge, deploy hoặc rollback hay không. Nếu bạn đang đưa API test vào CI/CD, hãy xem thêm các thực hành tốt nhất về CI/CD cho kiểm thử API.

Khi nào nên chuyển test API ra khỏi GUI?

GUI rất hữu ích khi bạn cần:

• Khám phá endpoint mới.
• Thử header, auth, body và response.
• Debug nhanh một request.
• Tạo assertion trực quan.

Nhưng GUI không phù hợp cho các việc cần lặp lại:

• Chạy lại hàng chục request sau mỗi commit.
• Chặn PR nếu API regression.
• Tự động kiểm thử trước khi deploy.
• Chạy test lúc không có người thao tác.

Với runner headless, bạn có thể đưa test vào một lệnh cố định:

api-test-runner run <test-source>

Sau đó dùng cùng một lệnh trên:

• Máy local của developer.
• Máy của QA.
• GitHub Actions, GitLab CI, Jenkins hoặc các CI server khác.
• Pipeline deploy staging/production.

Cách làm này giúp test API trở thành một phần của workflow phát triển, không phải một bước kiểm tra thủ công sau cùng. Đây cũng là một phần của tư duy xem API như một sản phẩm.

Apidog CLI: chạy test API không giao diện từ project Apidog

Apidog CLI là runner dòng lệnh của Apidog. Bạn có thể thiết kế, debug và tổ chức test trong ứng dụng Apidog, sau đó chạy test bằng lệnh:

apidog run <test-source>

apidog run có thể chạy scenario, folder, test suite hoặc file export cục bộ. Khi chạy xong, CLI in kết quả, tạo report và trả về exit code để CI xử lý.

1. Cài Apidog CLI

Một bước cài đặt tối thiểu:

npm install -g apidog-cli

Kiểm tra CLI đã sẵn sàng:

apidog --version

2. Chạy một test suite từ terminal

Ví dụ chạy test từ URL hoặc nguồn test được Apidog cung cấp:

apidog run https://api.apidog.com/... \
  -e <environment-id> \
  -r cli,html,junit

Trong đó:

• -e <environment-id> chọn môi trường chạy.
• -r cli,html,junit xuất nhiều loại report cùng lúc.
• Exit code khác 0 cho biết test fail.

Theo mặc định, report HTML và JUnit được tạo trong thư mục:

apidog-reports/

CI có thể thu thập thư mục này làm build artifact hoặc test report.

3. Chạy test dựa trên dữ liệu CSV/JSON

Nếu một scenario cần chạy với nhiều input khác nhau, dùng data-driven testing:

apidog run https://api.apidog.com/... \
  -e <environment-id> \
  -d ./data/users.csv \
  -n 20 \
  -r cli,html,junit

Các flag chính:

• -d, --iteration-data <path>: file CSV hoặc JSON chứa dữ liệu lặp.
• -n, --iteration-count: giới hạn số vòng lặp.

Ví dụ users.csv:

email,password,expectedStatus
[e-mail],secret123,200
[e-mail],wrong-password,401
invalid-email,secret123,400

Một scenario có thể được chạy nhiều lần với từng dòng dữ liệu. Chi tiết hơn có trong hướng dẫn kiểm thử API dựa trên dữ liệu với Apidog CLI.

4. Truyền biến môi trường trong CI

Không nên commit secret vào repository. Thay vào đó, truyền biến lúc chạy:

apidog run https://api.apidog.com/... \
  -e <environment-id> \
  --env-var baseUrl=https://staging.example.com \
  --env-var token=$API_TOKEN \
  -r cli,junit

Bạn cũng có thể dùng:

--global-var key=value

Cách này phù hợp khi CI đã lưu token, API key hoặc base URL trong secret manager.

5. Ví dụ GitHub Actions tối thiểu

name: API Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  api-tests:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API tests
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: |
          apidog run https://api.apidog.com/... \
            -e <environment-id> \
            --env-var token=$API_TOKEN \
            -d ./data/users.csv \
            -r cli,html,junit

      - name: Upload reports
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: apidog-reports
          path: apidog-reports/

Nếu test fail, lệnh apidog run trả về exit code lỗi và job sẽ fail.

Để đi từ cài đặt đến lần chạy đầu tiên, xem hướng dẫn đầy đủ về Apidog CLI. Nếu bạn muốn test một REST endpoint cụ thể từ dòng lệnh, xem hướng dẫn dòng lệnh API REST. Danh sách tùy chọn chi tiết nằm trong tài liệu tham khảo lệnh apidog run.

Một workflow headless khác: Apidog MCP

Ngoài CLI, Apidog còn có Apidog MCP server. MCP cho phép AI agent hoặc IDE hỗ trợ AI như Cursor, hoặc VS Code qua Cline, đọc trực tiếp đặc tả API của bạn.

Use case thực tế:

• IDE đọc contract API thật.
• Trợ lý AI tạo code dựa trên spec thay vì đoán endpoint.
• Test hoặc client code được sinh theo contract hiện có.

Đây cũng là một dạng “không GUI”: agent dùng API spec làm nguồn dữ liệu để thao tác. Quy trình này được mô tả thêm trong bài gỡ lỗi trực quan với máy khách Apidog MCP.

Các runner headless khác đáng biết

Apidog không phải lựa chọn duy nhất. Công cụ phù hợp phụ thuộc vào nơi test của bạn đang tồn tại.

Newman

Newman là runner dòng lệnh cho Postman collection. Nếu team đã có nhiều Postman collection, Newman thường là lựa chọn ít ma sát nhất.

Ví dụ:

newman run collection.json \
  -e environment.json \
  -d data.csv \
  -r cli,json,junit

Newman hỗ trợ các reporter tích hợp như:

• cli
• json
• junit
• progress
• emojitrain

Reporter HTML có thể cài thêm qua npm package riêng.

Hurl

Hurl dùng file văn bản thuần túy .hurl. Bạn viết request và assertion ngay trong file.

Ví dụ đơn giản:

GET https://api.example.com/users/1
HTTP 200
[Asserts]
jsonpath "$.id" == 1
jsonpath "$.email" exists

Chạy từ terminal:

hurl test.hurl

Hurl phù hợp nếu bạn muốn:

• Test nằm trong plain text.
• Dễ review trong Git diff.
• Không phụ thuộc vào GUI hoặc project workspace.
• Chạy nhanh trong CI nhờ binary nhỏ.

Hoppscotch CLI

Hoppscotch CLI, hay hopp, chạy Hoppscotch collection và test script trong CI.

Bạn có thể:

• Truyền collection và environment đã export dạng JSON.
• Tham chiếu collection/environment bằng ID và access token.
• Dùng CSV cho iteration data.
• Xuất JUnit report qua --reporter-junit.

Ví dụ khái quát:

hopp test collection.json \
  --env environment.json \
  --iteration-data data.csv \
  --reporter-junit

Nếu team đã dùng Hoppscotch, CLI của nó là lựa chọn tự nhiên. Nếu đang so sánh, xem thêm bài các lựa chọn thay thế Hoppscotch CLI tốt nhất.

So sánh nhanh các runner headless

Công cụ	Nguồn kiểm thử	Đầu vào dựa trên dữ liệu	Trình báo cáo tích hợp	Tốt nhất khi
Apidog CLI	Dự án, bộ kiểm thử Apidog hoặc tệp đã xuất	CSV / JSON (-d)	cli, html, json, junit	Bạn muốn thiết kế, mock, kiểm thử và tài liệu ở một nơi
Newman	Các collection Postman	CSV / JSON (-d)	cli, json, junit, progress (HTML qua tiện ích bổ sung)	Các collection Postman là nguồn chân lý của bạn
Hurl	Các tệp .hurl văn bản thuần túy	CSV qua các tùy chọn trình chạy	Báo cáo JUnit, TAP, JSON	Bạn thích các bài kiểm thử văn bản thuần túy, được kiểm soát phiên bản
Hoppscotch CLI	Các collection Hoppscotch (tệp hoặc ID)	CSV (--iteration-data)	JUnit	Nhóm của bạn đã sử dụng Hoppscotch

Cả bốn đều là runner headless đúng nghĩa: chạy bằng lệnh, không cần GUI, và báo hiệu thành công/thất bại bằng exit code.

Khác biệt chính nằm ở nguồn chân lý:

• Nếu test nằm trong Postman collection, dùng Newman.
• Nếu test nằm trong file text, dùng Hurl.
• Nếu test nằm trong Hoppscotch, dùng Hoppscotch CLI.
• Nếu bạn muốn contract, mock, test và docs nằm trong cùng một project, dùng Apidog CLI.

Cách chọn công cụ phù hợp

Bạn có thể chọn theo checklist sau.

Chọn Newman nếu

• Team đã dùng Postman lâu dài.
• Collection Postman là nguồn test chính.
• Bạn chỉ cần đưa collection hiện có vào CI.

Chọn Hurl nếu

• Bạn thích test dạng text file.
• Muốn review test bằng Git diff.
• Không cần GUI để quản lý test.
• Muốn cú pháp gần với HTTP request/response.

Chọn Hoppscotch CLI nếu

• Team đang dùng Hoppscotch.
• Collection và environment đã nằm trong hệ sinh thái Hoppscotch.
• Bạn muốn runner tương thích trực tiếp với workflow hiện có.

Chọn Apidog CLI nếu

• Bạn muốn thiết kế API, mock, test và tài liệu trong cùng một nơi.
• Bạn cần chạy cùng test cả trong GUI lẫn CI.
• Bạn muốn dùng data-driven testing bằng CSV/JSON.
• Bạn muốn report cli, html, json, junit.
• Bạn muốn giảm rủi ro contract API và test bị lệch nhau.

Lợi ích chính của Apidog không phải chỉ là “chạy được trong CI” — Newman, Hurl và Hoppscotch CLI cũng làm được. Điểm khác biệt là cùng một project có thể chứa contract, mock, test và docs, giúp giảm việc đồng bộ thủ công giữa nhiều công cụ.

Câu hỏi thường gặp

Công cụ kiểm thử API headless có giống công cụ kiểm thử API CLI không?

Trong thực tế, gần như giống nhau.

“Headless” mô tả việc công cụ không cần GUI. “CLI” mô tả cách bạn điều khiển công cụ qua dòng lệnh. Một công cụ kiểm thử API headless thường là CLI runner, có thể chạy tự động và trả về trạng thái pass/fail cho pipeline.

Có thể chạy các công cụ này mà không viết test script thủ công không?

Có, tùy công cụ.

Với Apidog, bạn có thể tạo assertion trực quan trong ứng dụng rồi chạy cùng scenario đó bằng CLI. Newman và Hoppscotch CLI chạy collection có thể chứa script được viết trong ứng dụng tương ứng. Hurl thì yêu cầu bạn viết test trong file .hurl.

Nếu bạn muốn workflow trực quan trước, headless sau, xem hướng dẫn đầy đủ về Apidog CLI.

Test API headless có cần backend thật không?

Không phải lúc nào cũng cần.

Bạn có thể trỏ test vào:

• Backend local.
• Staging environment.
• Production-like environment.
• Mock server.

Mock server hữu ích khi frontend hoặc integration team cần test contract trước khi backend hoàn thành. Máy chủ mock của Apidog có thể chạy trong CI cho mục đích này.

Runner headless nào tốt nhất cho CI/CD?

Không có một lựa chọn tốt nhất cho mọi team. Công cụ tốt nhất là công cụ chạy được test hiện có với ít thay đổi nhất.

• Postman collection: Newman.
• Hoppscotch collection: Hoppscotch CLI.
• Plain text HTTP test: Hurl.
• Contract, mock, test và docs trong một project: Apidog CLI.

Nếu bạn cần so sánh sâu hơn, xem Apidog CLI so với Newman và Apidog CLI so với Postman CLI.

Tổng kết

Một công cụ kiểm thử API headless là runner không cần cửa sổ GUI: bạn chạy bằng lệnh, truyền dữ liệu, xuất report và để CI quyết định pass/fail. Newman, Hurl và Hoppscotch CLI đều phù hợp trong hệ sinh thái riêng của chúng. Apidog CLI cũng làm được điều đó, đồng thời giữ test, mock, contract và tài liệu trong cùng một project. Tải Apidog để thiết kế scenario một lần và chạy headless ở mọi nơi.