Git Product home page Git Product logo

mcloud-agent's Introduction

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:
    ansible-playbook -vvv -i hosts devices.yml
    

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

    ansible-playbook -vvv -i hosts devices.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.yml
    
  • 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:
    ansible-playbook -vvv -i hosts mac-devices.yml
    

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

    ansible-playbook -vvv -i hosts mac-devices.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" mac-devices.yml
    
  • 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. Open WebDriverAgent.xcodeproj in Xcode.
  2. 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.
  3. Remove your WebDriverAgent folder from DerivedData and run Clean build folder (just in case).
  4. 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
  5. Go to the "Products/Debug-iphoneos" directory and run: mkdir Payload
  6. Copy the WebDriverAgentRunner-Runner.app to the Payload directory: cp -r WebDriverAgentRunner-Runner.app Payload
  7. 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

  8. 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
    

Documentation and free support

License

Code - Apache Software License v2.0

Documentation and Site - Creative Commons Attribution 4.0 International License

mcloud-agent's People

Contributors

akamarouski avatar avabishchevich avatar azarouski avatar cboyle81 avatar dhreben avatar hursevich avatar vdelendik avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

mcloud-agent's Issues

There are not relevant messages about containers after ./Zebrunner. sh restore

Steps:

1../zebrunner.sh backup
2./zebrunner.sh shutdown
3../zebrunner.sh restore

Actual result : There are unnecessary messages about containers after ./Zebrunner. sh restore

./zebrunner.sh restore**
      Your services will be stopped and current data might be lost. Do you want to do a restore now? y/n [n]:y
sudo: unable to resolve host mcloud
sudo: unable to resolve host mcloud
sudo: unable to resolve host mcloud
sudo: unable to resolve host mcloud
MCloud restore succeed.
removing device-Nokia_3-....... containers...
Error: No such container: device-Nokia_3-......
Error: No such container: device-Nokia_3.....-appium
removing device-Samsung_Galaxy_S10-....... containers...
Error: No such container: device-Samsung_Galaxy_S10-R.......
Error: No such container: device-Samsung_Galaxy_S10-R......-appium
removing device-Samsung_S5-4..... containers...
Error: No such container: device-Samsung_S5-4.....
Error: No such container: device-Samsung_S5-4d.....-appium


      WARNING! Your services needs to be started after restore.
      Start now? y/n [y]:y

ansible script due to the versions mistamch can't verify docker installed

we already have docker as pre-requisites so this verification step might be removed from roles/devices/tasks/main.yml (line 8)

    "msg": "Failed to import the required Python library (setuptools) on automation's Python /usr/bin/python. Please read module documentation and install in the appropriate location. If the required library is installed, but Ansible is using the wrong Python interpreter, please consult the documentation on ansible_python_interpreter"

test explicitly appium + opencv functionality

opencv components is shared in a little bit different way so there is probability that shared mcloud couldn't detect it.
in scope of the ticket we have to find valid script which use FindByImage annotation to detect any control by image and test.

refactor udev rules for iOS/Android devices

  1. we have to setup udev rule to start usbmuxd service if iOS device is connected to Linux
    https://github.com/shamanec/ios-appium-docker/blob/a55f4881b15c8e232b1d77835ed21655c56ed708/services.sh#L131

  2. integrate iOS devices into the same udev rules as android or in separate file as implemented by @shamanec
    https://github.com/shamanec/ios-appium-docker/blob/a55f4881b15c8e232b1d77835ed21655c56ed708/services.sh#L105

so after running ansible script all whitelisted devices should be registered in udev rules to remove/create containers asap after reconnections. So far for disconnected device our iOS containers constantly restarting...

investigate if we need NGIX share and ssl setup

in scope of 2.0 we reorganized http/https and ws/wss detection using PUBLIC_IP_PROTOCOL env var.
it seems like we can remove NGINX related share and ssl.crt/ssl.key as arguments at all. websockify also removed from the stf provider docker image wehre we used such artifacts

unable to manage devices manually using zebrunner-farm

after improving udev integration we lost capabilitites to manage devices via shell script directly:

(base) build@mcloud:~/tools/vd/mcloud-android$ zebrunner-farm restart <udid>
ACTION: restart
do nothing as device id/udid missed.

we have to adjust logic to combine both manual and udev usage

declare explicit port for vnc instead of using STF_PROVIDER_MAX_PORT

range of stf ports let's keep for stf only so let's don't use "STF_PROVIDER_MAX_PORT" for websockify

better to start after finishing with zebrunner/mcloud-device#58 because ideal solution is to deprecate and remove websockify at all.

anyway, make sure to change argument later for appium container either registering dedicated port and renaming env var https://github.com/zebrunner/mcloud-android/pull/38/files#diff-5a9ee23bdc597fc3d40c31d96d7bfb94c1ef8692d774d8e91975d4fb8c350526R83

