hook templates

1. Why do we need it:

Even though the configuration file's parameter provides comprehensive ways of customizing the crawling behavior for your target app, there may be some tricky scenes that you need a more direct control on the crawling process. For example:

• case 1: if your app contains a login page and after the first time you login you have to slide down until end of an agreement and tick a check box and then click the confirm button before you can enter the home panel of your app. You may have to write a complicated list of specific actions in your configuration parameter to perform these series of behavior.

• case 2: during the middle of crawling, if you want to test a very specific section of your app which is embedded inside of deep layers of activities/view controllers, it will also be like hell if you can only make it via a set of actions in configuration file.

2. Trigger points:

Hooks provides a direct way for user to take full control of the crawling process in the following stage, if you wonder how the crawler behaves in detail data flow, you can check this github issue

3. Hook APIs

This sections gives you an overview about hook methods and their input output params. The next chapter will give you example on how to write your own hooks

3.1 checkDigest

/**
 * Method to generate a unique digest which can identify a window, change the node.digest if you want.
 * @Params: $platform the name of the platform "iOS/android/web"
 * @Params: $source the raw json source of the current page
 * @Params: $node the node which needs to settle digest
 * @Params: $crawler the crawler instance, in which you can see the entire window hierarchy and the list of actions belongs to each of the window
 * @Returns: true to indicate the action has been handled and the default logic will not execute
 * to indicate the action has been handled
 * */
Hooks.prototype.checkDigest = function(platform, source, node, crawler) {
  return false;
};

3.2 sortActionPriority

/**
 * Method to sort a list of actions which will be later bind to a crawling node object, return the list of actions.
 * @Params: $actions the array of actions which can be further sorted.
 * @Params: $crawler the crawler instance, in which you can see the entire window hierarchy and the list of actions belongs to each of the window
 * @Returns: actions the sorted actions which should be bind to the crawling node.
 * */
Hooks.prototype.sortActionPriority = function(actions, crawler) {
  return actions;
};

3.3 insertTable

/**
 * Method to analysis and insert tab nodes for a master-detail view structure.
 *  This method is called when a tab node element is found in the source tree,
 *  the hook is invoked to provide you the chance to update the view tree structure
 *
 * @Params: $sourceArray the array of elements which belongs to the candidate tab node,
 *          you should create your own CrawlingNode and insert the source array as its action elements.
 * @Params: $crawler the crawler instance which contains the context information as well as crawler config
 * @Returns: true to indicate the action has been handled and the default logic will not execute
 * */
Hooks.prototype.insertTabNode = function (sourceArray, crawler) {
  return false;
};

3.4 performAction

/**
 * Method which you can override and replace with your own implementation
 * @Params: action the actions which belongs to current active node, which is going to be performed by you
 * @Params: crawler the crawler instance which contains the context information as well as crawler config
 * @Returns: a Promise to indicate the action has been handled and the default logic will not execute,
 *           you should resolve the promise and hence the crawling will go on :)
 * */
Hooks.prototype.performAction = function(action, crawler) {
  return null;
};

3.5 afterActionPerformed

/**
 * Method to intercept the crawling process after an specific action has been performed
 * @Params: action the action which belongs to current active node, and has just been performed
 * @Params: crawler the crawler instance which contains the context information as well as crawler config
 * @Returns: a Promise to indicate the action has been handled and otherwise the default logic will bypass it
 * */
Hooks.prototype.afterActionPerformed = function(action, crawler) {
  return null;
};