Feat/test parser

[scottnath]

Changelog

New

• adds test-parser
• adds fixtures for test-parser tests
• adds chai as assertion library
• gets HTML from file

What is this?

This is the parser which parses the exportable tests.

This parser, with our exportable-test structure, is now confirmed to work with Jest (this repo) and Mocha. The exportable tests have been confirmed to work in Angular CLI environments.

Exportable test parser

This test parser is meant to create describe/it/expect test structures. If it's output was being printed out, it would look like any other describe/it tests:

describe('Runs fixture requirement tests' () =>{
  describe('Div is understandable and unique', () => {
    it('Standard div', () => {
      expect(actual.html, "I find said div's content").to.not.be.empty;
      expect(actual.content, 'said content includes text').to.not.be.empty;
      expect(actual.content, "said div's content is meaningful").to.not.equal(defaults.content.text);
    });
  });
});

Exportable test structure

Inside src/test-parser.js is the breakdown of an exportable test object's available properties - documented in the scenario-test-object typedef JSDoc block.

The example in this repo via the fixture (see below) is a very basic example of a test.

Test fixtures

PR includes fixtures for the tests which are:

• src/tests/fixtures/div--variant-one.html
  • this represents the HTML that would be tested. In real-world use, this would be the output from react/angular/hbs/vue for one demo (ie button--primary)
• src/tests/fixtures/div-requirements.js
  • this outputs a function which returns an array. The array in this file contains one test
  • standardDiv is the one test. This test only checks the content of the HTML
    • the second parameter in the expect functions is why I added chai. Jest's assertion library doesn't allow that parameter out of the box
  • these tests are what would be imported by a framework to use in their specific test environment
• src/tests/fixtures/div.feature
  • this is an example Gherkin file
  • You can see the text from the single scenario in this file reflected in div-requirements

How Jest runs the tests

1. Running yarn test triggers the tests inside src/__tests__/test-parser-test.js
2. Grabs HTML from div--variant-one.html
3. Converts HTML into a DOM fragment for testing
4. Creates tests using TestParser (the test parsing func) using document - which contains the DOM fragment
5. Runs tests after it creates them

Next steps

Real-world example

This PR only includes testing of a basic example-fixture.

@elizabethsjudd is working on an actual test for the accordion component which will include separate tests per user type. Her tests will show how to test changes to the DOM using this exportable test format.

Carbon POC

While we can get these tests running in this environment, we should also test that they could work within one of carbon-components-react/angular/vue.

Chai assertions / assertion library selection

The second parameter allows us to tie the expect statements to a specific scenario-requirement. But we don't want to mix the assertion types. The assertion library for these exportable tests should be something that would work in at least all four framework test environments, plus Selenium.

Confirming all requirements are met

We have tests which reads the Gherkin and the exportable tests and determines if there is a test for every requirement. I didn't want to include that in this PR so that we can focus on the exportable test structure

[joshblack]

Thanks for submitting this @scottnath! Had a couple of questions going through it initially:

• How would this work out if a team had a test environment that didn't support BDD style assertions through describe/it?
• What is the best way for handling collisions for the expect library across test environments? Seems like in this case we are merging them together?

Also, it seems like chai may be overriding the Jest assertions in that:

      expect(TestParser).to.exist;
      expect(TestParser).to.be.a('function');
      expect(Itter).to.exist;
      expect(Itter).to.be.a('function');
      expect(GetDomFragment).to.exist;
      expect(GetDomFragment).to.be.a('function');

Would be written like this in Jest (I think):

expect(TestParser).toBeDefined();
expect(TestParser).toEqual(expect.any(Function));