Kiểm thử Jenkinsfile

Một Jenkinsfile là code chạy qua parser Declarative, Groovy/CPS, plugin, controller, agent và policy bảo mật. Vì vậy một tầng test duy nhất không đủ: lint cho phản hồi cấu trúc sớm, mock unit test kiểm tra flow, contract bảo vệ consumer, còn controller lab mới cho bằng chứng runtime. Những lớp này bổ sung nhau; không lớp nào tự chứng minh build ứng dụng sẽ pass hoặc Pipeline an toàn.

Mục lụcCopy Anchor Link

• Mô hình kiểm thử Pipeline
  • Pyramid và luồng gate
  • Bảng quyết định
• Declarative linter
  • Linter chứng minh gì và không chứng minh gì
  • UI CLI và HTTP endpoint
  • Xác thực crumb và gate pull request
• Unit test Pipeline không side effect
  • Mock step context và đường đi
  • Ví dụ với JenkinsPipelineUnit
  • Giới hạn của mock
• Kiểm thử Shared Library
  • Chia bề mặt vars src resources
  • Trust contract pin và CPS
• Sandbox runtime và controller test
  • Thiết kế môi trường disposable
  • Integration JenkinsRule và acceptance test
• CI gate và checklist
• Lab local an toàn
  • Tạo fixture Jenkinsfile vô hại
  • Validate trên sandbox loopback có giới hạn
  • Dọn fixture có guard
• Khắc phục sự cố
• Nguồn tham khảo
• Đọc tiếp

Mô hình kiểm thử PipelineCopy Anchor Link

Pyramid và luồng gateCopy Anchor Link

Pyramid dưới đây áp dụng cho mã điều phối Jenkins. Đáy chạy nhiều và nhanh; càng lên cao càng gần controller thật, đắt hơn và cần ít case đại diện hơn.

direction: up
A: "Lint Declarative\ncú pháp và cấu trúc" {
  style.fill: "#2563eb"
  style.font-color: "#fff"
}
B: "Unit Pipeline / Shared Library\nmock step, branch, error, retry" {
  style.fill: "#0f766e"
  style.font-color: "#fff"
}
C: "Contract consumer\nAPI + revision đã pin" {
  style.fill: "#7c3aed"
  style.font-color: "#fff"
}
D: "Integration controller lab\nplugin, sandbox, CPS, agent" {
  style.fill: "#b45309"
  style.font-color: "#fff"
}
E: "ATH / smoke runtime\nluồng UI hoặc controller thật" {
  style.fill: "#b91c1c"
  style.font-color: "#fff"
}

A -> B
B -> C
C -> D
D -> E

Luồng áp dụng cho một pull request (PR) nên đi từ trái sang phải: lint và unit là required check nhanh; contract chạy trên revision library mà consumer pin; integration/acceptance chạy ở lane lab được kiểm soát. Một lỗi lint không cần chờ controller; một lỗi CPS, sandbox hay plugin không được kết luận là không tồn tại chỉ vì unit test xanh.

Bảng quyết địnhCopy Anchor Link

Chọn ít case đại diện ở tầng runtime: một Jenkinsfile hợp lệ, một đường lỗi có chủ đích, một library revision đã pin và một restart khi code đi qua checkpoint. Đừng dùng acceptance test để thay thế hàng chục unit test thuần.

Declarative linterCopy Anchor Link

Linter chứng minh gì và không chứng minh gìCopy Anchor Link

Declarative linter do plugin Pipeline: Declarative (Pipeline Model Definition) cung cấp để Jenkins parse và model-validate một Declarative Jenkinsfile trước khi thực thi đầy đủ. Nó phù hợp để phát hiện agent, stages, directive hoặc nesting sai vị trí.

Linter chỉ dành cho Declarative Pipeline; Scripted Pipeline và logic Groovy động cần unit/integration test khác. Cú pháp hợp lệ cũng phụ thuộc version Jenkins và Pipeline: Declarative đang cài. Ghi core/plugin version trong evidence khi một lỗi chỉ tái hiện ở một lane.

UI CLI và HTTP endpointCopy Anchor Link

