Skip to content

Latest commit

 

History

History
187 lines (161 loc) · 10 KB

README.md

File metadata and controls

187 lines (161 loc) · 10 KB
Raw

Zebrunner Device Farm (Android and iOS agent)

Feel free to support the development with a donation for the next improvements.

Zebrunner

Hardware requirements

Requirements
Operating System Ubuntu 16.04, 18.04, 20.04, 21.04, 22.04
Linux CentOS 7+
Amazon Linux2
MacOS (Ventura)
CPU 8+ Cores
Memory 32 Gb RAM
Free space SSD 128Gb+ of free space

Software prerequisites

Clone and setup

  • Clone mcloud-agent repository and execute setup procedure 
    git clone https://github.com/zebrunner/mcloud-agent.git
cd mcloud-agent
./zebrunner.sh setup

Run ansible playbook

  • [Optional] To enable opencv support append -opencv5.6.0 postfix to the APPIUM_VERSION in the ./defaults/main.yml: 
    APPIUM_VERSION: 2.0-opencv5.6.0

    Full list of supported appium+opencv images can be found here: https://gallery.ecr.aws/zebrunner/appium

Linux OS

  • update roles/devices/vars/main.yml file according to the obligatory/optional comments inside.

    Register all whitelisted Android and iOS devices with their udids!

  • Run ansible-playbook script to download the required components and set up udev rules: 
    ./zebrunner.sh ansible

    To reregister the devices list only, you can use the following command:

    ./zebrunner.sh ansible devices

    To provide extra arguments including sudo permissions, you can use the below command:

    ./zebrunner.sh ansible --user=USERNAME --extra-vars "ansible_sudo_pass=PSWD"
  • Devices management script is deployed to /usr/local/bin/zebrunner-farm.
  • Udev rules with whitelisted devices are in /etc/udev/rules.d/90_mcloud.rules.
  • Whitelisted devices properties are in /usr/local/bin/mcloud-devices.txt.
  • Usbmuxd service is stopped and masked (disabled).
  • [Optional] Register@reboot /usr/local/bin/zebrunner-farm restart via crontab to forcibly restart containers on reboot
  • [Optional] Increased fs.inotify.max_user_instances to workaround #328

    sudo sysctl fs.inotify.max_user_instances=2048

Mac OS

  • update roles/mac-devices/vars/main.yml file according to the obligatory/optional comments inside.

    Register all whitelisted iOS devices (phones, tablets or TVes) with their udids! Important! Only iOS devices supported on MacOS!

  • Run ansible-playbook script to download the required components and set up udev rules: 
    ./zebrunner.sh ansible

    To reregister the devices list only, you can use the following command:

    ./zebrunner.sh ansible devices

    To provide extra arguments including sudo permissions, you can use the below command:

    ./zebrunner.sh ansible --user=USERNAME --extra-vars "ansible_sudo_pass=PSWD"
  • Devices management script is deployed to /usr/local/bin/zebrunner-farm.
  • Whitelisted devices properties are in /usr/local/bin/mcloud-devices.txt.
  • Deployed and loaded $HOME/Library/LaunchAgents/ZebrunnerUsbmuxd.plist to share usbmuxd into the device containers
  • Deployed $HOME/Library/LaunchAgents/ZebrunnerDevicesListener.plist to load and manage iOS devices connect/disconnect automatically

Usage

Android devices

  • Enable the Developer Option and USB Debugging for each Android device.
  • Connect an Android device physically to a USB direct port or through the hub.
  • For the 1st connection, trust the device by picking "always trust..." on the device.

iOS devices

Automation steps

  • Enable Settings -> Developer -> Enable UI Automation.

  • Settings -> Safari -> Advanced -> Web Inspector.

  • Enable Siri.

  • Disable screen lock:

    Phone and Tablet: Settings->Lock screen->Turn display off when inactive->select Never

    Apple TV: Settings->General->Sleep after->Select never

