readme-assert
将README中的代码块作为测试运行，确保文档示例永不失效。
安装使用
复制下面这段提示词发给你的 AI（Claude / Cursor / TRAE / Codex / WorkBuddy 等），它会自动帮你完成安装：
帮我安装这个 AI Skill：readme-assert。 它的用途是：将README中的代码块作为测试运行，确保文档示例永不失效。 详细介绍见：https://321skill.com/skills/readme-assert/ 请根据该页面的说明完成安装。
使用示例
“帮我在README中为这个计算函数添加一个可测试的代码示例。” 它会引导你编写带有 `//=>` 断言注释的代码块。然后，你可以运行 `npx readme-assert` 来验证这个示例是否与你的代码实现一致，确保文档永远正确。
介绍
readme-assert 解决了一个常见痛点：随着项目迭代，README文档中的代码示例很容易与实际代码脱节，导致文档过时或错误。它允许开发者在Markdown代码块中直接编写可执行的测试用例，通过简单的注释断言来验证代码行为，从而确保文档示例的准确性和可靠性。
使用方式非常直观：在README文件的代码块标记中添加 test 标签，并在代码行后使用 //=> 注释来声明预期输出或异常。然后，只需运行 npx readme-assert 命令，工具便会自动执行这些代码块并验证断言。它还支持自动发现模式，能识别所有包含断言注释的代码块，无需手动标记。
这个工具特别适合开源库的维护者、全栈开发者以及任何需要撰写高质量技术文档的工程师。它能将文档编写与代码测试无缝结合，提升项目的可信度和维护效率。
建议在项目的持续集成（CI）流程中集成 readme-assert，这样每次代码提交都会自动验证文档示例。注意，它主要面向JavaScript/TypeScript生态，虽然能处理TypeScript语法，但核心是执行而非类型检查。对于复杂的集成测试，仍需依赖专门的测试框架。
核心特点
与普通单元测试框架不同，readme-assert 将测试直接嵌入在文档的代码示例中，实现了文档即测试（Docs-as-Tests）。它能自动重写对自身包的导入语句，指向本地源代码，确保测试的是最新实现而非已发布的包。
注意事项
主要适用于验证JavaScript/TypeScript代码示例，不适合复杂的端到端测试或非代码类的文档验证。
常见问题
readme-assert 支持哪些断言类型？
支持值断言（//=>）、抛出错误断言（//=> ErrorType）、异步断言、控制台输出断言等，详细语法请查阅官方文档。
它能和现有的测试框架（如Jest）一起用吗？
可以，它是独立的工具，专注于文档示例验证，可以与Jest等框架并行使用，互不冲突。