Introduce CustomActions feature (closes #1535)

[Artem-Babich]

Purpose

In some cases, you need to create custom actions that contain multiple default actions or other custom actions.

Approach

Provide the ability to describe and register custom actions in a JS configuration file. Create a TestController.customActions property containing these actions. If the user function returns a value, the result of calling the user action will be that value. If the function does not return a value, the result will be a TestController object, which you can chain further.

API

Define Custom Actions

// JS Configuration file

module.exports = {
    customActions: {
        async makeSomething (selector) {
           await this.click(selector);
        },
        async getSelectorValue (selector) {
         return await Selector(selector).innerText;
       },
    }
}

Use Custom Actions

test('Check span value', async t => {
    const spanValue = await t.customActions.getSelectorValue('#result');

    await t.expect(spanValue).eql('OK');
});


test('Click the button and check span value', async t => {
    const spanValue = await t.customActions.makeSomething()
                             .customActions.getSelectorValue('#result');

    await t.expect(spanValue).eql('OK');
});

Reporter Changes (For Dashboard team):

• runCustomAction is a command that fires reportTestActionStart before any inner action starts and fires reportTestActionDone after the latest inner action fineshed.
• you can identify each custom action run using command.actionId property.
• in the case of concurrency mode you can also use testRunId.
• you can also access the result of the runCustomAction command(the value returned by the custom action) in the reportTestActionDone function using command.actionResult property.

An example of reporter:

const customActionsStack = {}
const shouldReportInnerActions = false;

function isCustomAction (name /*or type */) {
   return name ==='runCustomAction';
   // or return type === 'run-custom-action';
}

{
  reportTestActionStart: (actionName, { command, testRunId }) => {
     if(isCustomAction(actionName /* or command.type */ ) ) {
        const { actionId, name } = command;
        customActionsStack[testRunId].push({ actionId, name }) ;
     }
  },
  reportTestActionDone:  (name, { command, testRunId }) => {
     if( isCustomAction(actionName /* or command.type */ ) ) {
        customActionsStack[testRunId].pop();
  
        const { actionResult, actionId, name } = command;
        // Do something with actionResult
        return;
     }
  
     if (!shouldReportInnerActions && customActionsStack[testRunId].length) {
        // Do not report action
     } else {
        // Report action
     }   
  }
}

References

Closes #1535

Pre-Merge TODO

• Write tests for your proposed changes
• Make sure that existing tests do not fail
• Make sure that the documentation link is correct in the Error template

[github-actions]

Release v2.1.1-alpha.3 addresses this.