Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Documentation testsの恩恵 / Documentation testing ...
Search
TOMIKAWA Sotaro
May 11, 2024
Programming
2
1.1k
Documentation testsの恩恵 / Documentation testing benefits
TSKaigi 2024
の発表資料です
TOMIKAWA Sotaro
May 11, 2024
Tweet
Share
More Decks by TOMIKAWA Sotaro
See All by TOMIKAWA Sotaro
漸進。
ssssota
0
2.9k
Preact、HooksとSignalsの両立 / Preact: Harmonizing Hooks and Signals
ssssota
1
2.8k
useSyncExternalStoreを使いまくる
ssssota
6
5.7k
React CompilerとFine Grained Reactivityと宣言的UIのこれから / The next chapter of declarative UI
ssssota
8
5.4k
新しいAPI createRawSnippet触ってみた / What is the createRawSnippet?
ssssota
2
210
脱法Svelte / Evasion of svelte rules
ssssota
1
230
TypeScriptとDocumentaion tests / Documentation tests with TypeScript
ssssota
8
4k
Svelteでライブラリを作る / Make your library with Svelte
ssssota
0
180
現代のReactivityとSvelteの魔法
ssssota
0
2.3k
Other Decks in Programming
See All in Programming
なぜ今、Terraformの本を書いたのか? - 著者陣に聞く!『Terraformではじめる実践IaC』登壇資料
fufuhu
4
670
ゲームの物理
fadis
5
1.5k
WebAssemblyインタプリタを書く ~Component Modelを添えて~
ruccho
1
920
GUI操作LLMの最新動向: UI-TARSと関連論文紹介
kfujikawa
0
1k
私の後悔をAWS DMSで解決した話
hiramax
4
150
KessokuでDIでもgoroutineを活用する / Go Connect #6
mazrean
0
120
あのころの iPod を どうにか再生させたい
orumin
2
2.5k
マイコンでもRustのtestがしたい その2/KernelVM Tokyo 18
tnishinaga
2
2.3k
TanStack DB ~状態管理の新しい考え方~
bmthd
2
340
Claude Codeで実装以外の開発フロー、どこまで自動化できるか?失敗と成功
ndadayo
2
1.5k
オープンセミナー2025@広島「君はどこで動かすか?」アンケート結果
satoshi256kbyte
0
210
コーディングは技術者(エンジニア)の嗜みでして / Learning the System Development Mindset from Rock Lady
mackey0225
2
580
Featured
See All Featured
Bash Introduction
62gerente
614
210k
Documentation Writing (for coders)
carmenintech
73
5k
Into the Great Unknown - MozCon
thekraken
40
2k
Practical Orchestrator
shlominoach
190
11k
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
PRO
185
54k
Keith and Marios Guide to Fast Websites
keithpitt
411
22k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
46
7.6k
No one is an island. Learnings from fostering a developers community.
thoeni
21
3.4k
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
The World Runs on Bad Software
bkeepers
PRO
70
11k
The Art of Programming - Codeland 2020
erikaheidi
55
13k
How To Stay Up To Date on Web Technology
chriscoyier
790
250k
Transcript
Documentation testsの恩恵 ssssota
自己紹介 冨川宗太郎 Tomikawa Sotaro (ssssota) { GitHub: "ssssota", X: "ssssotaro"}
フロントエンドエンジニア sは合計4つ
突然ですがこちらのコードをご覧ください
/// ``` /// use biome_unicode_table::is_js_ident; /// /// assert!(is_js_ident("id0")); /// assert!(is_js_ident("$id$"));
/// assert!(is_js_ident("_id_")); /// assert!(is_js_ident("𐊧")); /// /// assert!(!is_js_ident("")); /// assert!(!is_js_ident("@")); /// assert!(!is_js_ident("custom-id")); /// assert!(!is_js_ident("0")); /// ``` pub fn is_js_ident(s: &str) -> bool { if s.is_empty() { return false; Rust製Linter/Formatterである Biomeのコードを一部抜粋 ソースコード中のドキュメント に 関数の入出力が記載されている Rust(Cargo)にはデフォルトで 搭載されている機能で実際に利 用されている https://github.com/biomejs/biome/blob/7 245146125fa76c19780f68653092ed24fcdb717/ crates/biome_unicode_table/src/lib.rs#L4 2-L57
TypeScriptでは次のようなもの(vite-plugin-doctestの例) JSDocとして記載されたコメント内でassert関数を用い関数をテストしている それだけ /** * @example * ```ts @import.meta.vitest *
assert(add(1, 2) === 3); * ``` */ export const add = (a: number, b: number) => a + b; Documentation testsとは?
1. ソースコードのすぐそばに、テストコードが記載できる。 index.test.ts など別途ファイルを作成することなく、すぐにテストを書 き始めることができる。 2. ドキュメントに記載したコードを実行してその動作が保証できる。 ライブラリ等で、動かないサンプルコードを見たことが...。 3. 関数利用時にIDE(LSP)を介して「動作保証されたサンプルが閲覧できる」。
Documentation testsの恩恵
Documentation testsの恩恵 こんなシーンを見たことが... • ドキュメントにサンプルコードを書いても廃れる • そもそもJSDoc誰も読み書きしない... →実装のすぐとなりにテストコード(=JSDoc)を書くことで、 そもそもJSDocに触れる機会が増え、 それがサンプルコードとなり、生きたドキュメントになる。
ドキュメンテーションテストとの向き合い方 ドキュメンテーションテストは銀の弾丸(万能)ではない。 次のようなテストは向かない(書けない)。 • ライフサイクル関数が必要 • モックが必要 • UIテスト カジュアルにドキュメントおよびテストを書き始める手段の一つ。
いま型をカジュアルに書くように、 よりドキュメント/テストをカジュアルに書く世界。
npm i -D vitest vite-plugin-doctest import { defineConfig } from
'vitest/config'; import { doctest } from 'vite-plugin-doctest'; export default defineConfig({ plugins: [doctest()], // markdownファイルもサポートしている test: { includeSource: ['./src/**/*.[jt]s?(x)', './**/*.md'] }, }); npx vitest 導入方法(vite-plugin-doctest)
TypeScriptでは次のようなもの(vite-plugin-doctestの例) JSDocとして記載されたコメント内でassert関数を用い関数をテストしている それだけ /** * @example * ```ts @import.meta.vitest *
assert(add(1, 2) === 3); * ``` */ export const add = (a: number, b: number) => a + b; Documentation testsとは?
Documentation testsで 生きてるドキュメントとテストを書こう!