테스트 밸런싱 API
GitLab v19.6Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
이 기능의 가용성은 기능 플래그에 의해 제어됩니다. 이 API를 사용하여 parallel: CI/CD 잡의 노드에 테스트를 테스트 소요 시간에 따라 분배하며, 모든 노드가 거의 같은 시간에 끝나도록 합니다. 테스트 분할은 노드에 분배하는 작업 단위입니다.
이 기능의 가용성은 기능 플래그에 의해 제어됩니다. 자세한 내용은 기록을 참조합니다. 이 기능은 테스트에 사용할 수 있지만 프로덕션 환경에서 사용할 준비는 되지 않았습니다.
이 API를 사용하여 parallel: CI/CD 잡의 노드에 테스트를
테스트 소요 시간에 따라 분배하며, 모든 노드가 거의 같은 시간에 끝나도록 합니다.
테스트 분할은 노드에 분배하는 작업 단위입니다. 파일 단위로 분할하면 각 테스트 분할은 테스트 파일 하나입니다. 노드는 정적 테스트 분할로 공유 대기 풀을 채운 다음, 작업을 마칠 때마다 소요 시간 예산에 맞춘 테스트 분할 배치를 반복해서 요청합니다. 더 빠른 노드가 더 많은 작업을 맡습니다. 노드를 재시도하면 처음에 할당받았던 테스트 분할 집합을 그대로 받습니다.
두 엔드포인트 모두 다음과 같습니다.
- 실행 중인 병렬 잡에서 호출해야 하며, CI/CD 잡 토큰(
CI_JOB_TOKEN)으로 인증합니다. - 호출한 잡이
parallel:키워드를 사용하지 않으면422 Unprocessable Entity를 반환합니다. - 7일보다 오래 전에 생성된 파이프라인에는
422 Unprocessable Entity를 반환합니다. 재시도를 포함한 테스트 밸런싱 데이터를 파이프라인 생성 시점부터 7일 동안 보존하기 때문입니다.
병렬 잡의 테스트 밸런싱 초기화#
호출자의 정적 테스트 분할로 잡 그룹의 공유 대기 풀을 채우고 첫 번째
테스트 분할 배치를 가져갑니다. 노드가 이미 가져간 테스트 분할이 있으면(예: 잡을
재시도하거나 비정상 종료에서 복구한 경우), 이전에 가져간 테스트 집합을 그대로 반환하며
test_splits 매개변수는 무시합니다.
시드로 인해 잡 그룹의 공유 풀이 테스트 분할 50,000개를 초과하게 되면
이 엔드포인트는 422 Unprocessable Entity를 반환합니다.
POST /job/test_balancing/initialize
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
test_splits |
array of hashes | 예 | 이 노드에 할당된 정적 분할의 테스트 분할입니다. 최대 1,000개 항목입니다. |
test_splits[].path |
string | 예 | 리포지터리 루트를 기준으로 한 테스트 분할의 경로입니다. 최대 1024자입니다. |
test_splits[].expected_duration |
float | 아니요 | 테스트 분할의 예상 소요 시간(초)입니다. 지정하지 않으면 기본값은 300입니다. |
성공하면 201 Created와 다음
응답 속성을 반환합니다.
| 속성 | 유형 | 설명 |
|---|---|---|
mode |
string | 풀을 채우고 첫 번째 배치를 가져갔으면 seed, 이전에 가져간 테스트 집합을 다시 반환했으면 retry입니다. |
test_splits |
array | 노드가 실행해야 하는 테스트 분할입니다. retry에서는 처음의 전체 테스트 집합입니다. |
test_splits[].path |
string | 리포지터리 루트를 기준으로 한 테스트 분할의 경로입니다. |
test_splits[].expected_duration |
float | 시드 시점의 예상 소요 시간(초)입니다. 지정하지 않으면 기본값은 300입니다. |
요청 예시:
curl --request POST \
--header "JOB-TOKEN: $CI_JOB_TOKEN" \
--header "Content-Type: application/json" \
--data '{"test_splits": [{"path": "spec/models/user_spec.rb", "expected_duration": 12.5}]}' \
--url "https://gitlab.example.com/api/v4/job/test_balancing/initialize"
응답 예시:
{
"mode": "seed",
"test_splits": [
{
"path": "spec/models/user_spec.rb",
"expected_duration": 12.5
}
]
}
다음 테스트 배치 요청#
호출한 노드를 위해 소요 시간 예산에 맞춘 대기 중인 테스트 분할 배치를 가장 느린 것부터 원자적으로
가져갑니다. test_splits 배열이 비어 있으면 큐가 소진된 것이므로 노드는 배치 요청을
중단해야 합니다.
서버는 공유 풀에 남은 예상 소요 시간의 합계에 따라 배치 크기를 자동으로 선택합니다. 남은 소요 시간이 많으면 서버는 요청 횟수를 줄이기 위해 더 큰 배치를 반환합니다. 풀이 줄어들수록 서버는 노드 간에 작업이 균형을 유지하도록 더 작은 배치를 반환합니다.
시간 초과 후처럼 요청을 안전하게 재시도하려면 같은 run_id와 seq를 다시 보냅니다.
- 서버가 해당 요청에 대해 이미 배치를 가져갔다면, 새 배치를 가져가는 대신 같은 배치를 반환합니다.
- 서버가 같은
run_id에 대해 더 높은seq의 요청을 이미 받았다면, 빈test_splits배열을 반환하고 테스트 분할을 가져가지 않습니다.
POST /job/test_balancing/request
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
run_id |
string | 아니요 | 요청을 보내는 프로세스에 대해 클라이언트가 생성한 ID입니다. 프로세스의 모든 요청에 같은 값을 사용합니다. seq와 함께 필요합니다. 최대 64자입니다. |
seq |
integer | 아니요 | 실행에서 요청의 순번입니다. 새 요청마다 값을 늘리고, 해당 요청을 재시도할 때만 같은 값을 다시 사용합니다. run_id와 함께 필요합니다. 최소 1입니다. |
성공하면 201 Created와 다음
응답 속성을 반환합니다.
| 속성 | 유형 | 설명 |
|---|---|---|
test_splits |
array | 노드가 실행해야 하는 테스트 분할입니다. 큐가 소진되면 비어 있습니다. |
test_splits[].path |
string | 리포지터리 루트를 기준으로 한 테스트 분할의 경로입니다. |
test_splits[].expected_duration |
float | 시드 시점의 예상 소요 시간(초)입니다. 지정하지 않으면 기본값은 300입니다. |
요청 예시:
curl --request POST \
--header "JOB-TOKEN: $CI_JOB_TOKEN" \
--header "Content-Type: application/json" \
--data '{"run_id": "3f2b8c1e-6d4a-4f0b-9a7e-2c5d8e1f4a6b", "seq": 1}' \
--url "https://gitlab.example.com/api/v4/job/test_balancing/request"
응답 예시:
{
"test_splits": [
{
"path": "spec/features/login_spec.rb",
"expected_duration": 210.4
}
]
}