InfoGrab DocsInfoGrab Docs

테스트 밸런싱 API

요약

이 기능의 가용성은 기능 플래그에 의해 제어됩니다. 이 API를 사용하여 parallel: CI/CD 잡의 노드에 테스트를 테스트 소요 시간에 따라 분배하며, 모든 노드가 거의 같은 시간에 끝나도록 합니다. 테스트 분할은 노드에 분배하는 작업 단위입니다.

히스토리
  • GitLab 19.4에서 parallel_test_balancing라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
Feature flag

이 기능의 가용성은 기능 플래그에 의해 제어됩니다. 자세한 내용은 기록을 참조합니다. 이 기능은 테스트에 사용할 수 있지만 프로덕션 환경에서 사용할 준비는 되지 않았습니다.

이 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
    }
  ]
}

테스트 밸런싱 API

GitLab v19.6
Tier: Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
원문 보기

요약

이 기능의 가용성은 기능 플래그에 의해 제어됩니다. 이 API를 사용하여 parallel: CI/CD 잡의 노드에 테스트를 테스트 소요 시간에 따라 분배하며, 모든 노드가 거의 같은 시간에 끝나도록 합니다. 테스트 분할은 노드에 분배하는 작업 단위입니다.

히스토리
  • GitLab 19.4에서 parallel_test_balancing라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
Feature flag

이 기능의 가용성은 기능 플래그에 의해 제어됩니다. 자세한 내용은 기록을 참조합니다. 이 기능은 테스트에 사용할 수 있지만 프로덕션 환경에서 사용할 준비는 되지 않았습니다.

이 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
    }
  ]
}