Installing Apex Stem

•Apex Stem ドキュメント
Apex StemInstallationUnlocked PackageSalesforce
Two install paths for every framework: Unlocked Packages (framework tests excluded from RunLocalTests) and git submodules. Current versions and install IDs.

Apex Stem の各フレームワークは Unlocked Package(2GP、名前空間なし)と git submodule の2つの経路で導入できます。どちらも中身は同じソースです。プロジェクトごとに選べますし、org によって使い分けても問題ありません。

Which path should I take?

Unlocked Package(推奨)Git Submodule
向いている場面新規プロジェクト、本番 orgsubmodule 運用中の既存プロジェクト、コントリビュータ
デプロイ時のフレームワークテストRunLocalTests から除外。validate がフレームワークのテストを実行しない(=落ちない)ローカルテストとして毎回実行される
org のカバレッジ計算フレームワークのコードは計算から除外コードもテストも計算に含まれる
バージョンの可視性sf package installed list で正確なバージョンが見えるsubmodule の git タグを確認する
アップグレード次バージョンをインストールするだけ(上書き)git submodule update --remote
ディレクトリ階層retrieve 直後はフラット。npx apex-librarian arrange で復元できる(後述)submodule がそのまま保持する

パッケージ経路を用意した理由は、実レコードを作るフレームワークテスト(たとえば ApexBlueprint の結合テスト)が、org 固有の入力規則や必須項目と衝突しうるためです。パッケージとして導入すれば、それらのテストはデプロイと validate では実行されません。リリースを止める失敗クラスが丸ごと消えます。

なお、sf apex run test -l RunLocalTests で手動実行したときは、名前空間を持たないアンロックパッケージのテストも対象に入ります (Salesforce CLI のヘルプでも、デプロイ側と手動実行側で RunLocalTests の定義が書き分けられています)。Apex Stem のパッケージは名前空間なしで発行しているので、手動実行ではフレームワークのテストも走ります。そこで落ちたテストのクラスが ManageableState = installedEditable なら、パッケージ由来なので無視して構いません。

Current versions

FrameworkVersionInstall command
ApexEloquentv4.0.1sf package install -p 04tgK000000axpZQAQ -o <your-org> -w 10
ApexBlueprintv2.2.2sf package install -p 04tgK000000b1gHQAQ -o <your-org> -w 10
ApexTracev1.6.1sf package install -p 04tgK000000b1ZpQAI -o <your-org> -w 10
ApexToolsv1.2.1sf package install -p 04tgK000000b1YDQAY -o <your-org> -w 10

各フレームワークは完全に独立しています。インストール順の制約も相互依存もありません。必要なものだけ入れてください。

ブラウザからインストールする場合は https://login.salesforce.com/packaging/installPackage.apexp?p0=<install ID> を開きます(Sandbox は test.salesforce.com に読み替え)。過去バージョンの install ID は各リポジトリの GitHub Releases に載っています。

ApexEloquent / ApexBlueprint / ApexTrace / ApexTools

Git submodule

BASH
cd /path/to/your/project
git submodule add https://github.com/krile136/ApexEloquent.git  force-app/main/default/classes/ApexEloquent
git submodule add https://github.com/krile136/ApexBlueprint.git force-app/main/default/classes/ApexBlueprint
git submodule add https://github.com/krile136/ApexTrace.git     force-app/main/default/classes/ApexTrace
git submodule add https://github.com/krile136/ApexTools.git     force-app/main/default/classes/ApexTools
git submodule update --init --recursive

sf project deploy start -d force-app/main/default/classes/<Name> で通常のソースフォルダと同じようにデプロイできます。submodule を使うプロジェクトをクローンするときは git clone --recurse-submodules を忘れずに。

Switching from submodules

submodule のソースで導入済みの org にパッケージを入れる場合も、既存クラスを先に消す必要はありません。同名の unmanaged クラスがあると、インストール時にパッケージがその所有権を引き取ります (ManageableState が unmanaged から installedEditable に変わります)。

  • 小さいものから 1 本ずつ入れる (ApexTools → ApexTrace → ApexBlueprint → ApexEloquent)。まとめて入れると、失敗したときに切り分けられません
  • インストール時に org の全テストは走りません。本番 org でも 1 本あたり数十秒から数分で終わった実測があります
  • 確認は ManageableState で行う。sf package installed list への反映は遅れることがあります
BASH
sf data query -o <your-org> --use-tooling-api -r csv \
  -q "SELECT ManageableState, COUNT(Id) c FROM ApexClass WHERE NamespacePrefix = null GROUP BY ManageableState"

⚠️ 引き取った後は、submodule をデプロイ対象に含めないでください。 含めると installedEditable のクラスを unmanaged で上書きし、状態が巻き戻ります。リポジトリの submodule は、ソースの参照元とバージョンの記録として残しておけば十分です。

Restoring the directory layout

Salesforce の org には Apex クラスのフォルダという概念がありません。そのため、パッケージでインストールしたクラスを sf project retrieve で手元に取得すると、すべて classes/ 直下にフラットに落ちてきます。

ApexEloquent v4.0.0 / ApexBlueprint v2.2.0 / ApexTrace v1.6.0 / ApexTools v1.2.0 以降、全クラスが自分の置き場所を @directory doc コメントタグとして持っています。retrieve のあとに npm モジュール ApexLibrarian を 1 回実行するだけで、submodule 導入時と同一のディレクトリ階層に戻せます。

BASH
npx apex-librarian arrange

.cls-meta.xml も必ずペアで移動します。仕組みと他のコマンド (check / stamp) の説明もリンク先にまとめています。

Next steps