如何構建可運行的JavaScript規范

這篇文章給大家分享的是有關如何構建可運行的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命令時，您應該看到使用它們各自顏色的結果。

感謝各位的閱讀！關于如何構建可運行的JavaScript規范就分享到這里了，希望以上內容可以對大家有一定的幫助，讓大家可以學到更多知識。如果覺得文章不錯，可以把它分享出去讓更多的人看到吧！