ansible script due to the versions mismatch can't pull android-device image

ERROR! couldn't resolve module/action 'community.general.docker_image'. This often indicates a misspelling, missing collection, or incorrect module path.

The error appears to be in '/home/user/tools/mcloud-android/roles/download/tasks/main.yml': line 3, column 3, but may
be elsewhere in the file depending on the exact syntax problem.

integrate nginx for proxing ws requests to the connected devices

screen ws url pattern should refer onto the mcloud-agent host as this particular instance has access to devices via private network.
screenWsUrlPattern: 'ws://52.7.165.168:80/d/demo.zebrunner.farm/d6afc6b3a65584ca0813eb8957c6479b9b6ebb11/7434/',

in the same manner connecturlPattern already work:
connectUrlPattern: 'demo.zebrunner.farm:<%= publicPort %>',

[Enhancement]support for android emulator

Dear mcloud team,
I'd like to ask a support related to enhance mcloud, it would be great if mcloud can support to run the test on android emulator.
In the meantime, do we have any workaround solution to deal with it?

Many thanks and best regards,
Binh

default-capabilities is missed for iOS appium

we do generate defaultcapabilities.json for iOS as minimal which include default data for appium per device, for example:

{
  "udid":"$DEVICE_UDID",
  "mjpegServerPort": ${MJPEG_PORT},
  "clearSystemFiles": "false",
  "webDriverAgentUrl":"http://${WDA_HOST}:${WDA_PORT}",
  "preventWDAAttachments": "true",
  "simpleIsVisibleCheck": "true",
  "wdaLocalPort": "${WDA_PORT}",
  "platformVersion": "${PLATFORM_VERSION}",
  "automationName":"${AUTOMATION_NAME}",
  "platformName": "${PLATFORM_NAME}",
  "deviceName": "${DEVICE_NAME}"
}

We have to provide DEFAULT_CAPABILITIES=true to be able to init these values. Also think about similar approach for Android as well.

Without default capabilities it is impossible to run iOS without explicitly adding: udid, webDriverAgent, automationName, and platformVersion

ask about tokens during agent setup

to fulfil configuration we have to provide valid values for:
STF_TOKEN=
AUTHKEY=
SECRET=

During mcloud setup such values must be prepopulated by secured data: zebrunner/mcloud#115. We have to ask these creds during mcloud-agent setup.
Information howto generate and provide valid STF_TOKEN should be added in readme steps

reorganized mcloud-android to be more generic and flexible

  1. rename mcloud-android to mcloud-agent (it supposed to be used for both android and ios devices)
  2. integrate regular zebrunner.sh with common actions (move most of the common operations from zebrunner-farm which should be able to manage devices only)
  3. add dedicated mcloud-grid component as part of the services to have selenium grid as close as possible near the devices (in 2.0+ it might be a must to have several grids per each device lab which is going to be combined on CE level under NGiNC or GGR)
  4. add into the default docker-compose stf-processor service to have it also as close as possible near the devices

automate or provide instructions howto mount `Developer Image` for iOS devices

{"err":"Could not start service:com.apple.instruments.remoteserver.DVTSecureSocketProxy with reason:'InvalidService'. Have you mounted the Developer Image?","level":"fatal","msg":"processcontrol failed","time":"2021-12-09T09:25:08Z"}

https://github.com/zebrunner/stf/pull/263/files#diff-dd2c0eb6ea5cfc6c4bd4eac30934e2d5746747af48fef6da689e85b752f39557R22
and
https://github.com/zebrunner/stf/pull/263/files#diff-e20bab65472b09a5c0acf0c33982552c9f46745b1fdd23a65c76ec33cefb8c3eR23

we have to declare a volume as part of mcloud-agent and push into aws s3 default content... think about re-downloading or symlinking missed images on the fly

improve start operation to skip create containers if already exists

docker: Error response from daemon: Conflict. The container name "/device-iPhone_X-36d077780cb9b93fe876731a3c7359107b4f21bb-appium" is already in use by container "88532c88990bc9d502246540c5d21f7b49c1edbaa403ac94427c2eb564c3e011". You have to remove (or rename) that container to be able to reuse that name.
See 'docker run --help'.
docker: Error response from daemon: Conflict. The container name "/device-iPhone_X-36d077780cb9b93fe876731a3c7359107b4f21bb" is already in use by container "7aec5a37a329a2e6680e5c27af39500fa9a2aaa2f4d702200347baf51fe66a14". You have to remove (or rename) that container to be able to reuse that name.
See 'docker run --help'.
already created

iOS device containers don't start after sudo reboot now