Trước khi tích hợp, kiểm tra controller lab có Jenkins core được hỗ trợ, plugin Pipeline: Declarative, endpoint/CLI được quản trị viên cho phép và đường truyền TLS. Pipeline Syntax cùng Declarative Directive Generator trong UI giúp đối chiếu step/directive với chính instance; chúng không thay linter hay runtime build.

Endpoint HTTP của plugin Pipeline Model Definition nhận form field tên chính xác jenkinsfile, không phải JSON body và không phải endpoint CLI. Mẫu sau là non-executable cho tới khi controller sandbox đã xác minh plugin, URL context path, TLS, auth và CSRF behavior. JENKINS_AUTH_FILE là file netrc do secret manager provision ngoài repository, mode 0600; token/password không nằm trong URL, argv hay log. Nó chỉ gửi fixture không có secret:

# Prerequisite: JENKINS_URL là HTTPS URL của controller sandbox;
# JENKINS_AUTH_FILE là netrc file mode 0600 do secret manager provision.
set -eu
: "${JENKINS_URL:?Đặt HTTPS URL controller sandbox}"
: "${JENKINS_AUTH_FILE:?Đặt path netrc ngoài repository}"
: "${JENKINSFILE_PATH:?Đặt path tới Jenkinsfile không chứa secret}"
test -r "$JENKINS_AUTH_FILE"
test -r "$JENKINSFILE_PATH"

curl --fail-with-body --silent --show-error \
  --netrc-file "$JENKINS_AUTH_FILE" \
  --form "jenkinsfile=<${JENKINSFILE_PATH}" \
  "$JENKINS_URL/pipeline-model-converter/validate"

Mẫu sau là non-executable nếu chưa có controller lab, SSH CLI được bật, port SSH, hostname và account được cấp theo policy. Nó chỉ gửi nội dung Jenkinsfile qua stdin; không có credential trong lệnh.

# Prerequisite: controller lab đã bật Jenkins SSH CLI; user, hostname và port do lab công bố.
# Non-executable cho tới khi các biến và quyền SSH CLI được provision ngoài repository.
set -eu
: "${JENKINS_SSH_USER:?Đặt user SSH được cấp cho controller lab}"
: "${JENKINS_HOST:?Đặt hostname controller lab}"
: "${JENKINS_SSH_PORT:?Đặt port SSH CLI controller lab}"
ssh -l "$JENKINS_SSH_USER" -p "$JENKINS_SSH_PORT" \
  "$JENKINS_HOST" declarative-linter < Jenkinsfile

Kết quả thành công thường chứa Jenkinsfile successfully validated.; hãy lưu exit status và version controller/plugin cùng PR check. Không hard-code host production, không tắt TLS/CSRF, và không thêm quyền administrator chỉ để linter đi qua.

Xác thực crumb và gate pull requestCopy Anchor Link

HTTP linter là request POST tới /pipeline-model-converter/validate, với multipart form field jenkinsfile. Client dùng browser session/password có thể cần CSRF crumb lấy từ cùng controller/session. Jenkins core hiện đại thường miễn crumb cho request xác thực bằng API token, nhưng đây không phải cam kết phổ quát cho plugin endpoint, reverse proxy, security realm hay version khác. Xác minh request thật trên sandbox; đừng tắt CSRF khi gặp 403.

• Dùng service identity riêng, quyền tối thiểu và credential được quản trị ngoài Git. API token xác thực identity; permission mới quyết định endpoint được gọi.
• Không đặt token/password trong URL, argv, Jenkinsfile, log, artifact hay report. Không in response body có thể phản chiếu nội dung Pipeline.
• Với session/password flow, lấy crumbRequestField và crumb từ crumb issuer bằng cùng URL/cookie session; gửi lại field runtime đó cho POST bằng client có thể giữ cookie/header ngoài log. Không hard-code tên header, không ghi crumb/cookie vào command history hay process arguments.
• Với API-token flow, chỉ bỏ crumb khi chính controller sandbox xác nhận endpoint này chấp nhận request đó. 401/403 cần được phân biệt giữa identity permission, session/crumb, URL canonical, context path và proxy.

Gate PR tối thiểu: checkout Jenkinsfile ở revision PR → linter Declarative nếu file dùng pipeline {} → fail check khi parser/model báo lỗi → unit/contract lanes. Linter pass không được là điều kiện duy nhất để merge hoặc cấp credential cho build PR.

