headless 執行與 CI

在介面裡建構好的情境，可以從命令列以無視窗的方式執行。這條路徑能把您的 API 測試變成管線中的一個步驟。

restorm \
  --open ./projet.restorm \
  --run "Find pets by status" \
  --headless \
  --param status=available

Pro 版

headless 執行包含在 Pro 與 Enterprise 版中。它需要一個組織權杖，透過環境 變數 RESTORM_TOKEN 提供。請參閱 方案與功能權限。

引數

引數	用途
--open <path>, -o	要開啟的專案。與 --run 併用時為必填
--run <target>	要執行的情境。只要出現它，就會啟用命令列模式
--by <name|id>	--run 以什麼方式指定情境：以名稱（預設）或以識別碼
--headless	完全不顯示視窗。不加它時，視窗會顯示出來，同時記錄在主控台上滾動
--param name=value	提供給情境輸入參數（一個 Input / Param 方塊）的值。可重複
--all-logs	一併納入引擎本身的項目；預設只輸出 Log 動作產生的項目
--out <file>	同時把記錄逐步寫入一個檔案
--clear-settings, -cls	啟動前重設所有偏好設定

格式錯誤的 --param（少了 =）會被回報到錯誤輸出並忽略。name=（空值）是可以 接受的。

這些值會依參數宣告的型別轉換 — 請參閱 情境中的變數與資料。

--param 針對的是情境的輸入，而不是環境變數

--param 餵的是情境裡宣告的 Input / Param 方塊 — 它不會修改環境變數。 因此上面那行 --param status=available 之所以有效，只是因為那個情境公開了一個 名為 status 的輸入參數。如果 baseUrl 是一個環境變數，那麼想用 --param baseUrl=… 覆寫基底 URL 不會有任何作用：住在 環境裡的值，無法從命令列 覆寫。若想讓這樣的值能從 CI 操控，請把它公開成情境的輸入參數（一個 Input / Param 方塊），再接到您需要的地方。

結束代碼

代碼	意義
0	情境正常結束
1	失敗、被取消，或引擎發生錯誤
2	找不到目標、--out 指定的檔案無法存取，或使用了 --run 卻沒有 --open
3	權限被拒：RESTORM_TOKEN 缺失、無效或已撤銷、方案等級不足，或驗證端點無法連線

正是這套約定讓結果能被 CI runner 直接使用。

輸出

記錄會寫到標準輸出，一筆一筆地，一產生就寫出，形式是一段 YAML 序列：

- message: "🔵 [2026-07-29 10:30:00.123] Commande créée"
  data: { id: 4271 }

各層級前面都帶一個色點：⚪ debug、🔵 info、🟠 warn、🔴 error。每一行都 不會被切斷 — 輸出始終可以用 grep 處理。錯誤會走標準錯誤輸出。

這正是介面上「複製記錄」按鈕產生的文字：兩邊格式完全相同。

CI 中的密鑰

請使用環境變數這種密鑰來源：密鑰由您 CI 的保險庫注入，Restorm 只負責讀取， 專案裡不會寫入任何東西。請參閱密鑰。

請固定版本

下載通道發佈的是帶版本號的檔案（restorm_<version>_amd64.deb）：沒有 latest 這種別名。請在您的管線裡固定版本 — 在 CI 中本來就該這樣，這樣新版本 才不會在沒人審閱的情況下改變某個作業的行為。最新版本確切的檔案名稱，列在同一個 通道的 latest-linux.yml 資訊清單裡。

GitHub Actions

name: Tests d'API
on: [push]

jobs:
  api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Installer Restorm
        env:
          RESTORM_VERSION: '1.4.2' # 您想要固定的版本
        run: |
          curl -sSL -o restorm.deb \
            "https://dl.restorm.app/restorm_${RESTORM_VERSION}_amd64.deb"
          sudo apt-get install -y ./restorm.deb

      - name: Exécuter les tests de fumée
        env:
          RESTORM_TOKEN: ${{ secrets.RESTORM_TOKEN }}
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: |
          xvfb-run -a restorm \
            --open ./api.restorm \
            --run "Find pets by status" \
            --headless \
            --all-logs \
            --out run.log \
            --param status=available

      - name: Publier le journal
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: journal-restorm
          path: run.log

GitLab CI

tests-api:
  image: ubuntu:24.04
  variables:
    RESTORM_TOKEN: $RESTORM_TOKEN
    RESTORM_VERSION: '1.4.2' # 您想要固定的版本
  before_script:
    - apt-get update && apt-get install -y curl xvfb
    - curl -sSL -o restorm.deb "https://dl.restorm.app/restorm_${RESTORM_VERSION}_amd64.deb"
    - apt-get install -y ./restorm.deb
  script:
    - >
      xvfb-run -a restorm
      --open ./api.restorm
      --run "Find pets by status"
      --headless --all-logs --out run.log
      --param status=$PET_STATUS
  artifacts:
    when: always
    paths: [run.log]

headless 模式下有什麼不同

• Toast 動作什麼都不做；執行會照常繼續。
• 參數無法以互動方式詢問：請用 --param 全部提供，或讓它們採用各自的預設值。
• 不論設定成什麼，MCP 伺服器在沒有顯示環境的機器上 永遠不會啟動。

取得權杖

RESTORM_TOKEN 權杖（前綴為 rstk_）可以從您帳號的儀表板產生。它繫結在組織 上，而不是繫結在某個人身上：這就是要放進 CI 保險庫的那個權杖。請參閱 帳號與登入。