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.

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:

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:

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:

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

Setting up:

git clone [email protected]:testndev/spec-examples-parser.git
cd @testndev/spec-examples-parser
npm install

Testing:

npm run test