Как создать работоспособные спецификации JavaScript

Программирование — это не только предоставление компьютерам инструкций о том, как выполнить задачу, но и точное общение идей с другими людьми или даже с самим собой в будущем. Такое общение может преследовать несколько целей, например, делиться информацией или просто разрешать более простые изменения — трудно что-то изменить, если вы этого не понимаете или не помните, что вы делали давным-давно. Документация является ключевой, либо в виде простых комментариев в вашем коде, либо в виде целых документов, описывающих общую функциональность программы.

Когда мы пишем программное обеспечение, мы также должны убедиться, что код обладает предполагаемой функциональностью Хотя существуют формальные методы определения семантики , самый простой и быстрый (но менее строгий) способ — использовать эту функциональность и посмотреть, дает ли она ожидаемые результаты.

Большинство разработчиков знакомы с этими практиками: документирование кода в виде комментариев, чтобы четко указать цель блока кода, и серия тестов, чтобы убедиться, что функции дают желаемый результат.

Но обычно документирование и тестирование выполняются в разных шагах. Объединяя эти методы, мы можем предложить лучший опыт для всех, кто участвует в разработке проекта. В этой статье рассматривается простая реализация программы для запуска спецификаций JavaScript, которые подходят как для документации, так и для тестирования.

Мы собираемся создать интерфейс командной строки, который находит все файлы спецификаций в каталоге, извлекает все утверждения, найденные внутри каждой спецификации, и оценивает их результат, наконец, показывая результаты того, какие утверждения провалились, а какие пропущены.

Формат спецификации

Каждый файл спецификации экспортирует одну строку из литерала шаблона . Первая строка может быть взята в качестве заголовка спецификации. Шаблонный литерал позволит нам встраивать выражения JS между строкой, и каждое выражение будет представлять утверждение. Чтобы идентифицировать каждое утверждение, мы можем начать строку с отличительного символа, в этом случае мы можем использовать комбинацию символа бара ( | ) и тире ( - ), который напоминает символ турникета, который иногда можно найти как символический представление для логических утверждений.

Ниже приведен пример с некоторыми пояснениями по его использованию:

 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 , которая указывает, что этот файл должен выполняться программой node . Нет необходимости добавлять определенную библиотеку для обработки параметров команды, поскольку нас интересует только один параметр. Однако вы можете рассмотреть другие варианты, если планируете значительно расширить эту программу.

Чтобы получить целевой тестовый файл или каталог, мы должны объединить путь, по которому была выполнена команда (используя process.cwd() ), с аргументом, предоставленным пользователем, в качестве первого аргумента при выполнении команды (используя process.argv[2] ). Вы можете найти ссылку на эти значения в документации Node.js для объекта процесса . Таким образом мы получаем абсолютный путь к целевому каталогу / файлу.

Теперь, первое, что нам нужно сделать, это найти все файлы спецификации JavaScript. Как видно из строки 12, мы можем использовать условный оператор для обеспечения большей гибкости: если пользователь предоставляет файл спецификации в качестве цели, то мы просто используем этот путь к файлу напрямую, в противном случае, если пользователь предоставляет путь к каталогу, мы должны найти все файлы, которые соответствуют нашему шаблону, как определено константой specRegExp , мы делаем это с помощью функции findSpecifications которую мы определим позже. Эта функция будет возвращать массив путей для каждого файла спецификации в целевом каталоге.

В строке 18 мы определяем константу assertionGroups в результате объединения двух функций getSpecifications() и getAssertions() . Сначала мы получаем содержимое каждого файла спецификации, а затем извлекаем из них утверждения. Мы определим эти две функции позже, а пока просто отметим, что мы используем вывод первой функции в качестве параметра второй, что упрощает процедуру и устанавливает прямую связь между этими двумя функциями. Хотя мы могли бы иметь только одну функцию, разделив их, мы можем получить более полное представление о том, каков реальный процесс, помните, что программа должна быть ясной для понимания; просто заставить его работать недостаточно.

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

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

 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> } ] } 

 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') } 

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

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