Permalink
1f3091e Feb 10, 2015
111 lines (92 sloc) 4.25 KB

Contributing to Mobile Checker

Looking to contribute to Mobile Checker? There is many ways to get involved in its developement. Please take few minutes to read this document to understand how you can help in Mobile Checker developement.

Add a new check

It is pretty simple to add a new check to the mobile checker. Create a new check require only an experience in a client side JavaScript developement.

A new check is composed by 2 composants:

  • the script itself, who will be executed on the tested web page.
  • the issue template, sent to the user.
  • testing.

script

All check scripts are located in the lib/checks directory. You just have to add your own script file in the correct category. Of course, feel free to create a new category if no category match with your check. Ready? Let's create your first check!

This is the basic template of check file. Save it in the lib directory:

var self = this;
exports.name = "name-of-the-check"; //write here the name of your check. Have to match with the file's name.
exports.category = "name-of-the-category"; //write here the name. Have to match with a category's directory name.
exports.check = function(checker, browser) {
    /*
     * here your code.
     */
};

The check(checker, browser) function, receive checker and browser as parameters.

  • Use browser to test the web page.
  • Use checker to report the result.

N.B: The browser object is based on the mobile-web-browser-emulator API which is based on selenium WebDriverJS API. That allow you to use all the functions provided by these APIs.

access to mobile-web-browser-emulator API:

exports.check = function(checker, browser) {
    // get a browser object which can be use with mobile-web-browser-emulator API
};

example:

exports.check = function(checker, browser) {
    browser.takeScreenshot(__dirname + "/../screenshot.png"); //mobile-web-browser-emulator method
};

access to selenium WebDriverJS API:

    browser.do(function(driver) { //take a function in parameter
        // get a driver object which can be use with selenium webdriver 
    }); 

example:

exports.check = function(checker, browser) {
    browser.do(function(driver) {
        driver.getTitle().then(function(title) { //selenium webdriver method
            console.log(title);
        });
    });
};

N.B: WebDriverJS uses "promises" to track the state of each operation. learn more.

run your own script:

exports.check = function(checker, browser) {
    browser.do(function(driver) {
        return driver.executeScript(function() {
            //write your own script and return what you need.
        });
    });
};

report a result:

to report a result, use the report function of the checker object.

checker.report(key, name, category, status, data)
  • key: name of the file issue to display in the report
  • name: self.name
  • category: self.category
  • status: error, warning or info
  • data: data to display in the issue reported (optional)

issue template

All check issues are located in the lib/issues directory. You just have to add your own issue file in the correct path as category/name-of-your-check/your-file. You can create all issues you need. That allow you to use more than once the checker.report(key, name, category, status, data) function in your script.

The Mobile Checker use EJS to write the issues sent to the client side. That allow you to insert data in the reported issue.

template:

<div class="col-md-12 issue">
    <div class="col-md-12 content-issue">
        <h2 class="title-issue page-header">
            <span class="glyphicon glyphicon-exclamation-sign" aria-hidden="true"></span> 
            <!-- title of your issue -->
            <small><%=category%></small>
        </h2>
        <p> <!-- write here what's going on --> </p>
        <p class='fixit'><strong>Fix it:</strong> <!-- explain here how to fix it --> </p>
    </div>
</div>