Specs' examples parser (SpExParser)


Specification examples parser for tests written in TypeScript


spec-examples-parser is a simple parser that turns specification examples into treatable array of objects, for your TypeScript tests.

Specification examples can be given:
1. directly inside the same test file, as:
- ☑️ Gherkin style text (Scenario Outline)
2. reading from files:
- ☑️ delimiter-separated values file (CSV or TSV)
- ☑️ Feature file (Cucumber/SpecFlow...) containing one "Scenario Outline" or more...
- ☑️ JSON file
- ☑️ Markdown containing table, based on GitHub Flavored Markdown specs

Works with

Tested with those testing frameworks:
- Jest
- Mocha
- Playwright

Install

``
npm install @testndev/spec-examples-parser
`

Samples

No more chit-chat.

Let's see a first sample using Jest, with TypeScript test file.


`typescript
import { describe, expect, test } from '@jest/globals';
import { greetings } from '../src/greetings';

describe(Our_App is able to greet customers (sample with Jest), () => {

test(Our_App greets in English by default, () => {
expect(greetings('Tom')).toBe('Hello Tom!');
});

test(Our_App says 'Bonjour Sébastien !' to 'Sébastien' in french, () => {
const greetingsPhrase = greetings('Sébastien', 'french');
expect(greetingsPhrase).toContain('Bonjour');
expect(greetingsPhrase).toBe('Bonjour Sébastien !');
});
});

`

You want to iterate the second test, with multiple examples (differents values of names/languages):

| name | language | greetingWord | expectedPhrase |
| --------- | -------- | ------------ | --------------------- |
| Sébastien | french | Bonjour | "Bonjour Sébastien !" |
| édouard | english | Hello | "Hello Édouard!" |
| ROSA | spanish | Hola | "¡Hola Rosa!" |

Instead of writing this:

`typescript
import { describe, expect, test } from '@jest/globals';
import { greetings } from '../greetings';

describe(Our_App respects local greetings formats for supported languages, () => {
[
{ name: 'Sébastien', language: 'french', greetingWord: 'Bonjour', expectedPhrase: 'Bonjour Sébastien !' },
{ name: 'édouard', language: 'english', greetingWord: 'Hello', expectedPhrase: 'Hello Édouard!' },
{ name: 'ROSA', language: 'spanish', greetingWord: 'Hola', expectedPhrase: '¡Hola Rosa!' },
].forEach(({ name, language, greetingWord, expectedPhrase }) => {
test(Our_App says "${expectedPhrase}" to "${name}" in "${language}", () => {
const greetingsPhrase = greetings(name, language);
expect(greetingsPhrase).toContain(greetingWord);
expect(greetingsPhrase).toBe(expectedPhrase);
});
});
});
`

SpExParser offers this (more human-readable) alternative:

`typescript
import { describe, expect, test } from '@jest/globals';
import { from } from '@testndev/spec-examples-parser';
import { greetings } from '../greetings';

describe(Our_App respects local greetings formats for supported languages, () => {
from(
name | language | greetingWord | expectedPhrase
Sébastien | french | Bonjour | "Bonjour Sébastien !"
édouard | english | Hello | Hello Édouard!
ROSA | spanish | Hola | ¡Hola Rosa!
).forEach(({ name, language, greetingWord, expectedPhrase }) => {
test(Our_App says "${expectedPhrase}" to "${name}" in "${language}", () => {
const greetingsPhrase = greetings(name, language);
expect(greetingsPhrase).toContain(greetingWord);
expect(greetingsPhrase).toBe(expectedPhrase);
});
});
});
`

Our magic .from() method can consume file, simply with file path:

`typescript
from('test/specexamples/csv/greetings-fr-es-en.csv') //...
`

executing this file will create and execute 3 tests, and return in terminal:

`
Our_App respects local greetings formats for supported languages
√ Our_App says "Bonjour Sébastien !" to "Sébastien" in "french" (1 ms)
√ Our_App says "Hello Édouard!" to "édouard" in "english"
√ Our_App says "¡Hola Rosa!" to "ROSA" in "spanish"
`

> You can find more detailed samples in https://github.com/testndev/spec-examples-parser-samples. They are ready to be executed!

Development