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 benefits
Search
TOMIKAWA Sotaro
May 11, 2024
Programming
1
620
Documentation testsの恩恵 / Documentation testing benefits
TSKaigi 2024
の発表資料です
TOMIKAWA Sotaro
May 11, 2024
Tweet
Share
More Decks by TOMIKAWA Sotaro
See All by TOMIKAWA Sotaro
脱法Svelte / Evasion of svelte rules
ssssota
1
30
TypeScriptとDocumentaion tests / Documentation tests with TypeScript
ssssota
7
2.9k
Svelteでライブラリを作る / Make your library with Svelte
ssssota
0
64
現代のReactivityとSvelteの魔法
ssssota
0
1.4k
型付きdotenv
ssssota
0
170
Other Decks in Programming
See All in Programming
新年度から始めるJava言語のファーストステップ2024
tatsuya1bm
0
150
Svelte採用記 - 位置情報と可視化の会社で、全社の標準技術スタックに選ぶまで / Svelte Japan Online Meetup #3
sorami
2
210
GitHub Actionsの痒いところを埋めるサードパーティーランナー
dora1998
2
350
The test code generator using static analysis and LLM
mikik0
1
550
AFUP Day Lyon 2024 - DDD !== Archi hexagonale
bgalati
0
190
Swift Attributes
hokuron
0
130
Using "modern" Ruby to build a better, faster Homebrew
mikemcquaid
3
720
Goでリフレクションする、その前に / Kansai.go #1
utgwkk
4
510
HonoのRPCで真の型安全が欲しかった
kosei28
1
210
It’s about time to pack Ruby and Ruby scripts in one binary
ahogappa0613
1
1.3k
Embedding it into Ruby code
soutaro
3
3.2k
BQで天気基盤をつくって、役立つ情報を可視化してみた!
wakamatsu_takumu
4
640
Featured
See All Featured
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
34
6.1k
Optimizing for Happiness
mojombo
372
69k
Testing 201, or: Great Expectations
jmmastey
30
6.8k
Typedesign – Prime Four
hannesfritz
36
2.1k
The MySQL Ecosystem @ GitHub 2015
samlambert
244
12k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
117
18k
BBQ
matthewcrist
80
8.8k
How GitHub Uses GitHub to Build GitHub
holman
469
290k
How to name files
jennybc
65
94k
Practical Orchestrator
shlominoach
183
9.8k
The Brand Is Dead. Long Live the Brand.
mthomps
49
32k
Understanding Cognitive Biases in Performance Measurement
bluesmoon
12
1.1k
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で 生きてるドキュメントとテストを書こう!