Configuration

Serenity/JS can be configured using the Protractor configuration file - protractor.conf.js, which then becomes the first argument of the Protractor command line test runner you invoke to execute the tests:

protractor ./protractor.conf.js

Configuration of the ts-node module and the TypeScript compiler is explained below.

Serenity/JS Protractor Framework

To make Protractor aware of Serenity/JS, make sure that the protractor.conf.js file defines the framework and the frameworkPath as per the below:

exports.config = {
    // Framework definition - tells Protractor to use Serenity/JS
    framework: 'custom',
    frameworkPath: require.resolve('serenity-js')
}

Cucumber

To use Serenity/JS with Cucumber, two more parameters need to be added to the configuration:

  • specs - which tells Cucumber where your .feature files are located,
  • cucumberOpts - which defines Cucumber-specific configuration, such as where the step definitions are, or what compiler to use.

When Serenity/JS sees the cucumberOpts parameter, it also makes an informed guess that it is the Cucumber dialect that you want to be using in your test scenarios (although you can configure that explicitly too):

exports.config = {

    // Framework definition - tells Protractor to use Serenity/JS
    // ... (see above)

    specs: [ 'features/**/*.feature' ],

    cucumberOpts: {
        require:    [ 'features/**/*.ts' ], // loads step definitions
        format:     'pretty',               // enable console output
        compiler:   'ts:ts-node/register'   // interpret step definitions as TypeScript
    }
}

Please note that even though the configuration above tells Cucumber to use a TypeScript transpiler to interpret the step definitions (compiler: 'ts:ts-node/register'), it still allows for steps defined in JavaScript to be included also (see mixed mode):

    cucumberOpts: {
        require:    [           // loads step definitions:
            'features/**/*.ts', // - defined using TypeScript    
            'features/**/*.js'  // - defined using JavaScript
         ], 
        format:     'pretty',               // enable console output
        compiler:   'ts:ts-node/register'   // interpret step definitions as TypeScript
    }

Learn more about writing and executing test scenarios with Cucumber.

Mocha

As with Cucumber, to use Mocha specify the below two parameters:

  • specs - which tells Mocha where to find your spec files,
  • mochaOpts - which defines Mocha-specific configuration, and same as the mocha.opts file, it tells Mocha how to display the progress of the execution of your tests execution in the terminal and what syntax you want to use in your tests. See Mocha documentation for more details.

When Serenity/JS sees the mochaOpts parameter, it also makes an informed guess that it is the Mocha dialect that you want to be using in your test scenarios (which can be configured explicitly too):

exports.config = {

    // Framework definition - tells Protractor to use Serenity/JS
    // ... (see above)

    specs: [ 'spec/**/*.spec.ts' ],

    mochaOpts: {
        ui:       'bdd',                  // use the describe/it syntax (default: 'bdd').
        compiler: 'ts:ts-node/register'   // interpret step definitions as TypeScript
    }
}

:bulb: PRO TIP: Mocha's programmatic API does not accept the compiler option, and because of that the above configuration would not work with Protractor's built-in Mocha adapter. Serenity/JS interprets the compiler configuration and loads the required module using syntax consistent with Cucumber's and Mocha's command line interface.

As with Cucumber, note that even though the configuration above tells Mocha to use a TypeScript transpiler to interpret the spec files (compiler: 'ts:ts-node/register'), it works perfectly fine with specs defined in JavaScript too (see mixed mode):

exports.config = {

    // Framework definition - tells Protractor to use Serenity/JS
    // ... (see above)

    specs: [                    // load specs defined in:
        'spec/**/*.spec.ts',    // - TypeScript
        'spec/**/*.spec.js'     // - JavaScript
     ],

    mochaOpts: {
        ui:       'bdd',
        compiler: 'ts:ts-node/register'   // interpret step definitions as TypeScript
    }
}

Learn more about writing and executing test scenarios using Cucumber.

Serenity/JS - dialect

Serenity/JS detects whether you want to use Cucumber or Mocha based on the presence of cucumberOpts or mochaOpts, respectively.

You can skip the automatic detection and define which dialect to use by specifying the dialect option in the serenity section of your configuration:

exports.config = {

    serenity: {
        dialect: 'cucumber',  // or 'mocha'
    }
    // ...
}

Stage Crew Members

The Stage Crew Members listen on and act upon the domain events emitted during the test scenario execution.

Your default stage crew consists of:

  • the Photographer, who takes a screenshot of the UI when an actor performs a task
  • the SerenityBDDReporter, who produces Serenity BDD-compatible JSON reports
