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
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.5k
Preact、HooksとSignalsの両立 / Preact: Harmonizing Hooks and Signals
ssssota
1
2.7k
useSyncExternalStoreを使いまくる
ssssota
6
5.5k
React CompilerとFine Grained Reactivityと宣言的UIのこれから / The next chapter of declarative UI
ssssota
8
5.2k
新しいAPI createRawSnippet触ってみた / What is the createRawSnippet?
ssssota
2
190
脱法Svelte / Evasion of svelte rules
ssssota
1
210
TypeScriptとDocumentaion tests / Documentation tests with TypeScript
ssssota
8
3.9k
Svelteでライブラリを作る / Make your library with Svelte
ssssota
0
160
現代のReactivityとSvelteの魔法
ssssota
0
2.2k
Other Decks in Programming
See All in Programming
Code as Context 〜 1にコードで 2にリンタ 34がなくて 5にルール? 〜
yodakeisuke
0
120
Kotlin エンジニアへ送る:Swift 案件に参加させられる日に備えて~似てるけど色々違う Swift の仕様 / from Kotlin to Swift
lovee
1
260
ruby.wasmで多人数リアルタイム通信ゲームを作ろう
lnit
3
420
AI時代のソフトウェア開発を考える(2025/07版) / Agentic Software Engineering Findy 2025-07 Edition
twada
PRO
61
17k
PHP 8.4の新機能「プロパティフック」から学ぶオブジェクト指向設計とリスコフの置換原則
kentaroutakeda
2
740
プロダクト志向ってなんなんだろうね
righttouch
PRO
0
180
WebViewの現在地 - SwiftUI時代のWebKit - / The Current State Of WebView
marcy731
0
110
LT 2025-06-30: プロダクトエンジニアの役割
yamamotok
0
700
来たるべき 8.0 に備えて React 19 新機能と React Router 固有機能の取捨選択とすり合わせを考える
oukayuka
2
890
Select API from Kotlin Coroutine
jmatsu
1
220
20250704_教育事業におけるアジャイルなデータ基盤構築
hanon52_
5
640
0626 Findy Product Manager LT Night_高田スライド_speaker deck用
mana_takada
0
150
Featured
See All Featured
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
233
17k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
231
53k
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
26
2.9k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
44
2.4k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
34
5.9k
Code Reviewing Like a Champion
maltzj
524
40k
Why Our Code Smells
bkeepers
PRO
337
57k
No one is an island. Learnings from fostering a developers community.
thoeni
21
3.4k
Rails Girls Zürich Keynote
gr2m
94
14k
A designer walks into a library…
pauljervisheath
207
24k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
34
3.1k
Adopting Sorbet at Scale
ufuk
77
9.4k
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で 生きてるドキュメントとテストを書こう!