calmjs.dev 2.3.0

替代安装方法（针对开发者和高级用户）

calmjs.dev 的开发仍在进行中，为了获取最新功能和错误修复，可能需要开发版本。但是，为了使源安装正确运行，calmjs 软件包必须在当前环境中可用，以便正确生成所有包元数据。随着最近版本的 pip 和 setuptools 正确支持 setup_requires 关键字，以下命令应确保在 pip 尝试设置此包之前，calmjs 可用。可以使用以下命令安装此软件包的最新开发版本：

$ pip install git+https://github.com/calmjs/calmjs.dev.git#egg=calmjs.dev

或者，可以手动克隆 git 仓库并手动运行命令，例如

$ git clone https://github.com/calmjs/calmjs.dev.git
$ cd calmjs.dev
$ pip install -e .

如果在源安装 calmjs.dev 之前没有使 calmjs 可用，将导致此软件包的关键 Node.js 依赖项未正确定义。可以通过在基于源安装的根目录下使用以下内容来纠正它们

$ python setup.py egg_info

如果没有错误信息表明某些关键字的使用失败，则运行测试（在下节中记录）以确保软件包正常运行。

安装 Node.js 外部依赖项

由于此软件包集成了多个 Node.js 软件包以实现与该环境的集成所需的功能，因此可以通过包含的 npm 命令使用 calmjs 可执行文件将此软件包所需的 Node.js 软件包安装到当前工作目录。

$ calmjs npm --install calmjs.dev

测试安装

最后，为了验证 calmjs.dev 安装的成功，可以通过以下命令执行包含的测试

$ python -m unittest calmjs.dev.tests.make_suite

但是，如果遵循了将外部 Node.js 依赖项安装到当前目录的步骤，则可以将当前目录指定为 CALMJS_TEST_ENV 环境变量。在 POSIX 兼容的 shell 中，可以从该目录中执行以下操作

$ CALMJS_TEST_ENV=. python -m unittest calmjs.dev.tests.make_suite

请注意，在 Karma 执行期间可能会出现许多失败；这是正常的，因为这些是涉及模拟失败的测试，以确保在真实测试失败时正确处理错误。

使用 RequireJS

例如，开发者可能通过 calmjs.rjs 执行 r.js 工具，使用如下命令从他们的 Python 项目创建 AMD 包：

$ calmjs rjs example.package

上述命令会将 Python 包 example.package 提供的所有 JavaScript 代码打包成一个 AMD 包文件，通过 r.js 完成。由于 example.package 可能还为其 JavaScript 代码提供测试（自然是用 JavaScript 编写的），因此它可以通过所选包提供的 karma 测试运行器执行。命令就像在工具链运行时之前添加 karma 一样简单，如下所示：

$ calmjs karma rjs example.package

这将对 rjs 工具链运行时应用测试建议并调用它。通常，在完成打包之前，测试将对构建目录中的转译源代码执行。请注意，测试建议也由 calmjs.rjs 实现，以确保此测试工作流程得到适当集成。

关于 webpack

对于 calmjs.webpack 也是一样，它对 webpack 的支持也是通过类似的机制提供的，因此以下命令将通过 karma 的典型 webpack 调用方法执行包的测试：

$ calmjs karma webpack example.package

跳过构建工件

如果测试结束后（无论成功或失败）不希望生成工件或打包文件，则可以在 karma 命令中应用 -T 或 --only-test 标志，如下所示：

$ calmjs karma -T webpack example.package
$ calmjs karma --only-test rjs example.package

使用现有测试轻松测试生成的包工件

要针对预生成的工件文件运行测试，calmjs.dev 为 karma 命令提供了一种特定的代理工具链运行时，可用于实现此目的。例如，给定一个工件文件（例如 bundle.js），可以使用同一个包提供的测试来测试它是否正确地包含了 example.package 生成的/提供的 JavaScript 代码，以下命令：

$ calmjs karma run \
    --artifact=bundle.js \
    --test-with-package=example.package

然而，对于更复杂的工具链和包，这可能不起作用，因为这些工件通常涉及额外的可选建议。为了解决这个问题，可以应用 --toolchain-package 标志，它类似于某些工具链的 --optional-advice 标志。对于 calmjs.rjs，这是必要的。完整的命令可能如下所示：

$ calmjs karma run \
    --artifact=bundle.js \
    --test-with-package=example.package \
    --toolchain-package=calmjs.rjs