Unit test Pipeline không side effectCopy Anchor Link

Unit test Pipeline chạy Jenkinsfile/library trong một framework mô phỏng Pipeline DSL. JenkinsPipelineUnit là dự án bên thứ ba phổ biến; có thể dùng framework tương thích nếu nó cung cấp mock và assertion tương đương. Không gọi framework đó là Jenkins core hay tài liệu chính thức.

Mock step context và đường điCopy Anchor Link

Mock phải mô tả một contract nhỏ, không mô phỏng cả Jenkins. Test các đường đi có policy:

• parameter hợp lệ/không hợp lệ, when hoặc branch main/feature;
• exception và exit status của step bắt buộc; lỗi phải tiếp tục làm test fail;
• retry bao đúng thao tác idempotent và số attempt hữu hạn;
• withEnv/environment được thiết lập trong scope mong muốn;
• sh, checkout, HTTP, deploy, credential binding hay gọi external service đều bị mock/stub — không thực hiện side effect thật.

Ví dụ Jenkinsfile Scripted dưới chỉ chọn một check từ allowlist và gọi sh bằng chuỗi cố định. Đây là fixture unit test, không phải lệnh production:

// vars/runCheck.groovy hoặc fixture Pipeline

def call(String requested = 'unit') {
  def commands = [
    unit: 'printf "unit check\\n"',
    lint: 'printf "lint check\\n"'
  ]
  def command = commands[requested]
  if (command == null) {
    error("Unsupported check: ${requested}")
  }
  withEnv(["CHECK_NAME=${requested}"]) {
    sh command
  }
}

Ví dụ với JenkinsPipelineUnitCopy Anchor Link

Mẫu test dưới là non-executable cho đến khi repository test đã thêm JenkinsPipelineUnit, Groovy/JUnit tương thích và API framework đúng version đã pin. Nó đăng ký mock cho withEnv và sh; callback không mở shell thật. Tên helper có thể thay đổi theo version framework, nên đối chiếu README/API của version pin trước khi chép vào dự án.

import com.lesfurets.jenkins.unit.BasePipelineTest
import org.junit.Before
import org.junit.Test

class RunCheckTest extends BasePipelineTest {
  List<String> seen = []

  @Before
  void setUp() {
    super.setUp()
    helper.registerAllowedMethod('withEnv', [List, Closure]) { List env, Closure body ->
      seen.add("env=${env.join(',')}")
      body.call()
    }
    helper.registerAllowedMethod('sh', [String]) { String command ->
      seen.add("sh=${command}")
      null
    }
  }

  @Test
  void unit_check_uses_scoped_environment_and_no_real_shell() {
    def script = loadScript('vars/runCheck.groovy')
    script.call('unit')

    assert seen == [
      'env=CHECK_NAME=unit',
      'sh=printf "unit check\\n"'
    ]
  }

  @Test(expected = Exception)
  void unsupported_check_fails_before_a_shell_call() {
    def script = loadScript('vars/runCheck.groovy')
    script.call('deploy')
  }
}

Thêm test riêng cho retry bằng mock đếm attempt và cho đường lỗi bằng mock sh ném exception. Với parameter hoặc branch, đặt binding.params/binding.env theo API framework rồi assert stage/step tương ứng. Không dùng retry thực để biến assertion lỗi thành xanh; test phải lưu được lần gọi và lỗi ban đầu.

Giới hạn của mockCopy Anchor Link

Mock unit test không thay thế một Jenkins controller:

Không cho test process gọi production/external service để “tăng độ thật”. Nếu cần HTTP contract, chạy một fake server loopback trong harness hoặc một endpoint sandbox allowlist ở integration lane, có timeout và teardown theo build scope.

Kiểm thử Shared LibraryCopy Anchor Link

Chia bề mặt vars src resourcesCopy Anchor Link

Tách test theo cấu trúc library giúp test nhanh và làm ranh giới capability rõ ràng:

Ví dụ src nên là class Serializable đơn giản, chỉ trả data primitive/List/Map qua checkpoint. vars gọi Pipeline step từ context hợp lệ, còn src không giữ steps, stream, socket, iterator, client SDK hay object Jenkins qua echo, sh, input hoặc sleep.

