09-steps-advanced.md

title	layout	order
Advanced features in steps	doc_page.html	9

Advanced features in steps

Each stage of a step (except emit stage) are promises functions, so its received two paramters resolve and reject.

Two main point:

1. General Tips & Tricks
2. Steps error handling
3. Conditional steps

General Tips & Tricks

Some step's implementation tips & tricks are:

(Please check this advanced article about promises for more information)

1. resolve is executed automatically

At the end of each stage, the function resolve is automatically executed.

The following code:

  run: function(resolve, reject){
     resolve();
  }

Is like:

  run: function(resolve, reject){
     resolve();
  }

2. Usually return a value

If you don't want to execute the resolve function, it is required to return a different value of undefined.

Example:

  run: function(resolve, reject){
     return true;
  }

3. Background execution

It is possible to have a stage execution in background if nothing is returned.

This is useful with flow that has more than one step, and one of this steps needs to be executed in background (for example, a background process to convert 'sass' to 'css').

Maybe, it could have more sense to implement the background function in a plugin.

4. Delegate promises to plugins

A good practice is to delegate promises to plugins.

Example:

  run : function(resolve, reject) {
    return this.execute("pwd").then(resolve,reject);
  }

Where:

• this.execute is a 'core' plugin that returns a promise. If we return this promise, then the resolve() will be not called automatically.
• The stage will finish when the plugin this.execute is over, because resolve() and reject() are parameters of then().

Steps error handling

Usually when there is a error in a step, and it is an unhandling error, then the execution of all the flow will finish.

reject() with keep field

If we don't want to stop all the flow execution, for a error in a step, then called reject() with {keep: true}.

reject({keep: true});

• By default keep is false.

reject() with error field

You can send a descriptive text error calling reject() with {error: txt}

reject( { error: 'descriptive text error' } );

reject() with data field

data in the reject() function allows to send more detail about the error, this is very interesting when we use piscosour for continuous integration (jenkins, bamboo, travis, ...) with the junit option.

reject( { data: 'details of the error' } );

reject() example

All field (keep, error, data) can work together:

module.export = {
  run: function(resolve, reject) {
    reject({
        keep: true,
        error: 'error text',
        data: 'detail\'s error'
    })
  }
}

Conditional steps

Steps could be executed conditionally evaluating a customized expression in the check() stage.

resolve() with skip field

So below there is an example about how could be executed conditionally a step. This condition may be implemnented in the check() stage. And if the step must be skipped and not executed, please provide to resolve() a field with {skip: true}

Example:

  check : function(resolve, reject) {
    if (this.params.needThisstep) {
      resolve({skip: true});
    }
  }

So, the remaining stages of this steps are not going to be executed.