详解构建可运行的JavaScript规范的方法

编程不仅仅是给计算机下达如何完成一项任务的指令，它还包括以一种精确的方式与他人交流思想，甚至是与未来的自己。这样的交流可以有多个目标，也许是为了共享信息，或者只是为了更容易地修改—如果你不理解或不记得很久以前做过什么，那么就很难修改。

当我们编写软件时，我们还需要确保代码具有预期的功能。虽然有定义语义的正式方法，但是最简单、最快速(但不那么严格)的方法是将该功能投入使用，并查看它是否产生预期的结果。

大多数开发人员都熟悉这些实践:代码文档作为注释来明确代码块的目标，以及一系列测试来确保函数给出所需的输出。

但是通常文档和测试是在不同的步骤中完成的。通过统一这些实践，我们可以为参与项目开发的任何人提供更好的体验。本文探讨了一个简单的程序实现，该程序可以运行既适用于文档编写又适用于测试的JavaScript规范。

我们将构建一个命令行界面，该界面将查找目录中的所有规范文件，提取每个规范中找到的所有断言，并计算它们的结果，最后显示哪些断言失败了，哪些断言通过了。

规范的格式

每个规范文件将从模板文本导出一个字符串。第一行可以作为规范的标题。模板文字将允许我们在字符串之间嵌入JS表达式，每个表达式将表示一个断言。要识别每个断言，我们可以用一个独特的字符开始行。

在本例中，我们可以使用bar字符(|)和破折号(-)的组合，破折号类似于旋转门符号，有时可以将其作为逻辑断言的符号表示。

下面是一个例子，对它的用法做了一些解释:

const dependency = require('./dependency')module.exports = `
  Example of a Specification File
  
  This project allows to test JavaScript programs using specification files.
  Every *.spec.js file exports a single template literal that includes a general
  explanation of the file being specified. Each file represents a logical
  component of a bigger system. Each logical component is composed of several
  units of functionality that can be tested for certain properties.
  Each one of this units of functionality may have one or more
  assertions. Each assertion is denoted by a line as the following:

  |- ${dependency} The dependency has been loaded and the first assert has
  been evaluated.

  Multiple assertions can be made for each file:

  |- ${false} This assertion will fail.

  |- ${2 + 2 === 4} This assertion will succeed.

  The combination of | and - will form a Turnstile ligature (|-) using the appropriate
  font. Fira Code is recommended. A Turnstile symbol was used by Gottlob Frege
  at the start of sentenses being asserted as true.

  The intended usage is for specification-first software. Where the programmer
  defines the high level structure of a program in terms of a specification,
  then progressively builds the parts conforming that specification until all
  the tests are passed. A desired side-effect is having a simple way to generate
  up-to-date documentation outside the code for API consumers.
`

现在让我们继续我们程序的高层结构。

我们程序的结构

我们的程序的整个结构可以在几行代码中定义，除了使用两个Node.js库来处理文件系统(fs)和目录路径(path)之外，没有任何依赖关系。在本节中，我们只定义程序的结构，函数定义将在下一节中给出。

#!/usr/bin/env node
const fs = require('fs')
const path = require('path')
const specRegExp = /\.spec\.js$/
const target = path.join(process.cwd(), process.argv[2])
// Get all the specification file paths
// If a specification file is provided then just test that file
// Otherwise find all the specification files in the target directory
const paths = specRegExp.test(target)
  ? [ target ]
  : findSpecifications(target, specRegExp).filter(x => x)
// Get the content of each specification file
// Get the assertions of each specification file
const assertionGroups = getAssertions(getSpecifications(paths))
// Log all the assertions
logAssertions(assertionGroups)
 
// Check for any failed assertions and return an appropriate exit code
process.exitCode = checkAssertions(assertionGroups)

因为这也是我们的CLI(命令行接口)的入口点，所以我们需要添加第一行shebang，它表示这个文件应该由节点程序执行。不需要添加特定的库来处理命令选项，因为我们只对单个参数感兴趣。但是，如果您计划以相当大的方式扩展此程序，则可以考虑其他选项。

要获得目标测试文件或目录，我们必须将执行命令的路径(使用process.cwd())与用户提供的参数作为执行命令时的第一个参数(使用process.argv[2])连接起来。

您可以在process对象的Node.js文档中找到对这些值的引用。通过这种方法，我们获得了目标目录/文件的绝对路径。

现在，我们要做的第一件事是找到所有的JavaScript规范文件。如第12行所示,我们可以使用条件运算符来提供更大的灵活性:如果用户提供了一个规范文件作为目标然后我们就直接使用,文件路径。

否则,如果用户提供了一个目录路径然后我们必须找到相匹配的所有文件模式specRegExp定义的常数,我们使用findSpecifications函数以后,我们将定义。这个函数将返回目标目录中每个规范文件的路径数组。

在第18行中，我们通过组合两个函数getspecification()和getassertion()来定义assertionGroups常量。首先获取每个规范文件的内容，然后从中提取断言。

我们稍后将定义这两个函数，现在只需要注意，我们使用第一个函数的输出作为第二个函数的参数，从而简化了过程，并在这两个函数之间建立了直接的联系。

虽然我们可以只有一个函数，通过拆分它们，我们可以更好地了解什么是实际的过程，但请记住，程序应该清晰易懂;仅仅做到这一点是不够的。

