チュートリアル
コードと README が食い違っている小さなプロジェクトを作り、Veritas で食い違いと弱いテストを見つけます。そのあと仕様を決めてコードを直し、承認した計画で足りないテストを追加します。
必要なものは Node.js 25 以上(26 を推奨)、npm、git です。出力は [...] の箇所で省略しています。run ID、計画の ID、承認の ID、承認トークン、日時は、手元の出力では違う値になります。
プロジェクトを作る
mkdir shop-pricing && cd shop-pricing
git init次のファイルを作ります。
package.json:
{
"name": "shop-pricing",
"private": true,
"type": "module",
"scripts": {
"test": "vitest run"
}
}README.md:
# shop-pricing
Pricing rules for checkout. Amounts are integer yen.
## Discount
Orders with a total of 1000 or more receive a flat discount of 100.
## Shipping
Shipping is free for orders of 5000 or more. Otherwise shipping costs 500.src/pricing.ts。README は「1000 or more(1000 以上)」ですが、割引の条件は > になっています。
/** Flat discount applied at checkout. */
export function discountAmount(total: number): number {
if (total > 1000) {
return 100;
}
return 0;
}
/** Shipping fee for an order total. */
export function shippingFee(total: number): number {
return total >= 5000 ? 0 : 500;
}test/discount-weak.test.ts。境界の値を試していません。
import { expect, it } from 'vitest';
import { discountAmount } from '../src/pricing.js';
it('gives a discount on large orders', () => {
expect(discountAmount(2000)).toBe(100);
});
it('gives no discount on small orders', () => {
expect(discountAmount(10)).toBe(0);
});test/tautological.test.ts。コードを呼んでいません。
import { expect, it } from 'vitest';
it('pricing works', () => {
expect(true).toBe(true);
});test/shipping-boundary.test.ts。境界の両側を確かめています。
import { expect, it } from 'vitest';
import { shippingFee } from '../src/pricing.js';
it('charges shipping just below the threshold', () => {
expect(shippingFee(4999)).toBe(500);
});
it('ships free exactly at the threshold', () => {
expect(shippingFee(5000)).toBe(0);
});.gitignore:
node_modules/
.veritas/*
!.veritas/config.json
!.veritas/approvals.json
.mutator/依存を入れ、テストを実行して、コミットします。
npm install -D vitest @under18dev/veritas
npx vitest run
git add -A && git commit -m "Add pricing rules" Test Files 3 passed (3)
Tests 5 passed (5)discountAmount(1000) は 0 を返し、README は 100 と書いているのに、五つのテストはすべて通ります。
1. 設定ファイルを作る
npx veritas init --yeswrote [...]/shop-pricing/.veritas/config.json
detected: package manager=npm, tsconfig=none, vitest=5.1.1, git=true
next:
veritas doctor
veritas discover --offline
veritas run --profile quick --offline2. standard プロファイルで実行する
standard プロファイルは、静的解析に mutation testing を加えます。コードを少しずつ書き換えたもの(mutant)を作り、それぞれに対してテストを実行します。
npx veritas run --profile standardrun run-20261120T105459627Z-000-0ed704 verdict: pass_with_warnings (exit 0)
succeeded index
2 function(s) in 1 file(s); 6 inferred candidate(s)
succeeded discover
3 source(s), 3 statement(s), 0 network request(s)
succeeded spec
properties: {"proposed":8}; 0 conflict(s)
succeeded map
5 test(s), 4 symbol edge(s)
succeeded mutate
mutator 0.4.5: succeeded
counts: {"killed":16,"survived":1}
mutation.mode is "diff" but no --since ref was given: all mutants in scope were run
succeeded assess
assessments: {"weak_or_incomplete":2,"meaningful_with_evidence":2,"tautological_or_disconnected":1}; 3 finding(s)
succeeded report
formats: json, markdown, html, sarif
findings (3):
F-0b43c88cc3a6 [confirmed medium] no test detects total > 1000 -> total >= 1000 at src/pricing.ts:3
F-89435b62ae1e [suspected medium] src/pricing.ts#discountAmount may not satisfy "total >= 1000"
F-99e71509e3c4 [suspected low] test "pricing works" does not check project behaviour
note: 3 finding(s) to review (not policy failures)
explain a finding: veritas explain <finding-id>; artifacts: .veritas/runs/run-20261120T105459627Z-000-0ed704/各ステージの結果です。
discoverは三つの出典(README、src/pricing.tsのドキュメントコメント、git log)を読み、README から記述を三つ見つけました。specは Property を 8 個作りました。どれもproposedで、README から来たもの(normative)が二つ、コードから推測したものが六つです。mutateは 17 個の mutant を実行しました。total > 1000をtotal >= 1000に変えた mutant だけが生き残り、どのテストも失敗しませんでした。assessは、割引の二つのテストをweak_or_incomplete、送料の二つのテストをmeaningful_with_evidence、pricing worksをtautological_or_disconnectedと判定しました。
verdict は pass_with_warnings(終了コード 0)です。確認すべき finding はありますが、確定した仕様違反はまだありません。
F-0b43c88cc3a6は、mutation testing で確かめたのでconfirmedです。F-89435b62ae1eはsuspectedです。コードは README と同じ数でtotalを比べていますが、演算子が違います。README の Property はまだ accepted ではありません。F-99e71509e3c4は、何も確かめていないテストを指しています。
3. finding の根拠を見る
npx veritas explain F-89435b62ae1eF-89435b62ae1e [suspected medium] spec_implementation_mismatch
src/pricing.ts#discountAmount may not satisfy "total >= 1000"
documented: total >= 1000 (README.md:7)
implementation compares the same parameter against a different boundary
property status is proposed; accept it to make this a confirmed violation
source readme README.md:1 "# shop-pricing Pricing rules for checkout. Amounts are integer yen. ## Discount Orders with a total of 1000 or more rece"
quote line 7: "Orders with a total of 1000 or more receive a flat discount of 100."
property P-ee03e6e8b749 [proposed, normative] discountAmount: total >= 1000 -> Orders with a total of 1000 or more receive a flat discount of 100.
test test/discount-weak.test.ts:4 "gives a discount on large orders"
test test/discount-weak.test.ts:8 "gives no discount on small orders"
assess T-97fef42e4cf7: weak_or_incomplete - 1 specification-relevant mutant(s) it runs survived: src/pricing.ts:3 total > 1000 -> total >= 1000; boundary not exercised: total >= 1000 (decisive inputs 999, 1000; asserted: none)
assess T-8b4efcb90022: weak_or_incomplete - 1 specification-relevant mutant(s) it runs survived: src/pricing.ts:3 total > 1000 -> total >= 1000; boundary not exercised: total >= 1000 (decisive inputs 999, 1000; asserted: none)
[...]
mutant M-d24bb133285b [survived] src/pricing.ts:3 total > 1000 -> total >= 1000
[...]
next: review the property: veritas spec accept P-ee03e6e8b749 --reason "..." or veritas spec reject P-ee03e6e8b749 --reason "..."README の行から Property、discountAmount を呼ぶテストとその評価、mutant までが順に並びます。total >= 1000 の境界を決める入力は 999 と 1000 ですが、どちらのテストもこの値を assert していません。最後の行は次にすべきことで、README の規則を仕様にするかどうかを決めるよう促しています。
4. Property を一覧にする
npx veritas spec listP-ee03e6e8b749 proposed normative discountAmount: total >= 1000 -> Orders with a total of 1000 or more receive a flat discount of 100.
P-e3003339ad77 proposed normative shippingFee: total >= 5000 -> Shipping is free for orders of 5000 or more.
P-1ee7b6944b63 proposed inferred discountAmount: behaviour may change at total > 1000 (line 3); check total = 1000 and its neighbours
P-964a7a290508 proposed inferred discountAmount: behaviour for negative total (and zero)
P-b787b41cef0a proposed inferred discountAmount: behaviour for non-integer, NaN, ±Infinity and unsafe-integer values of total
P-621583d37a21 proposed inferred shippingFee: behaviour may change at total >= 5000 (line 11); check total = 5000 and its neighbours
P-2eead7f786cb proposed inferred shippingFee: behaviour for negative total (and zero)
P-d7372f0d4de0 proposed inferred shippingFee: behaviour for non-integer, NaN, ±Infinity and unsafe-integer values of totalnormative はドキュメントから、inferred はコードから来た Property です。inferred は確かめる対象の候補にすぎません。npx veritas spec show <id> で、一つの Property の出典、前提、形式モデルを確認できます。
5. 割引の規則を accepted にする
割引については README を仕様とする、と決めて記録します。
npx veritas spec accept P-ee03e6e8b749 --reason "README is the pricing specification"recorded accept of P-ee03e6e8b749 by you決定は .veritas/approvals.json に追記されます。名前(--actor、VERITAS_ACTOR、git config user.name の順に使います)、理由、日時が残ります。
{
"id": "A-7d000af7e5fa",
"propertyId": "P-ee03e6e8b749",
"propertyVersion": 1,
"decision": "accept",
"actor": "you",
"reason": "README is the pricing specification",
"decidedAt": "2026-11-20T10:55:08.580Z",
"sourceIds": ["src-fa35c6154f0b"]
}送料の規則は proposed のままにします。次の手順で、--include-proposed を付けたときの扱いを確かめます。
6. Z3 で規則を検査する
npx veritas prove --include-proposedrun run-20261120T105508829Z-000-017911 verdict: policy_failure (exit 1)
[...]
succeeded prove
P-ee03e6e8b749: counterexample_found {"total":"1000"}
P-e3003339ad77: proven_within_model
succeeded assess
assessments: {"weak_or_incomplete":2,"inconclusive":2,"tautological_or_disconnected":1}; 2 finding(s)
[...]
findings (2):
F-89435b62ae1e [confirmed high] src/pricing.ts#discountAmount does not satisfy "total >= 1000" for {"total":"1000"} (within the model)
F-99e71509e3c4 [suspected low] test "pricing works" does not check project behaviour
note: 1 confirmed specification violation(s)
[...]prove は、[-10000, 10000] の範囲に規則を破る total があるかを Z3 に問います。
- accepted にした割引の規則では、Z3 が
total = 1000を見つけました。Veritas が JavaScript でdiscountAmount(1000)を実行して同じ違反を確かめたので、finding はconfirmed highになりました。確定した違反は既定のポリシーで失敗になり、終了コードは1です。 - 送料の規則は
--include-proposedを付けたので検査され、範囲内に違反はありませんでした。accepted ではないので、この結果は実験的な扱いです。 - 送料のテストがこの実行で
inconclusiveなのは、proveが mutation testing を実行しないからです。
もう一度 explain を実行すると、ソルバーの結果が加わっています。
npx veritas explain F-89435b62ae1eF-89435b62ae1e [confirmed high] spec_implementation_mismatch
src/pricing.ts#discountAmount does not satisfy "total >= 1000" for {"total":"1000"} (within the model)
documented: total >= 1000 (README.md:7)
implementation compares the same parameter against a different boundary
solver counterexample {"total":"1000"} reproduced in JavaScript (C-8aad536f8e71)
[...]
claim C-8aad536f8e71 [conformance counterexample_found, none] {"total":"1000"}
smt: .veritas/runs/run-20261120T105508829Z-000-017911/proofs/C-8aad536f8e71.smt2
next: fix the implementation or change the specification through review
next: add a test for the counterexample input.smt2 のファイルはふつうの SMT-LIB なので、どの Z3 でも実行し直せます。
; veritas conformance query: is there an input in the domain that violates the property?
(set-logic ALL)
(set-option :timeout 30000)
(set-option :produce-models true)
(define-fun |discountAmount| ((|total| Int)) Int (ite (> |total| 1000) 100 0))
(declare-const |total| Int)
(assert (<= (- 10000) |total| 10000))
(assert (not (and (=> (>= |total| 1000) (= (|discountAmount| |total|) 100)) (=> (not (>= |total| 1000)) (= (|discountAmount| |total|) 0)))))
(check-sat)
(get-value (|total|))
(get-info :reason-unknown)7. テストの改善を計画させる
npx veritas improve --dry-runplan IP-c7176a11a5f3 from run-20261120T105508829Z-000-017911: needs_spec_decision
spec violation candidates (not added; expected values unchanged):
SVC-ec7787ca9234 discountAmount(1000) returns 0, but the specification (README.md:7) documents 100; the test is not added and its expected value is not changed
implementation fix proposals: .veritas/improvements/IP-c7176a11a5f3/implementation-fix-proposal.json
[...]
plan: .veritas/improvements/IP-c7176a11a5f3/plan.json (no project file was written)終了コードは 4 です。README から期待値 100 を取った discountAmount(1000) のテストは、今のコードでは失敗します。Veritas はこのテストを追加せず、期待値を 0 に変えることもしません。needs_spec_decision は、コードと README のどちらを直すかをあなたが決める必要がある、という意味です。
8. コードを直して、もう一度計画する
src/pricing.ts の total > 1000 を total >= 1000 に直し、設定と決定と一緒にコミットしてから、もう一度実行します。
git add -A && git commit -m "Apply the discount at 1000"
npx veritas run --profile standardrun run-20261120T105517747Z-000-01dbf1 verdict: pass_with_warnings (exit 0)
[...]
succeeded spec
properties: {"accepted":1,"proposed":7}; 0 conflict(s)
[...]
succeeded mutate
mutator 0.4.5: succeeded
counts: {"killed":16,"survived":1}
[...]
findings (2):
F-99e71509e3c4 [suspected low] test "pricing works" does not check project behaviour
F-e2324bef333e [confirmed medium] no test detects total >= 1000 -> total > 1000 at src/pricing.ts:3割引の規則は accepted のままで、仕様との食い違いはなくなりました。ただし、1000 を使うテストがないので、total >= 1000 -> total > 1000 の mutant が生き残っています。
npx veritas improve --dry-runplan IP-a14164357e16 from run-20261120T105517747Z-000-01dbf1: planned
goal: Add 1 test(s) whose expected values come from the specification and at decisive boundary inputs no test checks; applying measures which mutants they kill
proposed tests (expected values from the specification):
test/veritas-P-ee03e6e8b749.test.ts: discountAmount(1000) is 100
property P-ee03e6e8b749 (total >= 1000): the guarding condition holds for this input, so the specification documents 100
gaps:
F-e2324bef333e boundary of total >= 1000: total=1000 is not checked by an asserting test
budget: 3 iteration(s), 5 file(s), 900000 ms, 1 test retr(y/ies)
patch preview:
--- /dev/null
+++ b/test/veritas-P-ee03e6e8b749.test.ts
@@ -0,0 +1,8 @@
+// Added by `veritas improve` for property P-ee03e6e8b749.
+// Expected values come from the specification (README.md:7), not from the implementation.
+import { expect, it } from 'vitest';
+import { discountAmount } from "../src/pricing.js";
+
+it("discountAmount(1000) is 100 (boundary of the rule)", () => {
+ expect(discountAmount(1000)).toBe(100);
+});
skipped:
M-5b67ad8e53c8: no bounded equivalence check for this mutant
P-ee03e6e8b749 {"total":"999"}: the value for this input is only an assumption of the formal model, not stated by the source
approval token for plan IP-a14164357e16: 6735e5d7e6d641b5b63f74f6521d6564c6d4821e0c2acb07a2d33b628063f67b
apply after review: veritas improve --apply --plan IP-a14164357e16 --approve 6735e5d7e6d641b5b63f74f6521d6564c6d4821e0c2acb07a2d33b628063f67b
plan: .veritas/improvements/IP-a14164357e16/plan.json (no project file was written)計画は、新しいテストファイルを一つ加えるものです。期待値の 100 は README の 7 行目から取っています。README は 1000 未満について何も書いていないので、入力 999 は見送られています。
9. 計画を適用する
パッチを確認したら、自分の出力に表示された計画の ID とトークンで適用します。
npx veritas improve --apply --plan IP-a14164357e16 --approve 6735e5d7e6d641b5b63f74f6521d6564c6d4821e0c2acb07a2d33b628063f67battempt PA-ee6c6c6d4bc3 for plan IP-a14164357e16: improved
before: tests 5 passed / 0 failed, mutants 16 killed / 1 survived
after: tests 6 passed / 0 failed, mutants 17 killed / 0 survived
note: killed mutants 16 -> 17, survived 1 -> 0
note: newly killed: M-5b67ad8e53c8
note: added: test/veritas-P-ee03e6e8b749.test.ts
note: formal and property-based results re-evaluated in run-20261120T105528565Z-000-2f25ef on the patched copyVeritas はプロジェクトの一時コピーで効果を測ってから、新しいファイルを一つだけ書き込みました。git status には、追跡されていないファイルとして test/veritas-P-ee03e6e8b749.test.ts が表示されます。--apply の手順はテストの改善で説明しています。
10. deep プロファイルで実行する
npx veritas run --profile deeprun run-20261120T105531774Z-000-7ae803 verdict: pass_with_warnings (exit 0)
[...]
succeeded mutate
mutator 0.4.5: succeeded
counts: {"killed":17}
[...]
succeeded pbt
P-ee03e6e8b749: passed
succeeded prove
P-ee03e6e8b749: proven_within_model
1 formalized propert(y/ies) not verified: not accepted (use --include-proposed)
P-ee03e6e8b749 vs mutant M-aecdf503e7bd: detects it with {"total":"-1808"}
P-ee03e6e8b749 vs mutant M-846bcbfcb4da: detects it with {"total":"8796"}
P-ee03e6e8b749 vs mutant M-5b67ad8e53c8: detects it with {"total":"1000"}
P-ee03e6e8b749 vs mutant M-407cd213acfd: detects it with {"total":"4812"}
succeeded assess
assessments: {"weak_or_incomplete":2,"meaningful_with_evidence":3,"tautological_or_disconnected":1}; 1 finding(s)
[...]
findings (1):
F-99e71509e3c4 [suspected low] test "pricing works" does not check project behaviour- 17 個の mutant がすべて kill されました。
- fast-check は、記録したシードで、accepted な規則を 1000 個の入力で試しました。
- Z3 は
[-10000, 10000]の範囲に規則を破るtotalがないことを確かめ、表示された各 mutant について、規則が元のコードと区別できる入力を見つけました。 - 新しいテストは
meaningful_with_evidenceです。もとからある割引の二つのテストは、それ自体が境界を確かめていないのでweak_or_incompleteのままです。 pricing worksは何も確かめていません。直すか削除してください。
次に読むページ
- 結果の読み方:このページに出てきた状態の意味。
- 仕様の確定:食い違い、reject、
spec diff。 - 検証:Z3、fast-check、Lean。
- CI と GitHub Action:プルリクエストでの実行。