Trust contract pin và CPSCopy Anchor Link

Đặt contract giữa library và consumer thành test cases có version:

1. API contract: Consumer gọi safeBuild(checks: ['unit']) nhận output/error đã công bố; input deploy bị từ chối bởi allowlist.
2. Revision contract: Consumer fixture khai báo tag hoặc commit SHA library đã pin, không dùng branch di động làm bằng chứng tái lập.
3. Trust contract: Cùng fixture chạy trong sandbox untrusted trước. Nếu production cần global trusted capability, test capability tối thiểu của API đó, review owner/SCM/retriever và không dùng trusted để né approval.
4. CPS contract: Chỉ dữ liệu serializable sống qua Pipeline step. Chạy integration với checkpoint và, khi library có state dài/chờ step, thêm kịch bản restart/resume.
5. Consumer matrix: Chạy các consumer đại diện trên Jenkins/plugin/JDK/image trong support matrix; một case canary trước khi nâng pin cho số đông.

Thiết kế Jenkins Shared Libraries giải thích chi tiết vars, src, resources, trust, pin revision, @NonCPS và migration. Với Shared Library, “unit xanh” không đủ để kết luận retriever, sandbox hoặc classloading sẽ hoạt động trên controller.

Sandbox runtime và controller testCopy Anchor Link

Thiết kế môi trường disposableCopy Anchor Link

Runtime smoke/integration phải chạy trong controller/agent/container disposable hoặc có vòng đời reset được. Ghi lại manifest môi trường cùng kết quả:

• Jenkins core LTS, plugin set và JDK được pin theo bản/digest đã phê duyệt; image agent cũng pin digest hoặc version bất biến;
• controller và agent lab tách khỏi production, không có production credential, network route production hoặc shared workspace;
• fixture test là dữ liệu tổng hợp, review được; log, JUnit XML, trace và artifact được redaction trước khi lưu;
• mỗi build dùng workspace, namespace, port và data ID riêng; parallel lane không dùng database/queue/path chung;
• Script Approval và permission của lab được reset về baseline sau test; không approve signature để “cho pass”, không mang approval từ lab sang production;
• artifact/workspace cleanup chỉ nhắm resource của build, chạy sau khi thu evidence và có TTL/garbage collector cho crash path.

Phân biệt tín hiệu: static/unit chỉ kiểm tra file và mock; runtime smoke là build thật trong sandbox với plugin/agent thật. Linter hoặc test mock xanh không cho phép gọi controller/agent production.

Integration JenkinsRule và acceptance testCopy Anchor Link

Jenkins Test Harness là framework chính thức cho phát triển Jenkins, dựa trên JUnit. JenkinsRule tạo Jenkins tạm để test plugin/job integration; JenkinsSessionRule hoặc RealJenkinsRule phù hợp hơn khi case cần phiên/restart gần thực tế. Đây là lựa chọn cho code plugin hoặc extension cần kiểm tra controller behavior, không phải thay thế cho Pipeline Unit test thuần.

Acceptance Test Harness (ATH) là dự án Jenkins dùng browser thật cho journey end-to-end. Chỉ chạy một số smoke case rủi ro cao trên hạ tầng acceptance cô lập: UI job tạo được, Jenkinsfile sandbox chạy một stage vô hại, hoặc plugin page cần thiết hiển thị. ATH chậm hơn và có nhiều dependency, nên không dùng nó như required check cho mọi chỉnh sửa Groovy nhỏ.

Một kịch bản restart có giá trị khi Pipeline/library giữ state qua sleep, input, durable task hoặc checkpoint tương tự. Assert result, log và dữ liệu serializable sau resume; không chỉ assert controller khởi động lại. Nếu runtime/project không có JenkinsRule/ATH/plugin cần thiết, ghi lane đó là chưa chạy thay vì gọi snippet là executable.

CI gate và checklistCopy Anchor Link

Một pipeline CI cho mã Pipeline có thể dùng thứ tự sau:

