English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Testing

Kiểm thử: bản cập nhật và Plugin

Đây là checklist chuyên dụng cho việc xác thực cập nhật và plugin. Mục tiêu rất đơn giản: chứng minh gói có thể cài đặt có thể cập nhật trạng thái người dùng thực, sửa trạng thái cũ lỗi thời thông qua doctor, và vẫn cài đặt, tải, cập nhật, cũng như gỡ cài đặt plugin từ các nguồn được hỗ trợ.

Để xem bản đồ trình chạy kiểm thử rộng hơn, xem Kiểm thử. Đối với khóa nhà cung cấp live và các bộ kiểm thử chạm mạng, xem Kiểm thử live.

Những gì chúng ta bảo vệ

Các kiểm thử cập nhật và plugin bảo vệ các hợp đồng này:

  • Một tarball gói là đầy đủ, có dist/postinstall-inventory.json hợp lệ, và không phụ thuộc vào các tệp repo chưa được đóng gói.
  • Người dùng có thể chuyển từ một gói đã phát hành cũ hơn sang gói ứng viên mà không mất config, agent, phiên, workspace, danh sách cho phép plugin, hoặc config kênh.
  • openclaw doctor --fix --non-interactive sở hữu các đường dẫn dọn dẹp và sửa chữa cũ. Khởi động không nên phát sinh các migration tương thích ẩn cho trạng thái plugin lỗi thời.
  • Cài đặt plugin hoạt động từ thư mục cục bộ, repo git, gói npm, và đường dẫn registry ClawHub.
  • Các phụ thuộc npm của plugin được cài trong gốc npm được quản lý, được quét trước khi tin cậy, và được gỡ bỏ thông qua npm trong khi gỡ cài đặt để các phụ thuộc được hoist không còn sót lại.
  • Cập nhật plugin ổn định khi không có gì thay đổi: bản ghi cài đặt, nguồn đã phân giải, bố cục phụ thuộc đã cài đặt, và trạng thái bật được giữ nguyên.

Bằng chứng cục bộ trong khi phát triển

Bắt đầu hẹp:

pnpm changed:lanes --json
pnpm check:changed
pnpm test:changed

Đối với các thay đổi về cài đặt plugin, gỡ cài đặt, phụ thuộc, hoặc package inventory, cũng chạy các kiểm thử tập trung bao phủ seam đã chỉnh sửa:

pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts

Trước khi bất kỳ lane Docker nào của gói tiêu thụ tarball, hãy chứng minh artifact gói:

pnpm release:check

release:check chạy các kiểm tra drift config/docs/API, ghi package dist inventory, chạy npm pack --dry-run, từ chối các tệp bị cấm trong gói, cài tarball vào một tiền tố tạm, chạy postinstall, và smoke các entrypoint kênh được đóng gói.

Các lane Docker

Các lane Docker là bằng chứng cấp sản phẩm. Chúng cài đặt hoặc cập nhật một gói thực bên trong container Linux và xác nhận hành vi thông qua lệnh CLI, khởi động Gateway, probe HTTP, trạng thái RPC, và trạng thái hệ thống tệp.

Dùng các lane tập trung trong khi lặp:

pnpm test:docker:plugins
pnpm test:docker:plugin-lifecycle-matrix
pnpm test:docker:plugin-update
pnpm test:docker:upgrade-survivor
pnpm test:docker:published-upgrade-survivor
pnpm test:docker:update-restart-auth
pnpm test:docker:update-migration

Các lane quan trọng:

  • test:docker:plugins xác thực smoke cài đặt plugin, cài đặt thư mục cục bộ, hành vi bỏ qua cập nhật thư mục cục bộ, thư mục cục bộ có phụ thuộc đã cài sẵn, cài đặt gói file:, cài đặt git có thực thi CLI, cập nhật moving-ref của git, cài đặt từ npm registry với phụ thuộc bắc cầu được hoist, no-op cập nhật npm, cài đặt fixture ClawHub cục bộ và no-op cập nhật, hành vi cập nhật marketplace, và bật/kiểm tra Claude-bundle. Đặt OPENCLAW_PLUGINS_E2E_CLAWHUB=0 để giữ khối ClawHub kín và offline.
  • test:docker:plugin-lifecycle-matrix cài gói ứng viên trong một container trống, chạy một plugin npm qua cài đặt, kiểm tra, tắt, bật, nâng cấp tường minh, hạ cấp tường minh, và gỡ cài đặt sau khi xóa mã plugin. Nó ghi log chỉ số RSS và CPU cho từng pha.
  • test:docker:plugin-update xác thực rằng một plugin đã cài đặt nhưng không thay đổi sẽ không cài đặt lại hoặc mất metadata cài đặt trong khi chạy openclaw plugins update.
  • test:docker:upgrade-survivor cài tarball ứng viên lên một fixture người dùng cũ bẩn, chạy cập nhật gói cùng doctor không tương tác, rồi khởi động Gateway loopback và kiểm tra việc bảo toàn trạng thái.
  • test:docker:published-upgrade-survivor trước tiên cài một baseline đã phát hành, cấu hình nó qua một công thức openclaw config set được nướng sẵn, cập nhật nó lên tarball ứng viên, chạy doctor, kiểm tra dọn dẹp cũ, khởi động Gateway, và probe /healthz, /readyz, cùng trạng thái RPC.
  • test:docker:update-restart-auth cài gói ứng viên, khởi động một Gateway token-auth được quản lý, bỏ đặt env xác thực Gateway của caller cho openclaw update --yes --json, và yêu cầu lệnh cập nhật ứng viên khởi động lại Gateway trước các probe thông thường.
  • test:docker:update-migration là lane published-update nặng về dọn dẹp. Nó bắt đầu từ trạng thái người dùng kiểu Discord/Telegram đã cấu hình, chạy doctor baseline để các phụ thuộc plugin đã cấu hình có cơ hội hiện thực hóa, seed rác phụ thuộc plugin cũ cho một plugin đóng gói đã cấu hình, cập nhật lên tarball ứng viên, và yêu cầu doctor sau cập nhật xóa các root phụ thuộc cũ.