// Optional, imports Serenity/JS Stage Crew Members
const crew = require('serenity-js/lib/stage_crew');

exports.config = {

    // Framework definition - tells Protractor to use Serenity/JS
    // ... (see above)

    serenity: {
        crew:    [
            crew.serenityBDDReporter(),
            crew.photographer()
        ],

        dialect: 'cucumber',  // or 'mocha'
    },

    // Test framework-specific configuration... (see above)

    // Other protractor-specific configuration... (see below)
}

Stage Crew configured via the serenity.crew property overrides the defaults, so for example if you wanted to disable screenshots altogether, you can let the Photographer go and only leave the SerenityBDDReporter:

serenity: {
    crew:    [
        crew.serenityBDDReporter(),
    ]
}

If you wanted to see what tasks are being performed, but were not interested in producing the report, you could hire the ConsoleReporter instead of the default Crew :

serenity: {
    crew:    [
        crew.consoleReporter(),
    ]
}

:bulb: PRO TIP: You can define your own Stage Crew Members to produce custom reports or integrate with your infrastructure.

Requirements directory

By default, Serenity/JS assumes that your acceptance tests, in the form of either Cucumber *.feature files or Mocha *.spec.ts files, are kept in the features directory under the project root. It also assumes that you run your acceptance tests from the project's root directory.

This means that the default configuration of the requirementsDirectory looks as follows, but you can change it to better fit the structure of your project:

serenity: {
    requirementsDirectory: `${process.cwd()}/features`
}

Output directory

Serenity/JS produces .json reports (optionally accompanied by screenshots) and stores them in the target/site/serenity directory (relative to where you're executing the tests from) where they can be processed by Serenity BDD CLI to create the HTML reports.

This means that the default configuration of the outputDirectory looks as follows, but you can change it to better fit the structure of your project:

serenity: {
    outputDirectory: `${process.cwd()}/target/site/serenity/`
}

:bulb: PRO TIP: To configure a location that's relative to your current working directory (i.e. where you execute your test runner, such as Protractor) use process.cwd(), for example: ${process.cwd()}/some/relative/path.

The thing to remember when changing the default output directory, though, is that this will also require you to tell Serenity BDD CLI where to look for the reports.

To do this, make sure that you specify the --source and --destination parameters when invoking serenity run:

serenity run --source my/custom/path --destination my/custom/path

To find out more about the command line options of Serenity CLI run:

serenity --help run

:bulb: PRO TIP: The serenity script mentioned above lives under the node_modules/.bin directory, so you can either execute it there, or add a script to your package.json: scripts: { serenity: "serenity" } and run it through the npm: npm run serenity --help run.

Timeouts

To ensure that the contract with Protractor is respected, Serenity/JS needs to wait for any Protractor plugins to process the results of a finished scenario before the next scenario can be executed. The same synchronisation needs to occur if Serenity/JS is configured to capture screenshots, as those too might take some time to be stored to disk, especially when the web browser is hosted on a remote grid.

To handle those situations, a test scenario will wait for a signal to start - a stage cue, up to the maximum of serenity.stageCueTimeout milliseconds:

serenity: {
   stageCueTimeout: 30 * 1000   // up to 30 seconds by default
}

To learn how to configure other timeouts, consult the below sections of relevant manuals:

Protractor

The rest of the configuration can be defined as per the Protractor documentation.

Mixed mode

Thanks to the fact that TypeScript is a super-set of JavaScript, valid JavaScript code is, in fact, valid TypeScript, just without the benefit of type definitions.

What this means is that Cucumber can use step definitions and Mocha can execute specs where some of them are implemented in TypeScript and some in JavaScript, yet they can still co-exist in the same codebase without a problem.

This fact is incredibly useful when introducing Serenity/JS and TypeScript to an existing JavaScript codebase, because it allows for gradual and safe adoption of Serenity/JS, rather tha a big-bang re-write.

TypeScript

The ts-node module, the one responsible for interpreting the TypeScript sources in-memory, uses the same configuration file as the regular TypeScript compiler.

The easiest thing to do to make sure that the TypeScript code you write is transpiled correctly is to place a tsconfig.json file with the below contents in the root directory of your Node.js project, the same place where the protractor.conf.js file lives:

{
  "compilerOptions": {
    "target": "es5",
    "lib": [ "es5", "es6" ],
    "module": "commonjs",
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "sourceMap": true,
    "declaration": true
  },

  "exclude": [
    "node_modules"
  ]
}

Your feedback matters!

Suggest features and improvements on github, get in touch on twitter, and if you found Serenity/JS useful - don't forget to give it a star! ★

Star

results matching ""

    No results matching ""