direction: down
pr: PR Jenkinsfile / Shared Library
docs: Markdown/frontmatter/link nếu đổi docs
lint: Declarative lint nếu Jenkinsfile Declarative
unit: Unit src + vars với mock, không network
contract: Contract consumer tại library revision pin
integration: Controller lab sandbox + plugin + agent
smoke: Smoke/ATH chọn lọc hoặc restart lane theo lịch/release
status: Publish status, version manifest, report đã redact
pr -> docs -> lint -> unit -> contract -> integration -> smoke -> status

Các check required nên chặn merge khi lint, unit hoặc contract fail. Integration/ATH có thể chạy theo branch bảo vệ, release candidate hoặc lịch nếu thời gian/capacity đắt, nhưng phải có owner, SLA, evidence và policy ngăn release khi lane bắt buộc chưa đạt. Không cấp credential release cho PR/fork để làm integration thuận tiện.

Checklist reviewCopy Anchor Link

• Tôi đã chọn lớp test theo rủi ro: lint, unit, contract và runtime không bị lẫn nghĩa.
• Declarative linter chạy trên controller có Pipeline: Declarative tương thích, hoặc trạng thái chưa chạy được ghi rõ.
• Linter pass không được diễn giải là build, agent, plugin, credential, security hay deploy an toàn.
• Unit test mock mọi sh, network, credential và step side effect; có case branch, error, retry, parameter và environment scope.
• Shared Library test riêng façade vars, class thuần src, resource; consumer pin tag/commit và có contract fixture.
• Trusted/untrusted library, Script Security và approval được kiểm tra ở controller lab; không có approval mù.
• State đi qua Pipeline step là serializable; case CPS/restart được thêm khi workflow cần resume.
• Runtime lane ghi Jenkins/plugin/JDK/image version, dùng agent disposable và không chạm production credentials/network/data.
• Fixture/report/artifact không có secret hoặc dữ liệu nhạy cảm; trước cleanup, scope/path/marker được xác minh.
• Parallel test có namespace, port, workspace và dữ liệu riêng; resource bỏ lại có TTL/cleanup guard.

Lab local an toànCopy Anchor Link

Lab này chỉ tạo Jenkinsfile text vô hại và kiểm tra các guard local. Nó không chứng minh Declarative linter Jenkins, plugin, credential, Script Approval hay agent hoạt động. Không cần network, Docker, Jenkins controller hoặc secret.

Tạo fixture Jenkinsfile vô hạiCopy Anchor Link

Chạy trong shell local. mktemp tạo directory duy nhất dưới parent temp; marker liên kết cleanup với chính lần chạy đó. Jenkinsfile chỉ echo, không checkout, shell, credential hay external service.

set -eu
umask 077

readonly LAB_PARENT="${TMPDIR:-/tmp}"
readonly LAB_PREFIX='jenkinsfile-testing-lab.'
LAB_ROOT="$(mktemp -d "${LAB_PARENT}/${LAB_PREFIX}XXXXXX")"
readonly LAB_ROOT
readonly LAB_MARKER="${LAB_ROOT}/.jenkinsfile-testing-lab-marker"
readonly LAB_FILE="${LAB_ROOT}/Jenkinsfile"

case "$LAB_ROOT" in
  "$LAB_PARENT"/"$LAB_PREFIX"*) ;;
  *) printf >&2 'Refuse lab: unexpected temporary prefix.\n'; exit 1 ;;
esac
[ "$(dirname -- "$LAB_ROOT")" = "$LAB_PARENT" ] || {
  printf >&2 'Refuse lab: temporary directory is not a direct child.\n'; exit 1;
}
printf '%s\n' 'jenkinsfile-testing-lab-v1' > "$LAB_MARKER"

cat > "$LAB_FILE" <<'EOF'
pipeline {
  agent none
  stages {
    stage('Static fixture') {
      steps {
        echo 'This fixture has no shell, credential, network, or deployment step.'
      }
    }
  }
}
EOF

test -s "$LAB_FILE"
grep -Fqx "        echo 'This fixture has no shell, credential, network, or deployment step.'" "$LAB_FILE"
printf 'Static fixture verified at a guarded temporary path.\n'

Validate trên sandbox loopback có giới hạnCopy Anchor Link

