Unit Test the Docs: Why You Should Test Your Code Examples
summary
Argues that code examples must be executable and kept as a single source of truth by extracting them from tests and transcluding into docs, using the realm node.js sdk and jest assertions, running CI checks via GitHub Actions, and generating snippet files with bluehawk. Describes two flows copy paste versus extract and transclude, reports 41 contributors across eight SDKs and over 2,000 code examples, and shows a CLI build that produces committed, reproducible snippet files.
AI-written summary · about
chapters (14)
- 0:00Start
- 1:59Unit Tests & Code Examples
- 4:12Challenges Documenting Code Examples
- 8:57Considerations
- 10:14When to test code examples
- 12:10Implementation
- 13:34Copy Code Example
- 18:02Bluehawk: A Brief History
- 19:56Bluehawk Walkthrough
- 24:01Add Code Example to Unit Test
- 24:19Annotate Unit Test with Code to Extract
- 28:14Continuous Integration
- 28:55Why CI Test Code Examples
- 30:22Why Unit Test Code Examples
related talks
25mTesting: it's not just for code anymore
19mWhere Docs, Cloud-hosted Interactive Tutorials and CI Testing Intersect
38mDocs as Tests: A Strategy for Resilient Docs
41mTesting that the code does what the code does
08mExample-driven development: bridging tests and documentation
16mA unit test walks into a bar
37mKeeping trust: Testing documentation as part of a continuous integration process
37mDelicious Controversy: Docs & Tests