github.com/openstf/stf @v3.4.2 sqlite

STF (or Smartphone Test Farm) is a web application for debugging smartphones, smartwatches and other gadgets remotely, from the comfort of your browser.

STF was originally developed at CyberAgent to control a growing collection of more than 160 devices. As of July 2016 development is mainly sponsored by HeadSpin and other individual contributors.

We welcome financial contributions in full transparency on our open collective.

Credits

Sponsors

Thank you to all our sponsors! (please ask your company to also support this open source project by becoming a sponsor)

Gold Sponsor

HeadSpin provides secure and scalable STF for iOS integrated with Appium/XCTest/Selenium/Espresso, High speed interaction Audio/Video/Game testing and AI based Root cause analysis for Performance Management. It's free to start using HeadSpin in 150+ locations worldwide! Try it out for free.

HeadSpin offers a generous monthly contribution towards STF development.

Contributors

Thank you to all the people who have already contributed to STF!

Backers

Thank you to all our backers! [Become a backer]

How to become a sponsor

Please use our open collective or [contact us][contact-link] directly for sponsor arrangements. Both recurring and one-time contributions are most welcome. Contributions towards a specific issue or feature are also possible, and can be attributed to your company in our release notes and other related materials. Hardware-only contributions, whether new or used, are also extremely helpful and well received, especially if you find a device that doesn't work. Please see our donation transparency report for past hardware contributions.

Features

• OS support
• Android
  • Supports versions 2.3.3 (SDK level 10) to 9.0 (SDK level 28)
  • Supports Wear 5.1 (but not 5.0 due to missing permissions)
  • Supports Fire OS, CyanogenMod, and other heavily Android based distributions
  • root is not required for any current functionality
• Remote control any device from your browser
• Real-time screen view
  • Refresh speed can reach 30-40 FPS depending on specs and Android version. See minicap for more information.
  • Rotation support
• Supports typing text from your own keyboard
  • Supports meta keys
  • Copy and paste support (although it can be a bit finicky on older devices, you may need to long-press and select paste manually)
  • May sometimes not work well with non-Latin languages unfortunately.
• Multitouch support on touch screens via minitouch, two finger pinch/rotate/zoom gesture support on regular screens by pressing Alt while dragging
• Drag & drop installation and launching of .apk files
  • Launches main launcher activity if specified in the manifest
• Reverse port forwarding via minirev
  • Access your local server directly from the device, even if it's not on the same network
• Open websites easily in any browser
  • Installed browsers are detected in real time and shown as selectable options
  • Default browser is detected automatically if selected by the user
• Execute shell commands and see real-time output
• Display and filter device logs
• Use adb connect to connect to a remote device as if it was plugged in to your computer, regardless of ADB mode and whether you're connected to the same network
  • Run any adb command locally, including shell access
  • Android Studio and other IDE support, debug your app while watching the device screen on your browser
  • Supports Chrome remote debug tools
• File Explorer to access device file system
• Experimental VNC support (work in progress)
• Monitor your device inventory
• See which devices are connected, offline/unavailable (indicating a weak USB connection), unauthorized or unplugged
• See who's using a device
• Search devices by phone number, IMEI, ICCID, Android version, operator, product name, group name and/or many other attributes with easy but powerful queries
• Show a bright red screen with identifying information on a device you need to locate physically
• Track battery level and health
• Rudimentary Play Store account management
  • List, remove and add new accounts (adding may not work on all devices)
• Display hardware specs
• Use the Booking & Partitioning systems
• Overview
  • The partitioning system allow you [administrator level] to allocate distinct sets of devices to different projects or organizations (i.e. represented by user sets) for an unlimited period
  • The booking system allows you to reserve a set of devices for a set of users during a limited time (e.g. from 3:00 am to 4:00 am during 5 days)
  • What is common to the booking & partitioning systems is the concept of Group, that is, an association of devices, users and a specification of time
  • Report to GroupFeature.pdf for detailed documentation on how to use this feature
• Monitor your group inventory
  • See which groups are active, ready or pending, as well as other group properties: name, identifier, owner, devices, users, class, duration, repetition, starting date, expiration date
  • Search groups by their property values
  • Contact by email the owners of the selected groups
• Manage your groups
  • Create a group by specifying its name, devices, users and schedule
  • Get ready your group in order it is scheduled by the system
  • Search groups by their property values
  • Remove your group or a selection of your groups
  • Contact by email the owners of the selected groups [administrator level]
