sui-test

sui-test

Zero config testing tool

Motivation

(1) Setup properly a testing env in JS is hard. There is a lot deps and is easy for us install differents setups in differents project. To avoid that now to run a test suit over your code you need install only one tool.

Folder Structure

Your tests must be in a test folder in your project root. Each test file should follow the patter: *Spec.js.

.
├── package.json <- Project package.json
└── src
│   ├── detail.js
│   └── user.js
└── test
    ├── detail
    │   └── detailSpec.js
    └── user
        └── userSpec.js

Installation

npm install @s-ui/test --save-dev

CLI Options

  Usage: sui-test [options] [command]


  Options:

        --version  output the version number
    -h, --help     output usage information


  Commands:

    browser|b   Run tests in the browser
    server|s    Run tests in node
    help [cmd]  display help for [cmd]

Browser options

  Usage: sui-test browser [options]


  Options:

    -W, --watch  Run in watch mode
    -C, --ci     Run a Firefox headless for CI testing
    -P, --pattern <pattern>               Path pattern to include (default: test/**/*Spec.js)
    -I, --ignore-pattern <ignorePattern>  Path pattern to ignore for testing (default: false)
    --src-pattern <srcPattern>  Define the source directory (default: src/**/*.js)
    -h, --help   output usage information
  Description:

  Run tests in Chorme

  Examples:

    $ sui-test browser

Server options

  Usage: sui-test server [options]


    Options:

        -I, --inspect Inspect node process
        -W, --watch  Run in watch mode
        -T, --timeout Customize test timeout
        -P, --pattern <pattern>  Path pattern to include (default: test)
        -h, --help   output usage information
    Description:

    Run tests in node

    Examples:

      $ sui-test server -W

e2e tests

sui-test e2e [options]

sui-test e2e assumes that your e2e tests are located in the ./test-e2e/ folder of your project.

Important: If you need to have fixtures files (or helpers), put them in the ./test-e2e/fixtures so they aren't executed as spec files.

Support files

If you need to have support files, then create a ./test-e2e/support directory, it will be detected and added to the cypress.json configuration.

Support files runs before every single spec file and you don't have to import it in spec file.

Example:

./test-e2e/support/index.js

/* globals Cypress, cy */
Cypress.Commands.add('login', () => {
  // Here the command code
})

Then you can use in your specs cy.login()

Options

  Usage: sui-test-e2e [options]


  Options:

    -B, --baseUrl <baseUrl>                  URL of the site to execute tests (in ./test/e2e/) on.
    -S, --screenshotsOnError                 Take screenshots of page on any failure.
    -U, --userAgentAppend <userAgentAppend>  Append string to UserAgent header.
    -UA, --userAgent <userAgent>             Overwrite string to UserAgent header.
    -G, --gui                                Run the tests in GUI mode.
    -C, --ci                                 CI Mode, reduces memory consumption
    -h, --help                               output usage information
    -b, --browser <browser>                  Select a different browser (chrome|edge|firefox)
    -N, --noWebSecurity                      Disable all web securities (CORS)
    -K, --key                                It is used to authenticate the project into the Dashboard Service
    -P, --parallel                           Run tests on parallel
    -R, --record                             Record tests and send result to Dashboard Service

sui-test e2e --gui

Tests are executed with cypress. It provides a special GUI to help you write your tests with a totally new experiences.

Check the docs for more info.

Important: Cypress is not installed as dependency of @s-ui/test. It will be auto-installed only on first sui-test e2e execution.

sui-test e2e --scope='sub/folder'

You can execute only a subset of tests in ./test-e2e/. The example above would only execute tests in ./test-e2e/sub/folder.

sui-test e2e --userAgent='My custom string'

Cypress can be detected as a robot if your server has that kind of protection or firewall. In this case, if your server allows an exception by header, you can overwrite the UserAgent header a string that cypress will set when opening your site with the browser.

sui-test e2e --userAgentAppend='My custom string'

Cypress can be detected as a robot if your server has that kind of protection or firewall. In this case, if your server allows an exception by header, you can append to the UserAgent header a string that cypress will add when opening your site with the browser.

sui-test e2e --screenshotsOnError

If defined, any error on your tests will create a screenshot of that moment in the ./.tmp/test-e2e/screenshots folder of your project.

# Config

@s-ui/test could use a config in your package.json to tweak some behaviors. These are

• server: Config for @s-ui/test server binary:
  • forceTranspilation: List of regexs (string based, later will be transformed with new Regex) of modules to transpile. This is useful in case you're using server tests for modules that are ESModules based and need to be transpiled with @babel/plugin-transform-modules-commonjs.
  • esmOverride: Boolean flag (defaults to false), enable patching the Node's CJS loader when facing ESM errors, like ERR_REQUIRE_ESM in node > v12.12.0.

"config": {
  "sui-test": {
    "server": {
      "forceTranspilation": ["@adv-ui/vendor-by-consents-loader"],
      "esmOverride": true
    }
  }
}

Tools

Descriptor by environment patcher

The descriptor by environment is a patch with the purpose of add some extra functionality to our mocha describe and it methods.

How to import it?

First of all, the patcher MUST BE APPLIED on each test that we want to have the extra methods so at the top of ourExampleSpec.js we will add the next code:

import { descriptorsByEnvironmentPatcher } from '@s-ui/test/lib/descriptor-environment-patcher'
descriptorsByEnvironmentPatcher()

And that's it, from that line you will have the next methods added to the base of the mocha lib:

• describe.client
• describe.server
• describe.client.only
• describe.server.only
• it.client
• it.server
• it.client.only
• it.server.only

How can I use it?

Just in the same way as you have been using the describe or it functions earlier:

describe.client('Users use case', () => {
  it('should....', () => {
    // ...
  })
})

describe.server('Users use case', () => {
  it('should....', () => {
    // ...
  })
})

You can also have it() by environment:

describe('Another use case', () => {
  it.client('should....', () => {
    // ...
  })

  it.server('should....', () => {
    // ...
  })
})

What about if you want to run only one describe but only for client? You can use the .only function in the same way as you've been using earlier.

describe.client.only('Another use case', () => {
  it('should....', () => {
    // ...
  })
})

Contributing

Please refer to the main repo contributing info.