Appiumx

Appiumx is a server that receives connections from Helios Devices and listens for commands sent over the Json Wire Protocol and forwards them onto it's connections. It is the mediator between the caller and the app and will report testing results.

sb-sand-appiumx:4723 is the base URL for sand, replace environment as needed.

Running

When you first clone this repository, run rake setup which will perform the rake install rake build and rake link steps for you. Because this repository consists of three modules, it is strongly encouraged to use the rake tasks to build and link so that you can easily set up your dev environment quickly (see Bumping Versions for more background on this). Linking allows the appiumx module to rely on your local copy of its dependencies appiumx-base-driver and appiumx-helios-driver. After linking once, you should be fine, but if you run rake install or any form of npm install again, you will have to re-link to continue devving. Use rake build after every code change and node . to run.

After linking, you can also use appiumx as a command in your terminal globally to run, but sometimes conflicts can happen with appiumx desktop and weird stuff goes down so it's encouraged to stick to appiumx/ as your current directory and running node ..

Deploying

Deploying to our sand and qa environments hosted here at MX automatically happens when you merge master into sand qa branches respectively. Feel free to use rake deploy to speed up these steps.

Bumping Versions

This repository actually consists of 3 modules that have dependencies on each other in order to make our hosting/deploying easier (so far, this is the only project at MX that is a javascript server, and it happens to have these dependencies like so). This however makes "deploying" via npm a little more... unconventional.

appiumx is the main module with dependencies appiumx-base-driver and appiumx-helios-driver. appiumx-base-driver is actually the core logic of where everything goes down (Go figure. Decisions were made.) and where the actual server is being run, and where our device connections are managed. The appiumx-helios-driver is a third (obviously) custom module that will act like a normal driver but will reroute the command through our device connections instead of using native device commands, etc.

Most maintenance is anticipated to be in appiumx-base-driver.

As a little background, The package-lock.json is the source of truth for what is being used at this time and that is why it is tracked in version control in addition to the package.json. Once you update the version of a dependency B required in module A's package.json, you will want to then run npm update B.

In order to hypothetically bump the appiumx-base-driver version after making an important change, the following is preferred:

$ cd appiumx/
# change appiumx-base-driver version in appiumx-base-driver/package.json and save
# commit this change
$ cd appiumx-base-driver/
$ npm publish   # push this new version up to npm
$ cd ../
# change appiumx-base-driver's version in appiumx/package.json to new version under
"dependencies".
# update the version of appiumx in appiumx/package.json (new version now has new dependency) and save
$ npm update appiumx-base-driver
# IMPORTANT: verify that appiumx/package-lock.json is showing the new version
for appiumx-base-driver and appiumx
# commit and push all changes to appiumx/package.json & appiumx/package-lock.json
# make sure your current directory is still appiumx/
$ npm publish   # release new version of appiumx

After that, it's up to you if you want to update the pipeline version of appiumx in moneymobilex or in appiumx-desktop. (Reminder that Appiumx Desktop is not published to NPM, just built and released as an executable.) Anything using the new version of appiumx will be using the new version of appiumx-base-driver as well.

Troubleshooting

Things that have helped in the past with trouble building, running etc:

• In finder, use cmd + shift + g to open /usr/local/, visit bin and delete the appiumx shortcut. Return and visit lib/node_modules and delete all three appiumx modules shortcuts. The shortcuts in bin and lib are generated by linking and installing globally, this is manually removing that linking.

Endpoints

Creating a websocket device connection

| url | ws://(baseURL)/helios-websocket | |----------|------------------------------------| | method | NA: Use websocket upgrade protocol | | body | NA: Use websocket upgrade protocol | | response | None. |

Expects some json of a lot of device info on device connection open. Mobile devices connect here.

Creating a websocket device connection

| url | ws://(baseURL)/appiumx-desktop-websocket | |----------|------------------------------------| | method | NA: Use websocket upgrade protocol | | body | NA: Use websocket upgrade protocol | | response | None. |

Expects some json of a lot of device info on device connection open. Appiumx desktop client connects here.

Viewing all connected devices

| url | http://(baseURL)/helios-devices | |----------|------------------------------------| | method | GET | | body | None | | response | Human-readable list of connected devices.|

Viewing all connected devices in Json format

| url | http://(baseURL)/helios-devices-json| |----------|------------------------------------| | method | GET | | body | None | | response | JSON list of uuids mapping to their device info.|

This really should have been a list, but was created originally as a map/object with the uuids mapping to the device info. Sorry about that, it probably should have been a list.

Resetting all connections

| url | http://(baseURL)/helios-reset-connections | |----------|----------------------------------------------| | method | POST | | body | None or { "uuids": ["uuid1", "uuid2"] } | | response | {"result":"Connections have been closed.","devicesClosed":["uuid1", "uuid2"]} |

This is useful in times of panic if socket connections freeze up, hang, or timeout, but the app still thinks that it's connected so it won't re-initiate. This forces all connections to close. All apps pointed towards this server will automatically attempt to reconnect 100ms after closure. You should in essence just see all devices close and reopen almost instantly.

Smokebombing all connections

| url | http://(baseURL)/helios-smokebomb-all | |----------|----------------------------------------------| | method | POST | | body | None or { "uuids": ["uuid1", "uuid2"] } | | response | {"result":"Devices have been smokebombed.","devicesSmokebombed":["uuid1", "uuid2"]}|

Smoke-bombing is when we need to get the app to the original starting place for a regression/sanity test, meaning the landing view. This currently functions on all connected devices at the same time (one giant smokebomb). Does not fail if the device is already at the start screen.

Sending custom commands directly to a specific device

| url | http://(baseURL)/helios-command/session/(deviceUuid)/(appEndpoint)| |----------|-------------------------------------------------------------------| | method | GET/PUT (honestly doesn't matter too much, app doesn't care | | body | Depends on endpoint you want to hit mostly empty | | response | Depends on endpoint you want to hit mostly empty |

This is the endpoint that Appiumx uses internally for forwarding on commands directly to a specific device that is connected. This isn't commonly just dropped in a browser, it's mostly intended to be used by scripts, but you functionally can use it in the browser as well (pretty much unless it needs body text too).

Find the endpoints the app recognizes in https://gitlab.mx.com/mx/moneymobilex/blob/master/Classes/dev_tools/web_driver_runner.cpp#L36 for now