• Manage the devices [administrator level]
• Search the devices by their property values
• Remove a device or a selection of devices meeting a set of filters: present, booked, annotated, controlled
• Manage the users [administrator level]
• Create a user by providing his name and his email
• Search the users by their property values
• Remove a user or a selection of users meeting a set of filters: group owner
• Contact a user or a selection of users by email
• Set the default groups quotas applicable to all users
• Set the groups quotas applicable to a specific user
• Simple REST API

Status

STF is in continued, active development, but development is still largely funded by individual team members and their unpaid free time, leading to slow progress. While normal for many open source projects, STF is quite heavy on the hardware side, and is therefore somewhat of a money sink. See how to become a sponsor if you or your company would like to support future development.

We're also actively working to expand the team, don't be afraid to ask if you're interested.

Short term goals

Here are some things we are planning to address ASAP.

1. Performance
2. Properly expose the new VNC functionality in the UI
3. Properly reset user data between uses (Android 4.0+)
4. Automated scheduled restarts for devices
5. More!

Consulting services

We highly encourage open participation in the community. However, if you're running a business that uses STF or would like to use STF, you may sometimes want to have an expert, i.e. one of the original developers or a skilled contributor, work with you to set up a prototype for evaluation purposes, add support for new or old hardware, figure out an issue, fix a bug or add some new feature. Our services are similar to FFmpeg's. [Contact us][contact-link] with details and we'll see what we can do.

Availability is limited and tied to individual developer's schedules.

A quick note about security

As the product has evolved from an internal tool running in our internal network, we have made certain assumptions about the trustworthiness of our users. As such, there is little to no security or encryption between the different processes. Furthermore, devices do not get completely reset between uses, potentially leaving accounts logged in or exposing other sensitive data. This is not an issue for us, as all of our devices are test devices and are only used with test accounts, but it may be an issue for you if you plan on deploying STF to a multiuser environment. We welcome contributions in this area.

Requirements

• Node.js 8.x required (some dependencies don't support newer versions)
• ADB properly set up
• RethinkDB >= 2.2
• GraphicsMagick (for resizing screenshots)
• ZeroMQ libraries installed
• Protocol Buffers libraries installed
• yasm installed (for compiling embedded libjpeg-turbo)
• pkg-config so that Node.js can find the libraries

Note that you need these dependencies even if you've installed STF directly from NPM, because they can't be included in the package.

On Mac OS, you can use homebrew to install most of the dependencies:

brew install rethinkdb graphicsmagick zeromq protobuf yasm pkg-config

On Windows you're on your own. In theory you might be able to get STF installed via Cygwin or similar, but we've never tried. In principle we will not provide any Windows installation support, but please do send a documentation pull request if you figure out what to do.

We also provide a Docker container in the Docker Hub as openstf/stf. You can use our Dockerfile as guidance if you'd prefer to do the installation yourself.

You should now be ready to build or run STF.

Note that while Mac OS can be used for development, it doesn't provide a very reliable experience in production due to (presumed) bugs in ADB's Mac OS implementation. We use CoreOS but any Linux or BSD distribution should do fine.

Installation

As mentioned earlier, you must have all of the requirements installed first. Then you can simply install via NPM:

npm install -g stf

Now you're ready to run. For development, though, you should build instead.

Building

After you've got all the requirements installed, it's time to fetch the rest of the dependencies.

First, fetch all NPM and Bower modules:

npm install

You may also wish to link the module so that you'll be able to access the stf command directly from the command line:

npm link

You should now have a working installation for local development.

Running

STF comprises of several independent processes that must normally be launched separately. In our own setup each one these processes is its own systemd unit. See DEPLOYMENT.md and Setup Examples if you're interested.

For development purposes, however, there's a helper command to quickly launch all required processes along with a mock login implementation. Note that you must have RethinkDB running first.

If you don't have RethinkDB set up yet, to start it up, go to the folder where you'd like RethinkDB to create a rethinkdb_data folder in (perhaps the folder where this repo is) and run the following command:

rethinkdb

_Note: if it takes a long time for RethinkDB to start up, you may be running into rethinkdb/rethinkdb#4600 (or rethinkdb/rethinkdb#6047). This usually happens on macOS Sierra. To fix this on macOS, first run scutil --get HostName to check if the HostName variable is unset. RethinkDB needs it to generate a server name for your instance. If you find that it's empty, running `sudo scutil --s