Build WebDriverAgent.ipa

You need an Apple Developer account to sign in and build WebDriverAgent.

  1. Clone WebDriverAgent from source you prefer. We recommend our forked repository with performance improvements. 
    git clone https://github.com/zebrunner/WebDriverAgent.git
  2. Open WebDriverAgent.xcodeproj in Xcode.
  3. Ensure a team is selected before building the application. To do this, go to Targets and select each target (one at a time). There should be a field for assigning team certificates to the target.
  4. Remove your WebDriverAgent folder from DerivedData and run Clean build folder (just in case).
  5. Build the application by selecting the WebDriverAgentRunner target and build for Generic iOS Device. Run Product -> Build for testing. This will create a Products/Debug-iphoneos in the specified project directory.
    Example: /Users/$USER/Library/Developer/Xcode/DerivedData/WebDriverAgent-dzxbpamuepiwamhdbyvyfkbecyer/Build/Products/Debug-iphoneos
  6. Go to the "Products/Debug-iphoneos" directory and run: mkdir Payload
  7. Copy the WebDriverAgentRunner-Runner.app to the Payload directory: cp -r WebDriverAgentRunner-Runner.app Payload
  8. Finally, zip up the project as an *.ipa file: zip -r WebDriverAgent.ipa ./Payload

    Make sure to specify relative ./Payload to archive only Payload folder content

  9. Share built ipa via WDA_FILE variable in roles/devices/vars/main.yml file.

    to override WDA_FILE artifacts per each device use wda_file and wda_bundleid iOS device properties and re-execute ansible playbook.

SmartTestFarm

  • Open in your browser http://<PUBLIC_IP>/stf, authenticate yourself based on preconfigured auth system.
  • The connected device should be available in STF.
  • Disconnect the device from the server. Device containers will be removed asap, then, in 15-30 sec, the device should change the state in STF to disconnected as well.
  • Use different commands from ./zebrunner.sh start/stop/restart to manage the devices.

    Run ./zebrunner.sh to see available options.

Troubleshooting

Follow the below algorithm to identify any configuration issues with MCloud agent:

  • Enable the debug log level for udev rules: sudo udevadm control --log-priority=debug.

  • Inspect syslog to check if the zebrunner-farm shell script executed on every whitelisted device is able to connect/disconnect:

    tail -f /var/log/syslog | grep zebrunner-farm

  • If there are no updates during connection/disconnection, please, verify the correctness of:

    • device udid values,
    • presence of /usr/local/bin/zebrunner-farm,
    • correctness of /usr/local/bin/mcloud-devices.txt and /etc/udev/rules.d/90_mcloud.rules files.

  • Read carefully the zebrunner-farm output in syslog to identify the exact failure during containers creation.

  • Analyze device container logs if the status is not healthy:

    docker ps -a | grep device
// appium and WebDriverAgent for iOS container:
docker logs -f device-<Name>-<udid>-appium
// STF provider container:
docker logs -f device-<Name>-<udid>
// artifacts uploader container:
docker logs -f device-<Name>-<udid>-uploader

  • If you have any problems running ansible:

    • Make sure you have sudo access and try to run ansible with sudo permissions.
    • Try to rub ansible commands manually (<devices_file> name is mac-devices on macOS or devices on Linux servers)

    To download the required components and set up udev rules:

    ansible-playbook -vvv -i hosts <devices_file>.yml

    To reregister the devices list only, you can use the following command:

    ansible-playbook -vvv -i hosts <devices_file>.yml --tag registerDevices

    To provide extra arguments including sudo permissions, you can use the below command:

    ansible-playbook -vvv -i hosts --user=USERNAME --extra-vars "ansible_sudo_pass=PSWD" <devices_file>.yml

Documentation and free support

License

Code - Apache Software License v2.0

Documentation and Site - Creative Commons Attribution 4.0 International License