usbmuxd.service - Socket daemon for the usbmux protocol used by Apple devices
   Loaded: loaded (/lib/systemd/system/usbmuxd.service; static; vendor preset: enabled)
   Active: failed (Result: exit-code) since Срд 2021-12-29 20:35:41 +03; 2s ago
  Process: 31517 ExecStart=/usr/sbin/usbmuxd --user usbmux --systemd (code=exited, status=1/FAILURE)
 Main PID: 31517 (code=exited, status=1/FAILURE)

Снж 29 20:35:41 mcloud systemd[1]: Started Socket daemon for the usbmux protocol used by Apple devices.
Снж 29 20:35:41 mcloud usbmuxd[31517]: [20:35:41.631][3] usbmuxd v1.1.0 starting up
Снж 29 20:35:41 mcloud usbmuxd[31517]: [20:35:41.631][0] unlink(/var/run/usbmuxd) failed: Is a directory
Снж 29 20:35:41 mcloud systemd[1]: usbmuxd.service: Main process exited, code=exited, status=1/FAILURE
Снж 29 20:35:41 mcloud systemd[1]: usbmuxd.service: Unit entered failed state.
Снж 29 20:35:41 mcloud systemd[1]: usbmuxd.service: Failed with result 'exit-code'.

investigate distrbuted mcloud setup if extra stf-processor will be located on the same host

https://github.com/openstf/stf/blob/master/doc/DEPLOYMENT.md#stf-processorservice

as stf-processor the main horse of the STF let's investigate if it might resolve the issue with distributed setup when in 8-24 hours android screen became gray/unavailable in spite of the fact that ws connection is good.

test single stf-processor per all android devices or independent processor inside every android container.

if we go with a single stf-processor per server it might have sense to investigate posssibility to start local selenium grid for them as well.

android container can't be started after env reinstall

  1. shutdown existing zebrunner env with mcloud
    device containers are being restarted until new setup appear
  2. setup new one with mcloud
  3. devices try to start services and connect to grid but fail on
/usr/bin/env: 'node': Too many levels of symbolic links
/opt/start_all.sh: line 65: node: command not found
/opt/websockify/websockify/websocket.py:31: UserWarning: no 'numpy' module, HyBi protocol will be slower
  warnings.warn("no 'numpy' module, HyBi protocol will be slower")
Traceback (most recent call last):
  File "/usr/lib/python3.5/runpy.py", line 174, in _run_module_as_main
    mod_name, mod_spec, code = _get_module_details(mod_name, _Error)
  File "/usr/lib/python3.5/runpy.py", line 133, in _get_module_details
    return _get_module_details(pkg_main_name, error)
  File "/usr/lib/python3.5/runpy.py", line 109, in _get_module_details
    __import__(pkg_name)
  File "/opt/websockify/websockify/__init__.py", line 2, in <module>
    from websockify.websocketproxy import *
  File "/opt/websockify/websockify/websocketproxy.py", line 389, in <module>
    'tlsv1_1': ssl.PROTOCOL_TLS | ssl.OP_NO_SSLv2 | ssl.OP_NO_SSLv3 |
AttributeError: module 'ssl' has no attribute 'PROTOCOL_TLS'
/usr/bin/env: 'node': Too many levels of symbolic links
/usr/bin/env: 'node': Too many levels of symbolic links

do not share proxy-port outside to the server

To be able to reuse dynamic browsermob proxy we have to start jenkins-slave in "host" network mode.
Also on this slave java proxy is started i.e. we have to use proxy_port in reality on slave but declare it on android device just for reference

improve recreate device container parametrization

device2docker recreate
adjust code to read and parse correctly full device docker container name.

For now we have to run:
device2docker recreate UDID-Name
but wanna to support
device2docker recreate device-UDID-Name

provide easy way to recreate docker container

device2docker script can react on udev rules and remove/create containers on device disconnect/connect.
At the same time during development we wanna to have possibility to recreate android device container too often which is rather problematic due to the remote work and pandemic situation.
Please, investigate possibility to recreate container via command line like
/usl/local/bin/device2docker <id>
where id might be device name, existing container id etc (something which uniqie identify device/container to recreate).
device2docker script should identify existing container, collect required parameters, remove existing container and start the same using detected args

reorganize docker network/container structure using appium as independent container

we can try to start with independent appium image from hub.docker.com (1.22 or 2.0) and start it in parallel with device container on the same server.
it suppose to combine each device inside single unique docker network and provide stable naming for containers inside aka:
appium
android
etc

Communication between appium and android device should be done via "wi-fi" which is regular tcp/ip connection especially if we talk about single host usage.

Benefits:

  1. fully independent standard appium image (ability to improve via custom docker also exists)
  2. quick movement to new appium without any build steps in mcloud-appium project which is going to be deprecate
  3. potential movement of videorecording on low level (custom appium) with s3 compatible storage integration

Potential negative aspect:

  1. lost customization of error messaging we used to provide info about device udid and name for unsuccessful start attempt
  2. n/a

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.