安裝 Hex 套件

Tuist 提供一個 Hex 套件 tuist_ex，可與你的 Elixir 專案整合，以啟用如構建洞察和測試洞察等功能。本指南將引導你完成安裝和設定。

此套件需要 Elixir 1.18 或更高版本。它不需要 Tuist 命令列介面。

1. 建立專案#

在 Tuist 儀表板中建立專案，並選擇 Mix (Elixir) 作為其構建系統。其代號 account/project 用於將你的 Mix 專案與其連接。

2. 新增套件#

將 tuist_ex 加入你 mix.exs 中的依賴項：

elixir

defp deps do
  [
    {:tuist_ex, "~> 0.10", runtime: false}
  ]
end

然後獲取它：

bash

mix deps.get

runtime: false 可確保 Tuist 不會進入你正在執行的應用程式。請繼續按照 Elixir 入門的指引，一起設定快取、構建洞察和測試洞察。以下章節涵蓋驗證和設定細節。

3. 為團隊和持續整合進行驗證#

每位團隊成員需執行以下指令，以在其機器上存取 Tuist 功能：

bash

mix tuist.login

它會列印一個簡短的登入代碼，開啟瀏覽器讓你輸入，並等待你授權。若要在沒有瀏覽器的情況下登入，請傳遞你的憑證：

bash

mix tuist.login --email [email protected] --password secret

當你使用自託管或本機 Tuist 伺服器時，請在 mix.exs 中設定其基本 URL，或使用 --url 傳遞：

bash

mix tuist.login --url http://localhost:8080

保持主機名稱拼寫一致。例如，為 localhost 儲存的登入資訊與為 127.0.0.1 儲存的登入資訊是分開的。

在 GitHub Actions、CircleCI 和 Bitrise 上，持續整合無需登入步驟。當任務首次發送報告時，它會將供應商的 OpenID Connect 令牌交換為 Tuist 令牌。將你的 GitHub 儲存庫連接到你的 Tuist 專案，並在 GitHub Actions 中給予作業 id-token: write 權限：

yaml

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: erlef/setup-beam@v1
        with:
          elixir-version: '1.18'
          otp-version: '27'
      - run: mix deps.get
      - run: mix test

對於任何其他 OpenID Connect 身份提供者（例如 Fly.io Machines），請在你帳戶的 設定 → 驗證 頁面的 工作負載身份 部分設定工作負載身份信任策略，這將授予 CI 存取該帳戶擁有之所有當前和未來專案的權限。將 TUIST_OIDC_ACCOUNT 設定為擁有該專案的 Tuist 帳戶，並透過 TUIST_OIDC_TOKEN 提供具有策略受眾的新簽發身份令牌。當沒有帳戶令牌或有效的已儲存登入資訊時，整合會自動交換它；mix tuist.login 也接受在非 CI 環境中使用它。自動交換僅對同一伺服器、帳戶和提供的身份令牌重用未過期的會話。更改該身份會觸發新的交換，而提供空白身份則會失敗，而不會重用先前的會話。Tuist 會話在沒有刷新令牌的情況下持續一小時，因此對於運行時間較長的工作負載，請在會話過期前簽發新的身份令牌並再次運行 mix tuist.login。請參閱工作負載身份設定和 Fly.io 範例。

來自分叉的拉取請求不會獲得 OpenID Connect 令牌，因此它們的運行不會被報告，並且仍會像往常一樣通過或失敗。在其他供應商處，將 TUIST_TOKEN 環境變數設定為帳戶令牌。請遵循持續整合驗證指南來建立一個。

4. 繼續使用 `mix test` 和 `mix compile`#

共用設定會為你安裝編譯和測試別名。mix test test/my_app_test.exs:12 --trace 會以相同的輸出和退出代碼報告運行，而編譯整合涵蓋由 mix test 或 mix phx.server 觸發的構建。如果編譯發現無事可做，則不會報告。

當你直接呼叫這些任務的名稱時，它們也能運作。Mix 會在 dev 環境中啟動以這種方式輸入的任務，因此該任務必須在第二個進程中重新開始以用於測試環境。將任務添加到首選環境中以跳過此步驟：

elixir

def cli do
  [preferred_envs: ["tuist.test": :test, "tuist.test.build": :test]]
end

設定參考#

以下選項可在 mix.exs 的專案選項下的 tuist 中使用：

選項	類型	預設值	說明
`project`	`String`	無（必填）	`account/project` 格式的專案識別碼。
`url`	`String`	`"https://tuist.dev"`	Tuist 伺服器的基本 URL。
`cache`	`boolean` 或關鍵字列表	已停用	設定啟用依賴項快取。請參閱 Elixir 快取以了解排除項和額外輸入。
`test_retries`	`integer`	`0`	重試失敗測試的次數；請參閱測試重試。
`tags`	`String` 列表	`[]`	附加到每個構建的標籤；請參閱自訂元數據。
`values`	映射	`%{}`	附加到每個構建的鍵值數據。

環境變數優先於 mix.exs：

變數	說明
`TUIST_PROJECT`	`account/project` 格式的專案識別碼。
`TUIST_URL`	Tuist 伺服器的基本 URL。
`TUIST_TOKEN`	用於驗證的令牌，取代儲存的登入資訊。
`TUIST_OIDC_TOKEN`	新簽發的 OpenID Connect 身分令牌，會交換為 Tuist 令牌。對於 GitHub Actions 和 Bitrise，其受眾必須是 `tuist`；對於其他供應商，則需符合帳戶的工作負載身分。由 `mix tuist.login` 使用，或在沒有帳戶令牌或有效儲存登入時作為備用。
`TUIST_OIDC_ACCOUNT`	擁有該專案的 Tuist 帳戶句柄。當透過帳戶工作負載身分交換令牌時需要此項。它會在現有的工作負載身分中進行選擇，本身並不授予存取權限。
`TUIST_TEST_RETRIES`	重試失敗測試的次數。
`TUIST_TAGS`	以逗號分隔的標籤，附加到構建中。
`TUIST_VALUES`	以逗號分隔的 `key=value` 配對，附加到構建中。
`TUIST_DEBUG`	設為 `1` 以列印無法發送報告的原因。

報告絕不會改變 mix test 或 mix compile 的退出代碼。如果無法發送報告，除非設定了 TUIST_DEBUG=1，否則任務不會顯示任何訊息。

下一步#

安裝並設定套件後，你可以使用：

依賴項快取，以便在本機和 CI 構建中重複使用已編譯的依賴項。
構建洞察，以追蹤編譯時間、警告以及阻礙構建的因素。
測試洞察，以追蹤每個測試的測試效能。
不穩定測試，以偵測和追蹤間歇性失敗的測試。
測試分片，以便將測試分散到持續整合執行器上。

安裝 Hex 套件

1. 建立專案#

2. 新增套件#

3. 為團隊和持續整合進行驗證#

4. 繼續使用 mix test 和 mix compile#

設定參考#

下一步#

4. 繼續使用 `mix test` 和 `mix compile`#