对于 webpack 也是一样；如果选定的工件文件是通过 calmjs webpack 生成的，可以使用以下方法进行测试：

$ calmjs karma run \
    --artifact=bundle.js \
    --test-with-package=example.package \
    --toolchain-package=calmjs.webpack

与所有 calmjs 工具一样，可以通过在每个运行时命令后附加 -h 或 --help 来获取更多帮助，例如 calmjs karma -h 或 calmjs karma run -h。将 -h 标志替换为 -V 将报告与相应运行时关联的底层包的版本信息。

有关与工件相关的测试的更多信息

可以通过在 karma 运行器上直接指定 --artifact 标志；这会导致能够测试由特定 Python 模块导出的有限或显式映射的 JavaScript 源代码。这意味着，而不是构建和测试与给定模块一起的所有依赖模块，所有这些依赖都可以作为一个单独的完整工件应用到测试环境中。这会从构建目录中删除依赖源，使得覆盖率报告不再显示，同时还测试了工件是否与测试源兼容。以下是一个使用 nunja.stock 包的例子，该包需要 nunja

$ calmjs rjs nunja
$ calmjs karma --coverage --artifact=nunja.js --cover-test \
    rjs nunja.stock --sourcepath-method=explicit

第一个命令生成了工件文件 nunja.js，然后立即被后续命令使用，该命令显式过滤掉所有未指定的其他源。否则，标准方式是将依赖项也包含到测试中，并生成结果工件文件。 --cover-test 标志表示测试覆盖率报告应扩展到提供的测试。类似地，启用 --cover-artifact 标志将扩展覆盖率报告到测试运行期间包含的工件。

测试为包定义的预构建工件

通过使用 calmjs.artifacts 注册系统定义和生成的包级别工件可以通过 calmjs artifact karma 工具进行测试，如果 calmjs.artifacts 注册表中的工件条目在 calmjs.artifacts.tests 注册表中也对应有记录。通常，引用工件条目的入口点的模块将由提供构建入口点的工具链包进行文档记录。如果测试包中的工件已创建，并且包有适合测试目的的良好定义的条目，则可以执行以下命令来测试定义和生成的工件

$ calmjs artifact karma example.package

有些情况下，测试执行可能需要从其他包中获取测试源；这种情况对于依赖包尤其有效，其中开发人员想要确保他们通过其开发的扩展（由其包提供）对其依赖所做的更改不会对现有功能产生负面影响。该功能通过 --test-with-package 标志实现，可以用来指定工件应从哪个包中获取测试。

$ calmjs artifact karma example.package \
    --test-with-package example.dependent

上述命令将使用 karma 执行 example.dependent 包提供的测试，以针对 example.package 定义的工件。如果工件正确构建，没有新的代码破坏由 example.dependent 包提供的现有功能，则所有测试都应该通过。

请注意，--test-with-package 标志覆盖了将提供测试以测试工件的源包列表。

如果需要在将包工件包含到测试运行器之前添加额外的工件（例如，测试工件可能引入到包工件中的潜在冲突），可以使用 --artifact 标志进行指定；指定的工件将被添加到构建器为测试执行提供的工件列表的前面。

错误：没有“framework:mocha”的提供者！（解析：framework:mocha）

此错误的可能原因是，为此包指定的 npm 依赖项在当前的 Node.js 环境中不可用。请在再次尝试之前确保已安装。一种方法是，在 calmjs npm 安装命令前添加 calmjs.dev，例如：

$ calmjs npm --install calmjs.dev ...

或者，包开发者可以为需要此包的额外功能创建包，并指导对该包的开发感兴趣的下游用户启用该额外标志来安装和使用该包。例如，nunja 就支持这一点。

$ calmjs npm --install nunja[dev]

ERROR [插件]：“karma-…” 插件：...

某些插件的特定消息可能导致测试运行器无法执行任何测试。这通常是由于 karma 测试运行器的某些版本无法干净地处理在 node_modules 目录中可用的行为不当的插件。如果引号内显示的插件（以 karma- 开头）对于测试的执行不是必需的，则应将其删除，然后再次执行测试命令。

UserWarning: 未知分布选项：‘package_json’

如果当前环境中尚未安装 calmjs，则使用开发方法安装将显示上述消息。请重新安装或通过运行以下命令重新生成元数据：

$ python setup.py egg_info

在 calmjs.dev 源目录的根目录中，以确保此包的正确行为。