33-js-concepts 贡献实战指南用 Vitest 验证文档代码示例的测试规范与翻译流程【免费下载链接】33-js-concepts 33 JavaScript concepts every developer should know.项目地址: https://gitcode.com/GitHub_Trending/33/33-js-concepts本文基于 33-js-concepts 仓库的 CONTRIBUTING.md 展开系统讲解该项目如何以 Vitest 测试框架保障“文档中的每段代码示例都真实可运行”从三条 npm 测试命令的实际定义、tests/目录的分类组织方式到编写测试的六条硬性规范显式导入、断言转换、错误用例、浏览器 API 处理、严格模式注意再到新增语言翻译的完整流程和 MIT 许可约定。读完后你可以独立完成跑通全量测试、为新的概念文档编写配套测试、以及提交一个翻译 PR。项目定位与“文档即代码”的贡献模式33-js-concepts 是一个整理 JavaScript 核心概念的学习型仓库docs/目录下按 fundamentals、functions-execution、object-oriented、functional-programming、beyond 等分类存放 MDX 文档如 docs/concepts/call-stack.mdx、docs/concepts/promises.mdx而 CONTRIBUTING.md 明确了本项目的核心贡献约定——使用 Vitest 作为测试运行器用来验证文档中的代码示例工作正常This project uses Vitest as the test runner to verify that code examples in the documentation work correctly.这意味着仓库的贡献不是“写功能代码”而是“写文档 写能验证文档示例的测试”。仓库本身没有业务源码根目录的 index.js 只是一个包含项目说明的注释占位文件真正的质量保障体系全部落在tests/目录和测试配置上。运行测试三条命令与其在 package.json 中的真实定义CONTRIBUTING.md 给出三条测试命令# Run all tests once npm test # Run tests in watch mode (re-runs on file changes) npm run test:watch # Run tests with coverage report npm run test:coverage对照 package.json 的scripts字段可以确认每条命令背后的真实行为npm 命令实际执行的命令行为说明npm testvitest run一次性运行全部测试并退出适合 PR 前自检npm run test:watchvitest进入 watch 模式文件变化时自动重跑适合开发中边写边验证npm run test:coveragevitest run --coverage运行测试并输出覆盖率报告依赖vitest/coverage-v8提供与之一致的devDependencies声明为vitest:^4.0.16jsdom:^27.4.0用于少量 DOM 测试vitest/coverage-v8:^4.0.16test:coverage命令的支撑依赖另外两个值得注意的脚本是docscd docs npx mintlify dev与docs:buildcd docs npx mintlify build从 package.json 的 scripts 结构可以看出仓库同时承担文档站点基于 Mintlify的构建贡献者改完 MDX 后可以本地预览渲染效果。测试全局配置为什么必须显式 importvitest.config.js 的全部配置只有三项但它们直接决定了测试的写法import { defineConfig } from vitest/config export default defineConfig({ test: { include: [tests/**/*.test.js], globals: false, environment: node } })三个配置项的含义与影响include: [tests/**/*.test.js]只有tests/目录下以.test.js结尾的文件会被执行。这解释了 CONTRIBUTING.md 中“在tests/{concept-name}/下创建{concept-name}.test.js”的命名约定——文件名不匹配这个 glob 就会被静默忽略。globals: falseVitest 不会把describe/it/expect挂到全局。这正是 CONTRIBUTING.md 第 2 条规范要求“使用显式导入”的配置级原因import { describe, it, expect } from vitest任何测试文件缺少这行导入都会直接报describe is not defined而仓库中的 tests/fundamentals/call-stack/call-stack.test.js 第一行就是标准的显式导入写法。environment: node默认测试环境是 Node.js 而非浏览器这也是 CONTRIBUTING.md 第 5 条“跳过浏览器专属示例”的根据下文会讲到 DOM 测试的例外处理方式。tests/ 目录结构按概念组织并按知识域分层CONTRIBUTING.md 中给出的结构示意是扁平化的tests/ ├── call-stack/ │ └── call-stack.test.js ├── primitive-types/ │ └── primitive-types.test.js └── ...实际仓库在此基础上多做了一层按知识域分组当前tests/的真实组织是“分类目录 / 概念目录 / 测试文件”三层例如tests/ ├── fundamentals/ │ ├── call-stack/call-stack.test.js │ ├── primitive-types/primitive-types.test.js │ └── ... ├── functions-execution/ │ ├── event-loop/event-loop.test.js │ ├── promises/promises.test.js │ └── ... ├── object-oriented/ │ ├── this-call-apply-bind/this-call-apply-bind.test.js │ └── ... ├── functional-programming/ │ ├── recursion/recursion.test.js │ └── ... ├── web-platform/ │ ├── dom/dom.test.js │ └── http-fetch/http-fetch.test.js └── beyond/ ├── memory-performance/memoization/memoization.test.js ├── observer-apis/performance-observer/performance-observer.test.js └── ...可以推断外层分类fundamentals/、beyond/等与 docs/ 下的concepts/和beyond/concepts/文档分类保持对应贡献者在为新文档补测试时应把测试文件放进与文档一致的概念目录中而不是平铺在tests/根部。为代码示例编写测试六条规范逐条解析CONTRIBUTING.md 的“Writing Tests for Code Examples”给出了六条规范。下面逐条结合仓库实际代码展开使每条规范可操作、可验证。1. 文件命名tests/{concept-name}/{concept-name}.test.js文件名必须匹配vitest.config.js的includeglob且目录名与概念名一致。以调用栈为例tests/fundamentals/call-stack/call-stack.test.js 中的测试按主题组织成describe块Basic Function Calls、Nested Function Calls 等每条it的标题直接描述被验证的行为如should execute nested function calls and return correct greeting。2. 显式导入由globals: false强制要求见上文“测试全局配置”一节。CONTRIBUTING.md 给出的标准写法import { describe, it, expect } from vitest需要 mock 或生命周期钩子时按需补充导入例如 tests/beyond/browser-storage/cookies/cookies.dom.test.js 额外导入了beforeEach、afterEach和vi并在afterEach中用vi.restoreAllMocks()还原 mock这是多测试共享 DOM 状态时的标准清理姿势。3. 把 console.log 示例转成断言这是本仓库测试哲学的核心文档里// string这种注释式预期在测试中必须变成可执行的expect。CONTRIBUTING.md 给出的对照示例// Documentation example: // console.log(typeof hello) // string // Test: it(should return string type, () { expect(typeof hello).toBe(string) })实际仓库中的写法与之完全一致比如 call-stack 测试中it(should execute nested function calls and return correct greeting, () { function createGreeting(name) { return Hello, name ! } function greet(name) { const greeting createGreeting(name) return greeting } expect(greet(Alice)).toBe(Hello, Alice!) })即先完整搬入文档中的示例函数再对文档注释里写明的输出用toBe/toEqual断言。对对象、数组等复合结果使用toEqual深度比较对原始值使用toBe仓库中两种断言均有实例。4. 错误用例用toThrow()验证“应当抛出”的行为CONTRIBUTING.md 第 4 条对预期抛错的示例使用expect(() { ... }).toThrow()。典型场景是文档中讲解“访问 TDZ 中的变量会抛 ReferenceError”“调用Object.freeze后的属性赋值在严格模式下抛 TypeError”这类内容——测试代码把抛错本身当作断言对象从而保证文档描述的失败行为与运行时行为一致。5. 浏览器专属示例默认跳过需要时用 jsdom docblock因为environment: nodewindow/document/DOM相关示例默认不在 Node 测试中覆盖CONTRIBUTING.md 第 5 条。但仓库并没有完全放弃 DOM 测试对确实要验证浏览器 API 的文档如 cookies、DOM 操作、Observer 系列采用文件后缀 docblock 注释的方式单独标记例如 tests/beyond/browser-storage/cookies/cookies.dom.test.js/** * vitest-environment jsdom */ import { describe, it, expect, beforeEach, afterEach, vi } from vitest文件头部的vitest-environment jsdom注释会覆盖全局的node环境使该文件单独运行在 jsdom 中对应 devDependencies 里的jsdom这也解释了仓库中.dom.test.js与普通.test.js并存的双文件模式同一概念如 cookies会同时有 Node 环境可测的cookies.test.js与 jsdom 环境的cookies.dom.test.js。该文件还在beforeEach/afterEach中清理document.cookie与 mock保证 DOM 测试之间互不污染。6. 严格模式行为Vitest 下“静默失败”会变成 TypeErrorCONTRIBUTING.md 第 6 条提醒Vitest 以严格模式运行因此在非严格模式下“静默失败”的操作如给未声明变量赋值、修改只读属性在测试中会直接抛TypeError。写测试时要据此调整预期文档若演示非严格模式的宽松行为测试里要么用toThrow(TypeError)断言其失败要么改写示例本身使其在严格模式下成立。这与beyond/文档中 strict-mode 主题的内容相呼应。覆盖率用 test:coverage 检查示例覆盖情况npm run test:coverage即vitest run --coverage会基于vitest/coverage-v8输出覆盖率报告。对“文档示例 配套测试”的仓库而言覆盖率的意义在于核对文档里出现过、但没有对应测试的示例——它们是贡献者可以补齐的空白点。创建新翻译完整流程与格式约定CONTRIBUTING.md 的“Creating a New Translation”给出了八步流程全部步骤与格式约定如下翻译工作针对的是整个文档仓库而非当前仓库的代码Fork 主仓库leonardomso/33-js-concepts将主仓库加入 watch 列表保持与上游同步在自己的 fork 中完成翻译在主仓库的 README.md 中编辑链接指向你的翻译仓库在Community区块按固定格式新增一行格式Your language in native form (English name) — Your Name文档给出的示例[日本語 (Japanese)](https://github.com/oimo23/33-js-concepts) — oimo23创建 Pull Request命名格式为Add *your language here* translation.等待合并。仓库根目录另有 TRANSLATIONS.md 汇总现有翻译docs/translations.mdx 则提供文档站内的翻译入口README.md 也声明该指南已被翻译为 40 语言README 的 Community 区块即为翻译链接的挂载位置。许可约定贡献即接受 MITCONTRIBUTING.md 末尾明确By contributing, you agree that your contributions will be licensed under the MIT license.即任何贡献文档、测试、翻译一经提交即视为以 LICENSE 中的 MIT 协议授权。这一点在提交 PR 前需要知悉——MIT 是宽松协议允许自由使用、修改与再分发但对贡献者的实际约束主要体现在不附带担保、贡献内容归入项目统一的 MIT 授权之下。贡献前自检清单结合 CONTRIBUTING.md 与仓库实际配置提交前可按以下清单自查测试文件位置正确tests/{分类}/{concept-name}/{concept-name}.test.js文件名匹配tests/**/*.test.js第一行显式导入import { describe, it, expect } from vitestglobals: false下不可省略文档示例全部转为断言原始值用toBe复合结构用toEqual抛错行为用toThrow()浏览器 API 处理得当Node 测试跳过 DOM 示例确需 DOM 验证时使用vitest-environment jsdomdocblock 并妥善清理全局状态严格模式预期确认示例在严格模式下的行为与文档描述一致本地跑通npm test一次性全量通过开发过程可用npm run test:watch合并前用npm run test:coverage查看覆盖情况翻译类 PRREADME 的 Community 区块格式与 PR 命名符合约定。这套“文档示例 Vitest 断言”的组合使 33-js-concepts 的每个代码片段都不只是“看起来能跑”而是被测试持续验证的行为契约——这也是贡献者理解并参与该项目最重要的机制。【免费下载链接】33-js-concepts 33 JavaScript concepts every developer should know.项目地址: https://gitcode.com/GitHub_Trending/33/33-js-concepts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考