VSCode中CodeceptJS自定义步骤无法使用IntelliSense问题求助

问题现象 #

• MacOS下VSCode无法通过cmd+click跳转到自定义步骤文件中myAsyncFunction的定义
• IDE错误提示“Refactor this redundant 'await' on a non-promise”，但实际方法是异步函数
• 测试用例中调用自定义步骤时无IntelliSense支持，仅CodeceptJS原生函数正常，JetBrains系列IDE无此问题

解决方案 #

方案1：添加JSDoc类型注解

通过JSDoc明确自定义actor的类型结构，帮助VSCode语言服务识别方法类型：

/**
 * @typedef {Object} CustomActor
 * @property {(param: string) => Promise<void>} myAsyncFunction
 * @property {(param: string) => Promise<void>} myOtherFunction
 */

/**
 * @returns {CustomActor}
 */
module.exports = function() {
  return actor({
    async myAsyncFunction(param) {
      // 业务逻辑
    },

    async myOtherFunction(param) {
      await this.myAsyncFunction(param)
    }
  });
};

添加后VSCode将能识别异步方法的Promise返回值，消除冗余await提示，同时支持方法跳转和基本IntelliSense。

方案2：创建TypeScript类型声明文件

如果项目允许，创建codecept.d.ts类型声明文件扩展CodeceptJS的Actor接口：

declare namespace CodeceptJS {
  interface Actor {
    myAsyncFunction(param: string): Promise<void>;
    myOtherFunction(param: string): Promise<void>;
  }
}

将该文件放在项目根目录，VSCode会自动读取类型定义，为自定义步骤提供完整的IntelliSense、方法跳转支持，彻底解决类型识别问题。

额外配置建议

• 确保VSCode的JavaScript/TypeScript语言服务为最新版本（可通过Ctrl+Shift+P打开命令面板，选择TypeScript: Select TypeScript Version切换到最新内置版本）
• 若项目无jsconfig.json，可创建基础配置优化类型推断：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "strict": false
  },
  "include": ["./**/*.js", "./**/*.ts"]
}

内容的提问来源于stack exchange，提问作者Seth van Wyk