Muốn gọi linter thật, dùng controller sandbox đã provision riêng và chỉ sau khi administrator xác nhận Pipeline: Declarative, authentication, CSRF policy, CLI/HTTP endpoint và version compatibility. Lệnh sau là non-executable cho tới khi các biến được lấy từ secret manager/lab configuration; nó không tạo token, không in credential và chỉ nhắm loopback sandbox.

# Prerequisite: controller sandbox chỉ bind loopback, HTTPS/CLI policy đã được kiểm tra,
# và JENKINS_AUTH_FILE là file credential do secret manager provision, mode 0600.
set -eu
: "${JENKINS_URL:?Ví dụ: https://127.0.0.1:8443/jenkins}"
: "${JENKINS_AUTH_FILE:?Path tới auth file ngoài repository}"
test -r "$JENKINS_AUTH_FILE"
java -jar jenkins-cli.jar -s "$JENKINS_URL" \
  -auth @"$JENKINS_AUTH_FILE" \
  declarative-linter < "$LAB_FILE"

Không thay auth file bằng chuỗi user:token trong command, không dùng curl -k, và không chuyển loopback lab thành endpoint công khai. Nếu endpoint HTTP cần crumb, lấy và gửi crumb/cookie theo policy sandbox; không ghi chúng vào terminal/log. Lệnh không chạy được khi thiếu plugin/runtime là trạng thái hợp lệ cần báo rõ, không phải lý do tắt CSRF hoặc dùng account admin.

Dọn fixture có guardCopy Anchor Link

Chạy hàm này trong cùng shell với bước tạo. Nó từ chối cleanup khi thiếu biến, sai parent/prefix, không phải child trực tiếp, marker không đúng hoặc fixture không có. Không dùng nó để xóa job, controller, volume, workspace Jenkins hay bất kỳ path cố định nào.

cleanup_lab() {
  local expected_marker='jenkinsfile-testing-lab-v1'

  if [ -z "${LAB_PARENT:-}" ] || [ -z "${LAB_PREFIX:-}" ] || \
     [ -z "${LAB_ROOT:-}" ] || [ -z "${LAB_MARKER:-}" ] || \
     [ -z "${LAB_FILE:-}" ]; then
    printf >&2 'Refuse cleanup: missing lab variables.\n'
    return 1
  fi

  case "$LAB_ROOT" in
    "$LAB_PARENT"/"$LAB_PREFIX"*) ;;
    *) printf >&2 'Refuse cleanup: invalid prefix.\n'; return 1 ;;
  esac

  if [ "$(dirname -- "$LAB_ROOT")" != "$LAB_PARENT" ] || \
     [ "$LAB_MARKER" != "$LAB_ROOT/.jenkinsfile-testing-lab-marker" ] || \
     [ "$LAB_FILE" != "$LAB_ROOT/Jenkinsfile" ] || \
     [ ! -d "$LAB_ROOT" ] || [ ! -f "$LAB_MARKER" ] || \
     [ ! -f "$LAB_FILE" ] || \
     [ "$(cat -- "$LAB_MARKER")" != "$expected_marker" ]; then
    printf >&2 'Refuse cleanup: parent, fixture, or marker guard failed.\n'
    return 1
  fi

  cd / || return 1
  rm -rf -- "$LAB_ROOT"
}

cleanup_lab

Khắc phục sự cốCopy Anchor Link

Nguồn tham khảoCopy Anchor Link

Jenkins chính thứcCopy Anchor Link

• Pipeline development tools and Declarative linter — linter CLI/HTTP và công cụ phát triển Pipeline.
• Pipeline syntax — Declarative directives và Pipeline DSL.
• Using a Jenkinsfile — Jenkinsfile, runtime và credential handling.
• In-process Script Approval — Groovy Sandbox và quyết định approval.
• Jenkins test harness — JUnit, JenkinsRule, integration và test pyramid cho Jenkins development.
• Jenkins acceptance-test-harness — repository ATH cho UI/end-to-end tests.
• Pipeline CPS method mismatches — serialization, CPS và giới hạn runtime.
• CSRF Protection — crumb, session và API token behavior.

Bên thứ baCopy Anchor Link

• JenkinsPipelineUnit — framework mock/unit test cho Jenkins Pipeline; kiểm tra version/API tương thích trước khi dùng.

Đọc tiếpCopy Anchor Link