Các biến thể published-upgrade survivor hữu ích:

[email protected] \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=versioned-runtime-deps \
pnpm test:docker:published-upgrade-survivor

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@latest \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \
pnpm test:docker:published-upgrade-survivor

Các kịch bản có sẵn là base, feishu-channel, bootstrap-persona, plugin-deps-cleanup, configured-plugin-installs, stale-source-plugin-shadow, tilde-log-path, và versioned-runtime-deps. Trong các lần chạy tổng hợp, OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues mở rộng thành tất cả kịch bản có hình dạng vấn đề đã báo cáo, bao gồm migration cài đặt configured-plugin.

Full update migration được cố ý tách khỏi Full Release CI. Dùng workflow thủ công Update Migration khi câu hỏi phát hành là "mọi bản phát hành stable đã xuất bản từ 2026.4.23 trở đi có thể cập nhật lên ứng viên này và dọn rác phụ thuộc plugin không?":

gh workflow run update-migration.yml \
  --ref main \
  -f workflow_ref=main \
  -f package_ref=main \
  -f baselines=all-since-2026.4.23 \
  -f scenarios=plugin-deps-cleanup

Package Acceptance

Package Acceptance là gate gói theo kiểu native của GitHub. Nó phân giải một gói ứng viên thành tarball package-under-test, ghi lại phiên bản và SHA-256, sau đó chạy các lane Docker E2E có thể tái sử dụng dựa trên chính tarball đó. Ref harness workflow tách biệt với ref nguồn gói, vì vậy logic kiểm thử hiện tại có thể xác thực các bản phát hành tin cậy cũ hơn.

Nguồn ứng viên:

  • source=npm: xác thực openclaw@beta, openclaw@latest, hoặc một phiên bản đã phát hành chính xác.
  • source=ref: pack một branch, tag, hoặc commit tin cậy với harness hiện tại đã chọn.
  • source=url: xác thực tarball HTTPS với package_sha256 bắt buộc.
  • source=artifact: tái sử dụng tarball do một lần chạy Actions khác tải lên.

Full Release Validation mặc định dùng source=artifact, được build từ SHA phát hành đã phân giải. Để chứng minh sau phát hành, truyền [email protected] để cùng ma trận nâng cấp nhắm tới gói npm đã xuất xưởng thay thế.

Các kiểm tra phát hành gọi Package Acceptance với tập package/update/restart/plugin:

doctor-switch update-channel-switch update-corrupt-plugin upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update

Khi bật release soak, chúng cũng truyền:

published_upgrade_survivor_baselines=last-stable-4 2026.4.23 2026.5.2 2026.4.15
published_upgrade_survivor_scenarios=reported-issues
telegram_mode=mock-openai

Điều này giữ migration gói, chuyển kênh cập nhật, dung thứ plugin được quản lý bị hỏng, dọn dẹp phụ thuộc plugin lỗi thời, bao phủ plugin offline, hành vi cập nhật plugin, và QA gói Telegram trên cùng artifact đã phân giải mà không khiến gate gói phát hành mặc định đi qua mọi bản phát hành đã xuất bản.

last-stable-4 phân giải thành bốn bản phát hành OpenClaw stable mới nhất đã xuất bản trên npm. Release package acceptance ghim 2026.4.23 làm ranh giới tương thích cập nhật plugin đầu tiên, 2026.5.2 làm ranh giới churn kiến trúc plugin, và 2026.4.15 làm baseline published-update cũ hơn của 2026.4.1x; bộ phân giải khử trùng lặp các pin đã nằm trong bốn bản mới nhất. Để bao phủ published update migration đầy đủ, dùng all-since-2026.4.23 trong workflow Update Migration riêng thay vì Full Release CI. release-history vẫn có sẵn để lấy mẫu rộng hơn thủ công khi bạn cũng muốn anchor trước ngày cũ.

