Style guide for contributors

Thanks for your contribution to Appium! Here are the principles we use when writing javascript. Please conform to these so we can merge your pull request without going back and forth about style. The main principle is: make your code look like the surrounding code.

JavaScript

With the exception of the code that runs on the devices themselves (appium-uiautomator2-server for Android, WebDriverAgent for iOS), Appium is written in Node.js. If you are not familiar with JavaScript, please familiarize yourself before attempting to modify the code. There are plenty of good, free resources (see, for example, You Don't Know JavaScript).

Rebasing

Commits in a pull request should consist of logical changes. If there are multiple authors, make sure each author has their own commit. It's not a good idea to modify author information. Merge commits should be rebased out of pull requests.

Linting

All code must pass ESLint. To check your code, you can simply run npm run lint from the Appium repo dir. The configuration is specified in the eslint-config-appium package.

Most modern editors have integration with ESLint. See here for details.

Style notes

We use a future version of JavaScript and take advantage of the Babel transpiler to render it down to what is supported by current versions of Node.js. We use ES2015 (formerly called ES6) with some not-yet-standard features, namely async/await. This style guide must be followed diligently in all Appium contributions! Luckily, linting will enforce most of these rules!

Test Style:

Tests are written using mocha and chai. The WebDriver library used is wd.

Keep on the same line if it makes sense semantically and length is not an issue:

Examples:

driver.elementByTagName('el1').should.become('123');

driver
  .elementsByTagName('el1').should.eventually.have.length(0);

Alternatively use extra indents to improve readability:

driver
  .elementById('comments')
    .clear()
    .click()
    .keys('hello world')
    .getValue()
    .should.become('hello world')
  .elementById('comments')
    .getValue().should.become('hello world');

driver
  .execute("'NaN'--")
    .should.be.rejectedWith('status: 13');