Skip to content

appium-from-source.md

Latest commit

 

History

History
159 lines (115 loc) · 5.14 KB

appium-from-source.md

File metadata and controls

159 lines (115 loc) · 5.14 KB
Raw

Running Appium from Source

So you want to run Appium from source and help fix bugs and add features? Great! Just fork the project, make a change, and send a pull request! Please have a look at our Style Guide before getting to work. Please make sure the unit and functional tests pass before sending a pull request; for more information on how to run tests, keep reading!

Node.js

Appium is written in JavaScript, and run with the Node.js engine. Currently version 6+ is supported. While Node.js can be installed globally on the system, a version manager is highly recommended.

Your Node.js installation will include the npm package manager, which Appium will need in order to manage dependencies. Appiums supports npm version 6+.

Setting up Appium from Source

An Appium setup involves the Appium server, which sends messages back and forth between your test code and devices/emulators, and a test script, written in whatever language binding exists that is compatible with Appium. Run an instance of an Appium server, and then run your test.

The quick way to get started:

git clone https://github.com/appium/appium.git
cd appium
npm install
npm start

Hacking on Appium

First, run

npm install

Now, you can run appium-doctor to verify the prerequisites are present (since prerequisites for building Appium are different from those for simply running it). @appium/doctor (and its command-line executable, appium-doctor) lives in the Appium core monorepo, and can be run via:

npm run doctor -- --dev

The @appium/doctor package can also be installed globally and used that way:

npm install --global @appium/doctor
appium-doctor --dev

At this point, you will be able to start the Appium server:

npm start

See the server documentation for a full list of command line arguments that can be used.

Hacking with Appium for Android

To work on Android, make sure you have ant, maven, and adb installed and added to system PATH environment variable. Also you would need the android-19+ sdk installed. From your local repo's command prompt, install/run the following:

npm run reinstall

Make sure you have one and only one Android emulator or device running, e.g., by running this command in another process (assuming the emulator command is on your path):

emulator -avd <MyAvdName>

Now you are ready to run the Appium server via npm start.

Making sure you're up to date

Since Appium uses dev versions of some packages, it often becomes necessary to install new packages or update various things. Running npm install will update everything necessary. You will also need to do this when Appium bumps its version up. Prior to running npm install it is recommended to remove all the old dependencies in the node_modules directory:

npm run clean

To automatically reinstall, use:

npm run reinstall

Different packages

Appium is made up of a number of different packages. As of v2.0, the core packages live in a monorepo (including this documentation). The packages themselves live in the packages subdirectory. Running npm install will automatically install all dependencies for all packages in this directory by way of Lerna.

Running Tests

First, check out our documentation on running tests in general Make sure your system is set up properly for the platforms you desire to test on.

Once your system is set up and your code is up to date, you can run unit tests with:

npm run test

You can run functional tests for all supported platforms (after ensuring that Appium is running in another window with npm start) with:

npm run e2e-test

Debugging Node

This project has multiple launch configurations for running NodeJS code from within VSCode

  • Debug: Runs Appium server in debug mode so you can set breakpoints inside VSCode source files
  • Attach Debug: Attach to a currently running Appium server
    • Example Usage
      • From root, run node --inspect-brk . --port 5555
      • Run attach debug
      • Setup breakpoints in VSCode
  • Test All: Runs all mocha tests in test/. Can setup breakpoints in test code and source code
  • Test Current File: Runs the currently focused-on mocha file. Fails if it's not valid mocha test

Committing code

Each Appium package installs a pre-commit hook which will run the linter and the unit tests before the commit is made. Any error in either of these will stop the commit from occurring.

Once code is committed and a pull request is made to the correct Appium respository on GitHub, Appium build system will run all of the functional tests.