|
| 1 | +{ |
| 2 | + "cells": [ |
| 3 | + { |
| 4 | + "metadata": {}, |
| 5 | + "cell_type": "markdown", |
| 6 | + "source": [ |
| 7 | + "# Welcome to the Puma Tutorial\n", |
| 8 | + "\n", |
| 9 | + "Puma — *Programmable Utility for Mobile Automation* — is a Python library that lets you control Android apps through simple, high‑level actions.\n", |
| 10 | + "It supports a variety of popular applications such as **Telegram**, **TeleGuard**, **WhatsApp**, **Google Maps**, and more (see the README.md)\n", |
| 11 | + "\n", |
| 12 | + "In this tutorial you will learn how to use Puma to interact with the a few of these apps: Sending messages with TeleGuard, navigating using Google Maps and conduct web searches using Google Chrome. Finally, you will build a full scenario, using multiple applications simultaneously to mimic real user behavior.\n", |
| 13 | + "\n", |
| 14 | + "The workshop is primarily aimed at _using_ Puma. If you’re interested in extending Puma itself by extending or improving features, or by adding support for new apps, check out bonus **Exercise 5**. Please refer to the [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines, or ask one of us for help." |
| 15 | + ], |
| 16 | + "id": "64ab1c9aa8a8e397" |
| 17 | + }, |
| 18 | + { |
| 19 | + "metadata": {}, |
| 20 | + "cell_type": "markdown", |
| 21 | + "source": [ |
| 22 | + "# Exercise 1: Send us a message with TeleGuard\n", |
| 23 | + "In this exercise, you will learn to use Puma through a few simple actions.\n", |
| 24 | + "We will add a contact and send a message using the chat app TeleGuard. TeleGuard does not require personal information such as a phone number, making it the perfect candidate for a tutorial!\n", |
| 25 | + "\n", |
| 26 | + "> ❔ New to jupyter notebooks? You need to run all executable cells sequentially in order to initialize the variables. Weird behaviour and/or crashes? Restart the kernel and rerun the code blocks, top of screen: Kernel -> Restart Kernel...\n", |
| 27 | + "\n", |
| 28 | + "Your TeleGuard ID is displayed in a \"chat\" with TeleGuard, and can be shared with other users to message one another.\n", |
| 29 | + "\n", |
| 30 | + "Fill in your device udid and initialize TeleGuard.\n", |
| 31 | + "\n", |
| 32 | + "The device udid can be found by running\n", |
| 33 | + "```bash\n", |
| 34 | + "adb devices\n", |
| 35 | + "```\n", |
| 36 | + "from your terminal. If you use an emulator, the udid has already been filled in, as emulators have default udids. For physical devices, the udid is unique for the device and always needs to be checked.\n" |
| 37 | + ], |
| 38 | + "id": "465be2cf0878a0b4" |
| 39 | + }, |
| 40 | + { |
| 41 | + "metadata": {}, |
| 42 | + "cell_type": "code", |
| 43 | + "source": [ |
| 44 | + "from puma.apps.android.teleguard.teleguard import TeleGuard\n", |
| 45 | + "\n", |
| 46 | + "# This initializes an object through which we can execute TeleGuard actions. Initialization can take a while. The device udid can be found by running `adb devices` in your terminal\n", |
| 47 | + "teleguard = TeleGuard(device_udid=\"emulator-5554\")" |
| 48 | + ], |
| 49 | + "id": "4594520f1f70d68", |
| 50 | + "outputs": [], |
| 51 | + "execution_count": null |
| 52 | + }, |
| 53 | + { |
| 54 | + "metadata": {}, |
| 55 | + "cell_type": "markdown", |
| 56 | + "source": [ |
| 57 | + "You probably got an error stating Appium is not running. To establish a connection to the Appium driver, we need to start Appium first.\n", |
| 58 | + "In a terminal, run the command\n", |
| 59 | + "```bash\n", |
| 60 | + "appium\n", |
| 61 | + "```\n", |
| 62 | + "Leave this terminal open and do not stop the Appium process, then rerun the above code." |
| 63 | + ], |
| 64 | + "id": "5494fac7991d6161" |
| 65 | + }, |
| 66 | + { |
| 67 | + "metadata": {}, |
| 68 | + "cell_type": "markdown", |
| 69 | + "source": [ |
| 70 | + "### Appium\n", |
| 71 | + "Appium is a framework for testing applications, based on Selenium. In Puma, we use Appium to execute actions on the device.\n", |
| 72 | + "In this context, we define functions in Python that exist of one or more `Appium actions`. An Appium action is an action on the phone, for instance tapping on an element. In our Python code, we define functions executing one or more\n", |
| 73 | + "Appium actions, for instance `send_message()` where the message box is tapped, text is added to the box and the send button is clicked." |
| 74 | + ], |
| 75 | + "id": "800446abe5fe54c2" |
| 76 | + }, |
| 77 | + { |
| 78 | + "metadata": {}, |
| 79 | + "cell_type": "markdown", |
| 80 | + "source": [ |
| 81 | + "## 1. Add a contact\n", |
| 82 | + "To send messages, you need to have someone to talk to. This can be done by adding a contact.\n", |
| 83 | + "If you are attending a workshop, the TeleGuard ID of the workshop host is visible on screen, add them! If you are doing the tutorial by yourself, create an additional TeleGuard ID on another device, or ask someone else to do it. Enter the ID in the cell below and execute the code:" |
| 84 | + ], |
| 85 | + "id": "733fe69884e9c1f8" |
| 86 | + }, |
| 87 | + { |
| 88 | + "metadata": {}, |
| 89 | + "cell_type": "code", |
| 90 | + "source": [ |
| 91 | + "contact_id = '' # TeleGuard ID of the person you want to add\n", |
| 92 | + "teleguard.add_contact(contact_id)" |
| 93 | + ], |
| 94 | + "id": "32e97c439cef4e75", |
| 95 | + "outputs": [], |
| 96 | + "execution_count": null |
| 97 | + }, |
| 98 | + { |
| 99 | + "metadata": {}, |
| 100 | + "cell_type": "markdown", |
| 101 | + "source": [ |
| 102 | + "## 2. Send a message\n", |
| 103 | + "Send a message to the contact you just added. Enter their username and the message below." |
| 104 | + ], |
| 105 | + "id": "da3e4a385a663d3f" |
| 106 | + }, |
| 107 | + { |
| 108 | + "metadata": {}, |
| 109 | + "cell_type": "code", |
| 110 | + "source": [ |
| 111 | + "recipient_username = '' # Username or group name you will send a message to\n", |
| 112 | + "message = '' # Message to send\n", |
| 113 | + "\n", |
| 114 | + "teleguard.send_message(message=message, conversation=recipient_username)" |
| 115 | + ], |
| 116 | + "id": "9b0e8b4d27d7e2e0", |
| 117 | + "outputs": [], |
| 118 | + "execution_count": null |
| 119 | + }, |
| 120 | + { |
| 121 | + "metadata": {}, |
| 122 | + "cell_type": "markdown", |
| 123 | + "source": [ |
| 124 | + "## 3. Send a picture with TeleGuard\n", |
| 125 | + "Apart from sending messages, Puma also supports sending pictures. Each application has a `README.md`, listing all functionality of an application and the options. Sending a picture can be done in several ways, e.g. sending a picture from the gallery or taking a new picture with the camera. Lastly, an optional caption can be added.\n", |
| 126 | + "_Note_:\n", |
| 127 | + "`picture_id` is the index of the picture shown in the Android media picker (the first picture has index 1).\n", |
| 128 | + "If `picture_id` is omitted, TeleGuard will open the camera, take a picture, and send it.\n", |
| 129 | + "`caption` is optional – you can omit it to send the image without text." |
| 130 | + ], |
| 131 | + "id": "6ff03781ea8d1e41" |
| 132 | + }, |
| 133 | + { |
| 134 | + "metadata": {}, |
| 135 | + "cell_type": "code", |
| 136 | + "source": [ |
| 137 | + "teleguard.send_picture(conversation=\"\",\n", |
| 138 | + " #optional parameters, you can also remove them\n", |
| 139 | + " picture_id=1, caption=\"\")" |
| 140 | + ], |
| 141 | + "id": "a7e4d7bbfb65737a", |
| 142 | + "outputs": [], |
| 143 | + "execution_count": null |
| 144 | + }, |
| 145 | + { |
| 146 | + "metadata": {}, |
| 147 | + "cell_type": "markdown", |
| 148 | + "source": [ |
| 149 | + "#### What to observe\n", |
| 150 | + "After running the cell, the TeleGuard app on the device should open the media picker (or camera) and automatically send the selected image.\n", |
| 151 | + "The caption (if provided) appears in the chat bubble alongside the picture.\n", |
| 152 | + "If you omitted `picture_id`, a new photo will be captured and sent.\n", |
| 153 | + "Feel free to experiment with different picture_id values or captions to see how the app behaves." |
| 154 | + ], |
| 155 | + "id": "af07003adf5f9961" |
| 156 | + }, |
| 157 | + { |
| 158 | + "metadata": {}, |
| 159 | + "cell_type": "code", |
| 160 | + "source": "", |
| 161 | + "id": "65597861fba26725", |
| 162 | + "outputs": [], |
| 163 | + "execution_count": null |
| 164 | + } |
| 165 | + ], |
| 166 | + "metadata": {}, |
| 167 | + "nbformat": 4, |
| 168 | + "nbformat_minor": 5 |
| 169 | +} |
0 commit comments