Gửi HTTP request

Gọi HTTP API từ flow để chuẩn bị dữ liệu test hoặc kiểm tra trạng thái backend.

maestro-runner có sẵn HTTP client JavaScript, nên bạn có thể gọi API bên ngoài trực tiếp từ flow. Điều này hữu ích để chuẩn bị dữ liệu test, xác thực người dùng, hoặc kiểm tra trạng thái backend mà không cần đi qua UI.

Gửi request

Dùng các phương thức viết tắt cho request chuẩn:

• http.get(url, options)
• http.post(url, options)
• http.put(url, options)
• http.delete(url, options)

Với các phương thức khác (như PATCH), dùng hàm request tổng quát. Trong maestro-runner, HTTP method là đối số đầu tiên:

const response = http.request('PATCH', 'https://example.com', {
    body: JSON.stringify({ status: "active" })
});

Lưu ý: khác với Maestro

Maestro ghi http.request(url, { method: "PATCH" }). Dạng này không chạy trong maestro-runner, vốn mong đợi http.request(method, url, options).

Làm việc với JSON

Hàm global json() phân tích chuỗi JSON thành đối tượng JavaScript. Một response thành công có body là đối tượng JSON cũng cung cấp nó qua response.json.

Ví dụ, giả sử https://api.example.com/user/1 trả về:

{
  "id": 1,
  "email": "user@example.com",
  "profile": {
    "name": "Jane Doe",
    "age": 32
  }
}

Bạn có thể phân tích body của response và truy cập trực tiếp các trường:

// script.js
const response = http.get('https://api.example.com/user/1');

// Phân tích body và truy cập trực tiếp các trường
const userData = json(response.body);
output.username = userData.profile.name;

Trong ví dụ này, tên người dùng được đọc từ profile.name và gán cho output.username.

Option của request

Đối số thứ hai là một đối tượng options. Các key sau được hỗ trợ:

Option	Kiểu	Mô tả
headers	Object	Header của request, như token xác thực.
body	String hoặc Object	Payload. Một object thuần được gửi dưới dạng JSON với Content-Type: application/json.
timeout	Number	Timeout tính bằng mili giây. Mặc định là 30000.
insecure	Boolean	Bỏ qua xác minh chứng chỉ TLS, ví dụ với server staging dùng chứng chỉ tự ký.

Header

const response = http.get('https://example.com', {
    headers: {
        'Authorization': 'Bearer ' + output.token,
        'Content-Type': 'application/json'
    }
});

Body của request

Với request POST, PUT hoặc PATCH, cung cấp payload trong body. Hãy tự stringify các object JSON để body đúng như bạn mong đợi:

const response = http.post('https://example.com/login', {
    body: JSON.stringify({
        username: "test_user",
        password: "password123"
    })
});

Lưu ý: không hỗ trợ upload multipart

Option multipartForm của Maestro (upload file) không có trong maestro-runner. Nếu truyền vào, nó bị bỏ qua. Hãy upload qua UI của chính app, hoặc qua các endpoint test của backend với body JSON.

Đối tượng response

Mỗi lời gọi HTTP trả về một đối tượng response với các trường sau:

Tên trường	Kiểu	Mô tả
ok	Boolean	true nếu request thành công (status 200-299).
status	Number	Mã trạng thái HTTP (ví dụ 200, 404).
body	String	Body thô của response dưới dạng chuỗi.
headers	Object	Header của HTTP response.
json	Object hoặc null	Body đã phân tích khi nó là một đối tượng JSON, ngược lại là null.

Ví dụ sử dụng

Mẫu thường gặp là dùng API để tạo sẵn dữ liệu test trước khi thực hiện tương tác UI. Cách này đảm bảo dữ liệu bạn cần đã có mà không cần các step thiết lập UI chậm và flaky.

Trong ví dụ này, một script tạo lịch hẹn mới bằng request POST và lưu appointmentTitle vào đối tượng output cho flow chính.

// create_appointment.js
const response = http.post('https://my-api.com/v1/appointments', {
    body: JSON.stringify({
        title: "Maestro Health Check",
        date: "2026-02-10"
    }),
    headers: { 'Content-Type': 'application/json' }
});

const data = json(response.body);

// Lưu tiêu đề ở phạm vi global để flow có thể assert trên đó
output.appointmentTitle = data.title;

Sau khi script đã chạy, các giá trị đã lưu có thể dùng ở bất kỳ step nào sau đó trong flow:

# flow.yaml
appId: com.example.app
---
- launchApp
- runScript: create_appointment.js
- tapOn: "My Appointments"
# Kiểm tra dữ liệu vừa tạo qua API giờ đã hiển thị trên UI
- assertVisible: ${output.appointmentTitle}

Step tiếp theo

Tìm hiểu cách tạo dữ liệu test giả lập khi chạy, giúp test linh hoạt hơn và ít phụ thuộc vào giá trị hardcode.