Khi chọn nhiều baseline published-upgrade survivor, workflow Docker có thể tái sử dụng sẽ shard từng baseline vào job runner mục tiêu riêng. Mỗi shard baseline vẫn chạy tập kịch bản đã chọn, nhưng log và artifact được giữ theo từng baseline và thời gian wall bị chặn bởi shard chậm nhất thay vì một job tuần tự lớn.

Chạy thủ công một profile gói khi xác thực ứng viên trước phát hành:

gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=package \
  -f published_upgrade_survivor_baselines="last-stable-4 2026.4.23 2026.5.2 2026.4.15" \
  -f published_upgrade_survivor_scenarios=reported-issues \
  -f telegram_mode=mock-openai

Dùng suite_profile=product khi câu hỏi phát hành bao gồm kênh MCP, dọn dẹp cron/subagent, tìm kiếm web OpenAI, hoặc OpenWebUI. Chỉ dùng suite_profile=full khi bạn cần bao phủ đầy đủ đường dẫn phát hành Docker.

Mặc định phát hành

Đối với release candidate, stack bằng chứng mặc định là:

  1. pnpm check:changed và pnpm test:changed cho hồi quy cấp nguồn.
  2. pnpm release:check cho tính toàn vẹn artifact gói.
  3. Profile package của Package Acceptance hoặc các lane gói tùy chỉnh của release-check cho hợp đồng install/update/restart/plugin.
  4. Kiểm tra phát hành Cross-OS cho trình cài đặt, onboarding, và hành vi nền tảng đặc thù theo OS.
  5. Bộ live chỉ khi bề mặt đã thay đổi chạm tới hành vi nhà cung cấp hoặc dịch vụ được host.

Trên máy của maintainer, các gate rộng và bằng chứng sản phẩm Docker/gói nên chạy trong Testbox trừ khi đang làm bằng chứng cục bộ một cách tường minh.

Tương thích cũ

Độ nới tương thích là hẹp và có giới hạn thời gian:

  • Các gói đến 2026.4.25, bao gồm 2026.4.25-beta.*, có thể dung thứ các lỗ hổng metadata gói đã xuất xưởng trong Package Acceptance.
  • Gói 2026.4.26 đã xuất bản có thể cảnh báo về các tệp stamp metadata build cục bộ đã xuất xưởng.
  • Các gói muộn hơn phải đáp ứng hợp đồng hiện đại. Cùng các lỗ hổng đó sẽ thất bại thay vì cảnh báo hoặc bỏ qua.

Không thêm migration khởi động mới cho các hình dạng cũ này. Thêm hoặc mở rộng một sửa chữa doctor, rồi chứng minh nó bằng upgrade-survivor, published-upgrade-survivor, hoặc update-restart-auth khi lệnh cập nhật sở hữu việc khởi động lại.

Thêm bao phủ

Khi thay đổi hành vi cập nhật hoặc plugin, hãy thêm bao phủ ở lớp thấp nhất có thể thất bại vì đúng lý do:

  • Logic đường dẫn hoặc metadata thuần: kiểm thử unit cạnh nguồn.
  • Hành vi package inventory hoặc packed-file: kiểm thử package-dist-inventory hoặc trình kiểm tra tarball.
  • Hành vi cài đặt/cập nhật CLI: assertion hoặc fixture lane Docker.
  • Hành vi migration bản phát hành đã xuất bản: kịch bản published-upgrade-survivor.
  • Hành vi khởi động lại do cập nhật sở hữu: update-restart-auth.
  • Hành vi nguồn registry/gói: fixture test:docker:plugins hoặc máy chủ fixture ClawHub.
  • Hành vi bố cục hoặc dọn dẹp phụ thuộc: assert cả thực thi runtime và ranh giới hệ thống tệp. Các phụ thuộc npm có thể được hoist dưới root npm được quản lý, vì vậy kiểm thử nên chứng minh root được quét/dọn thay vì giả định một cây node_modules cục bộ theo gói.

Giữ các fixture Docker mới mặc định hermetic. Dùng registry fixture cục bộ và gói giả trừ khi mục tiêu của kiểm thử là hành vi registry live.

Triage lỗi

Bắt đầu với định danh artifact:

  • Tóm tắt resolve_package Chấp nhận gói: nguồn, phiên bản, SHA-256 và tên artifact.
  • Artifact Docker: .artifacts/docker-tests/**/summary.json, failures.json, nhật ký lane và lệnh chạy lại.
  • Tóm tắt sống sót sau nâng cấp: .artifacts/upgrade-survivor/summary.json, bao gồm phiên bản baseline, phiên bản ứng viên, kịch bản, thời gian từng giai đoạn và các bước recipe.

Ưu tiên chạy lại đúng lane đã thất bại với cùng artifact gói thay vì chạy lại toàn bộ umbrella phát hành.