如何用JSDoc标注Mocha before钩子中TestContext字段以获IDE自动补全

你需要通过类型标注让IDE识别Mocha测试上下文（this）的结构，从而提供自动补全和文档提示。以下是针对JavaScript和TypeScript项目的解决方案：

方案一：JavaScript项目用JSDoc标注 #

直接通过JSDoc定义测试上下文的类型结构，让IDE识别this的字段：

/**
 * @typedef {Object} TestContext
 * @property {ExpensiveThing} expensiveThingUsedForTheTests - 测试用的昂贵资源，在before钩子中初始化
 */

describe('🔥Awesome Test Code🔥', /** @this {TestContext} */ async function()
{
  /** A super expensive thing that each unit test needs. **/
  class ExpensiveThing { expensive = true; }

  /**
   * Run this once before the first test in this describe block.
   */
  before('the first test', /** @this {TestContext} */ async function()
  {
    this.expensiveThingUsedForTheTests = new ExpensiveThing();
  });

  it('should be easy', /** @this {TestContext} */ async function(){
    // 此时IDE会自动补全字段并显示文档
    this.expensiveThingUsedForTheTests.expensive = false;
    assert.equal(this.expensiveThingUsedForTheTests.expensive, false, 'This was not easy!');
  });
});

关键说明： #

1. 用@typedef定义TestContext类型，通过@property标注每个字段的类型和说明
2. 在describe、before、it的函数上添加/** @this {TestContext} */，指定该函数内this的类型
3. 这样IDE就能识别this的结构，提供自动补全和文档提示（按下CTRL+Q可查看字段说明）

方案二：TypeScript项目用接口扩展 #

直接扩展Mocha的内置Context接口，让类型系统自动识别上下文字段：

import { describe, before, it } from 'mocha';
import assert from 'assert';

/** A super expensive thing that each unit test needs. **/
class ExpensiveThing { expensive = true; }

// 扩展Mocha上下文，添加自定义字段
interface TestContext extends Mocha.Context {
  /** 测试用的昂贵资源，在before钩子中初始化 */
  expensiveThingUsedForTheTests: ExpensiveThing;
}

describe('🔥Awesome Test Code🔥', async function(this: TestContext)
{
  before('the first test', async function(this: TestContext)
  {
    this.expensiveThingUsedForTheTests = new ExpensiveThing();
  });

  it('should be easy', async function(this: TestContext){
    // TypeScript和IDE会自动提供补全与文档
    this.expensiveThingUsedForTheTests.expensive = false;
    assert.equal(this.expensiveThingUsedForTheTests.expensive, false, 'This was not easy!');
  });
});

关键说明： #

1. 定义TestContext接口继承Mocha.Context，添加自定义字段和类型注释
2. 在每个Mocha函数中通过this: TestContext指定上下文类型
3. TypeScript会自动校验字段类型，IDE也会提供完整的自动补全和文档提示

IDE配置注意事项 #

• IntelliJ/WebStorm：确保启用了「JavaScript」或「TypeScript」的类型提示功能（默认已开启）
• VSCode：安装Mocha Test Explorer和TypeScript Language Features插件，确保项目的类型配置正确

内容的提问来源于stack exchange，提问作者Luke Machowski