Merge pull request #1 from moropo-com/readme-changes

improve readme

Author: riglar

LICENSE

@@ -1,6 +1,6 @@
     MIT License
 
-    Copyright (c) DCD LIMITED
+    Copyright (c) devicecloud.dev
 
     Permission is hereby granted, free of charge, to any person obtaining a copy
     of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,239 +1,175 @@
-# devicecloud.dev - Trigger Mobile App Test Run
+# Device Cloud Action
 
-This GitHub Action leverages devicecloud.dev to trigger a mobile app UI test.
+This action is a swap in replacement for the [Maestro Cloud Action](https://github.com/mobile-dev-inc/action-maestro-cloud)
 
-## Installation
+It lets you run your flows on [devicecloud.dev](https://devicecloud.dev) to save money and access extra features.
 
-1. Navigate to the [GitHub Marketplace](https://github.com/marketplace/actions/dcd-trigger-mobile-app-test-run).
-2. On the action page, click `Use latest version` button.
-3. Follow the prompts from github to install the action.
+# Using the action
 
-## Configuration
-
-Here is an example of how to set up the devicecloud.dev GitHub Action in your workflow file:
-
-```yaml
-name: devicecloud.dev Mobile App Test Run
-on:
-  push:
-    branches: [production, staging]
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: devicecloud.dev - Trigger Mobile App Test Run
-        uses: devicecloud-dev/action-trigger-test-run@v1
-        with:
-          api-key: ${{ secrets.DCD_API_KEY }}
-          app-file: path/to/build.apk
-          workspace: path/to/workspace
-          env: '{"VAR_1":"Some variable", "VAR_2":"A different variable"}'
-```
-
-In this example, this action will run whenever a push to the production or staging branch occurs.
-
-### Storing Secrets
-
-The `api-key` should be kept private. You can use GitHub secrets to protect it. To add a secret:
-
-1. Navigate to your GitHub repository and click on the `Settings` tab.
-2. Click on `Secrets` in the left sidebar.
-3. Click `New repository secret`.
-4. Enter `DCD_API_KEY` as the name for the secrets, and paste the corresponding key in the value field.
-
-## Inputs
-
-### `api-key`
-
-**Required** - devicecloud.dev Secret Key, find this in your devicecloud.dev dashboard.
-It follows the UUID schema, e.g. `85e67636-7652-45a8-94ac-e7cdd7e8f869`, however we recommend using Github Secrets for this parameter and provide as follows:
+Add the following to your workflow. Note that you can use the `v1` tag if you want to keep using the latest version of the action, which will automatically resolve to all `v1.minor.patch` versions as they get published.
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
+- uses: devicecloud.dev/maestro-device-cloud@v1
   with:
     api-key: ${{ secrets.DCD_API_KEY }}
+    app-file: <path_to_your_app_file>
 ```
 
-### `app-file`
+# Triggers
 
-**Required if binary-id is not specified** - App binary to run your flows against.
+Trigger this action on (1) pushes to your main branch and (2) pull requests opened against your main branch:
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
-  with:
-    api-key: ${{ secrets.DCD_API_KEY }}
-    app-file: /path/to/your_app.apk
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
 ```
 
-### `app-binary-id`
-
-**Required if app-file is not specified** - The ID of the app binary previously uploaded to Maestro Cloud.
+If you need to use the `pull_request_target` trigger to support repo forks, check out the HEAD of the pull request to ensure that you're running the analysis against the changed code:
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
-  with:
-    api-key: ${{ secrets.DCD_API_KEY }}
-    app-binary-id: your-app-binary-id
+on:
+  push:
+    branches: [master]
+  pull_request_target:
+    branches: [master]
+jobs:
+  run-maestro-on-dcd:
+    name: Run Flows on devicecloud.dev
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.pull_request.head.sha }} # Checkout PR HEAD
 ```
 
-### `workspace`
-
-**Required** - The path to the flow file or folder containing your flows.
+# Android
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
+- uses: devicecloud.dev/maestro-device-cloud@v1
   with:
     api-key: ${{ secrets.DCD_API_KEY }}
-    workspace: /path/to/flows
+    app-file: app/build/outputs/apk/debug/app-debug.apk
 ```
 
-### `env`
+`app-file` should point to an x86 compatible APK file, either directly to the file or a glob pattern matching the file name. When using a pattern, the first matched file will be used.
 
-**Required** - One or more environment variables to inject into your flows. The variables must be passed as stringified JSON in the form `{"VAR_1":"VAL_1","VAR_2":"VAL_2"}`
+# iOS
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
+- uses: devicecloud.dev/maestro-device-cloud@v1
   with:
     api-key: ${{ secrets.DCD_API_KEY }}
-    env: '{"VAR_1":"Some variable", "VAR_2":"A different variable"}'
+    app-file: <app_name>.app
 ```
 
-### `android-api-level`
-
-**Optional** - [Android only] Android API level to run your flow against. Options: `32`, `33`, `34`.
-
-```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
-  with:
-    api-key: ${{ secrets.DCD_API_KEY }}
-    android-api-level: 33
-```
+`app-file` should point to an Apple silicon compatible Simulator .app build, either directly to the file or a glob pattern matching the file name. When using a pattern, the first matched file will be used.
 
-### `android-device`
+# Custom workspace location
 
-**Optional** - [Android only] Android device to run your flow against. Options: `pixel-6`, `pixel-6a`, `pixel-6-pro`, `pixel-7`, `pixel-7-pro`, `generic-tablet`.
+By default, the action is looking for a `.maestro` folder with Maestro flows in the root directory of the project. If you would like to customize this behaviour, you can override it with a `workspace` argument:
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
+- uses: devicecloud.dev/maestro-device-cloud@v1
   with:
     api-key: ${{ secrets.DCD_API_KEY }}
-    android-device: pixel-6
+    app-file: app.zip
+    workspace: myFlows/
 ```
 
-### `async`
+# Custom name
 
-**Optional** - Wait for the results of the run asynchronously.
+A name will automatically be provided according to the following order:
 
-```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
-  with:
-    api-key: ${{ secrets.DCD_API_KEY }}
-    async: true
-```
-
-### `exclude-flows`
+1. If it is a Pull Request, use Pull Request title as name
+2. If it is a normal push, use commit message as name
+3. If for some reason the commit message is not available, use the commit SHA as name
 
-**Optional** - Subdirectories to ignore when building the flow file list.
+If you want to override this behaviour and specify your own name, you can do so by setting the `name` argument:
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
+- uses: devicecloud.dev/maestro-device-cloud@v1
   with:
     api-key: ${{ secrets.DCD_API_KEY }}
-    exclude-flows: 'test/exclude-directory'
+    app-file: app.zip
+    name: My Upload
 ```
 
-### `exclude-tags`
+# Run in async mode
 
-**Optional** - Flows which have these tags will be excluded from the run.
+If you don't want the action to wait until the Upload has been completed as is the default behaviour, set the `async` argument to `true`:
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
+- uses: devicecloud.dev/maestro-device-cloud@v1
   with:
     api-key: ${{ secrets.DCD_API_KEY }}
-    exclude-tags: 'tag1,tag2'
+    app-file: app.zip
+    async: true
 ```
 
-### `google-play`
+# Adding environment variables
 
-**Optional** - [Android only] Run your flow against Google Play devices.
+If you want to pass environment variables along with your upload, The variables must be passed as stringified JSON in the form `{"VAR_1":"VAL_1","VAR_2":"VAL_2"}`:
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
+- uses: devicecloud.dev/maestro-device-cloud@v1
   with:
     api-key: ${{ secrets.DCD_API_KEY }}
-    google-play: true
+    app-file: app.zip
+    env: '{"VAR_1":"Some variable", "VAR_2":"A different variable"}'
 ```
 
-### `include-tags`
+# Using tags
+
+You can use Maestro [Tags](https://maestro.mobile.dev/cli/tags) to filter which Flows to send to Maestro Cloud:
 
-**Optional** - Only flows which have these tags will be included in the run.
+You can either pass a single value, or comma-separated (`,`) values.
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
+- uses: devicecloud.dev/maestro-device-cloud@v1
   with:
     api-key: ${{ secrets.DCD_API_KEY }}
-    include-tags: 'tag3,tag4'
+    app-file: app.zip
+    include-tags: dev, pull-request
+    exclude-tags: excludeTag
 ```
 
-### `ios-device`
+# Specifying Android API Level
 
-**Optional** - [iOS only] iOS device to run your flow against. Options: `iphone-12`, `iphone-12-mini`, `iphone-12-pro-max`, `iphone-13`, `iphone-13-mini`, `iphone-13-pro-max`, `iphone-14`, `iphone-14-plus`, `iphone-14-pro`, `iphone-14-pro-max`, `iphone-15`, `iphone-15-plus`, `iphone-15-pro`,
+You can specify what Android API level to use when running in devicecloud.dev using the `android-api-level` parameter.
+
+The default API level is 33. [Refer to docs](https://docs.devicecloud.dev/getting-started/devices-configuration) for available Android emulator API levels.
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
+- uses: devicecloud.dev/maestro-device-cloud@v1
   with:
     api-key: ${{ secrets.DCD_API_KEY }}
-    ios-device: iphone-14
+    app-file: app.apk
+    android-api-level: 32
 ```
 
-### `ios-version`
+# Specifying iOS version
+
+You can specify what **major** iOS Version to use when running in devicecloud.dev using the `ios-version` parameter.
 
-**Optional** - [iOS only] iOS version to run your flow against. Options: `15`, `16`, `17`.
+The default iOS version is 17. [Refer to docs](https://docs.devicecloud.dev/getting-started/devices-configuration) for available iOS simulator versions.
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
+- uses: devicecloud.dev/maestro-device-cloud@v1
   with:
     api-key: ${{ secrets.DCD_API_KEY }}
+    app-file: app.zip
     ios-version: 16
 ```
 
-### `name`
+# Using an already uploaded App
 
-**Optional** - A custom name for your upload (useful for tagging commits etc).
+You can use an already uploaded App binary in devicecloud.dev using the `app-binary-id` parameter.
 
 ```yaml
----
-- name: devicecloud.dev - Trigger Mobile App Test Run
-  uses: dcd-com/action-trigger-test-run@v1
+- uses: devicecloud.dev/maestro-device-cloud@v1
   with:
     api-key: ${{ secrets.DCD_API_KEY }}
-    name: 'My Custom Upload Name'
+    app-binary-id: <your-app-binary-id>
 ```

action.yml

@@ -1,9 +1,9 @@
-name: 'devicecloud.dev - Trigger Mobile App Test Run'
+name: 'Device Cloud Action'
 author: 'devicecloud.dev'
-description: 'Uses devicecloud.dev.com to execute a mobile app UI test'
+description: 'Uses devicecloud.dev to execute Maestro mobile tests'
 inputs:
   api-key:
-    description: 'devicecloud.dev Api Key - find this in your app settings in the devicecloud.dev dashboard'
+    description: 'devicecloud.dev API Key - find this in your app settings in the devicecloud.dev dashboard'
     required: true
   app-file:
     description: 'Path to the build artifact to upload to devicecloud.dev before running the test'

package.json

@@ -1,6 +1,6 @@
 {
   "name": "dcd-github-action",
-  "description": "devicecloud.dev - Trigger Mobile App Test Run",
+  "description": "run maestro tests on devicecloud.dev",
   "author": "devicecloud.dev",
   "version": "1.0.0",
   "main": "src/index.ts",
@@ -24,4 +24,4 @@
     "@vercel/ncc": "^0.36.1",
     "typescript": "^5.1.6"
   }
-}
+}