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
2
650
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
50
TypeScriptとDocumentaion tests / Documentation tests with TypeScript
ssssota
7
3k
Svelteでライブラリを作る / Make your library with Svelte
ssssota
0
66
現代のReactivityとSvelteの魔法
ssssota
0
1.5k
型付きdotenv
ssssota
0
180
Other Decks in Programming
See All in Programming
最初にもらったフロントのタスクは半年以上かかりました
mitsu0428
1
130
The state of Ruby tooling
vinistock
0
110
deadcode超解剖
kuro_kurorrr
1
280
EduBlocksでPythonのブロックプログラミング体験!
ueponx
0
310
DroidKnights 2024 : Compose Material3 커스텀 디자인 시스템 구축기
kwondae
0
190
KotlinConf 2024
feliciafaye
0
180
앱 성능 영혼까지 끌어올리기
veronikapj
0
440
The Final Frontier of Web Development: React Server Components vs Jakarta EE
ivargrimstad
0
1.1k
multipart/form-dataの省メモリパース / Go Conference 2024 Pre Party #gocon24_preparty
mazrean
0
260
Dive into gomock / Go Conference 2024
utgwkk
12
2.9k
DatadogでAPI毎のSQL発行数を可視化してN+1を改善した話
nealle
0
750
エンジニア向け 株式会社バックテック 会社紹介資料 / for Engineers
backtech
1
190
Featured
See All Featured
From Idea to $5000 a Month in 5 Months
shpigford
377
46k
A Modern Web Designer's Workflow
chriscoyier
689
190k
Debugging Ruby Performance
tmm1
70
11k
The Power of CSS Pseudo Elements
geoffreycrofte
63
5.1k
Ruby is Unlike a Banana
tanoku
96
10k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
228
16k
Designing for humans not robots
tammielis
247
25k
Why You Should Never Use an ORM
jnunemaker
PRO
51
8.7k
Design by the Numbers
sachag
276
18k
The Language of Interfaces
destraynor
151
23k
Documentation Writing (for coders)
carmenintech
61
4.1k
Building Applications with DynamoDB
mza
88
5.7k
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で 生きてるドキュメントとテストを書こう!