assertionsGroup常量的结构如下:

assertionGroup[specification][assertion]

接下来，我们将所有这些断言记录到用户日志中，以便使用logassertion()函数报告结果。每个断言将包含结果(true或false)和一个小描述，我们可以使用该信息为每种类型的结果赋予特殊的颜色。

最后，我们根据断言的结果定义退出代码。这将向流程提供关于程序如何结束的信息:流程是成功的还是失败了?退出码为0表示进程成功退出，如果失败则为1，或者在我们的示例中，当至少一个断言失败时为1。

查找所有规范文件

要找到所有的JavaScript规范文件，我们可以使用一个递归函数，该函数遍历用户作为CLI参数指定的目录。在搜索时，应该使用程序开始时定义的正则表达式(/\.spec\.js$/)检查每个文件，该表达式将匹配以.spec.js结尾的所有文件路径。

function findSpecifications (dir, matchPattern) {
  return fs.readdirSync(dir)
    .map(filePath => path.join(dir, filePath))
    .filter(filePath => matchPattern.test(filePath) && fs.statSync(filePath).isFile())
}

我们的findspecification函数接受一个目标目录(dir)和一个正则表达式，该正则表达式标识规范文件(matchPattern)。

获取每个规范的内容

由于我们导出的是模板文本，因此获取内容和计算后的断言非常简单，因此我们必须导入每个文件，当它被导入时，所有的断言都将自动进行计算。

function getSpecifications (paths) {
  return paths.map(path => require(path))
}

使用map()函数，我们使用节点的require函数将数组的路径替换为文件的内容。

从文本中提取断言

此时，我们有一个数组，其中包含每个规范文件的内容，并且已经计算了它们的断言。我们使用旋转门指示器(|-)来查找所有这些断言并提取它们。

function getAssertions (specifications) {
  return specifications.map(specification => ({
    title: specification.split('\n\n', 1)[0].trim(),
    assertions: specification.match(/^( |\t)*(\|-)(.|\n)*?\./gm).map(assertion => {
      const assertionFragments = /(?:\|-) (\w*) ((?:.|\n)*)/.exec(assertion)
 
      return {
        value: assertionFragments[1],
        description: assertionFragments[2].replace(/\n /, '')
      }
    })
  }))
}

这个函数将返回一个类似的数组，但是用一个如下结构的对象替换每个规范的内容:

title: <String: Name of this particular specification>,
  assertions: [
    {
      value: <Boolean: The result of the assertion>,
      description: <String: The short description for the assertion>
    }
  ]
}

标题是用规范字符串的第一行设置的。然后，每个断言都作为数组存储在断言键中。该值将断言的结果表示为布尔值。我们将使用这个值来知道断言是否成功。

此外，描述将显示给用户，作为识别哪些断言成功和哪些断言失败的方法。我们在每种情况下都使用正则表达式。

记录结果

我们沿着程序构建的数组现在有一系列JavaScript规范文件，其中包含一列找到的断言及其结果和描述，因此除了向用户报告结果之外，没有什么可做的。

{
  function logAssertions(assertionGroups) {
  // Methods to log text with colors
  const ansiColor = {
    blue: text => console.log(`\x1b[1m\x1b[34m${text}\x1b[39m\x1b[22m`),
    green: text => console.log(`\x1b[32m    ${text}\x1b[39m`),
    red: text => console.log(`\x1b[31m    ${text}\x1b[39m`)
  }
  // Log the results
  assertionGroups.forEach(group => {
    ansiColor.blue(group.title)
    group.assertions.forEach(assertion => {
      assertion.value === 'true'
        ? ansiColor.green(assertion.description)
        : ansiColor.red(assertion.description)
    })
  })
 
  console.log('\n')
}

我们可以根据结果使用颜色来格式化输入。为了在终端上显示颜色，我们需要添加ANSI转义码。为了在下一个块中简化它们的用法，我们将每种颜色保存为ansiColor对象的方法。

首先，我们要显示规范的标题，请记住，我们为每个规范使用数组的第一个维度，并将其命名为一组(断言)。然后，我们使用它们各自的颜色根据它们的值记录所有断言:绿色表示计算为true的断言，红色表示具有其他值的断言。

注意比较，我们检查true是否为字符串，因为我们从每个文件接收字符串。

检查结果

最后，最后一步是检查所有测试是否成功。

function checkAssertions (assertionGroups) {
  return assertionGroups.some(
    group => group.assertions.some(assertion => assertion.value === 'false')
  ) ? 1 : 0
}

我们使用数组的some()方法检查每个断言组(规范)，看看是否至少有一个值是' ' ' false ' ' '。我们嵌套了其中的两个因为我们有一个二维数组。

运行我们的程序

此时，我们的CLI应准备好运行一些JavaScript规范，并查看是否拾取并评估了断言。在test目录中，您可以从本文开头复制规范示例，并将以下命令粘贴到您的文件中：package.json

"scripts": {
  "test": "node index.js test"
  }

其中test是包含示例规范文件的目录的名称。

当运行npm test命令时，您应该看到使用它们各自颜色的结果。

相关免费学习推荐：js视频教程

更多编程相关知识，请访问：编程入门！！

Atas ialah kandungan terperinci 详解构建可运行的JavaScript规范的方法. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!