GITBOOK-264: No subject

README.md

@@ -0,0 +1,81 @@
+---
+description: Maestro is the simplest and most effective mobile UI testing framework.
+---
+
+# What is Maestro?
+
+{% embed url="https://vimeo.com/767721667/d972c5f08e" %}
+
+## Why Maestro?
+
+Maestro is built on learnings from its predecessors (Appium, Espresso, UIAutomator, XCTest) and allows you to easily define and test your Flows.
+
+{% hint style="info" %}
+**What are Flows?** Think of Flows as parts of the user journey in your app. Login, Checkout and Add to Cart are three examples of possible Flows that can be defined and tested using Maestro.
+{% endhint %}
+
+* Built-in tolerance to flakiness. UI elements will not always be where you expect them, screen tap will not always go through, etc. Maestro embraces the instability of mobile applications and devices and tries to counter it.
+* Built-in tolerance to delays. No need to pepper your tests with `sleep()` calls. Maestro knows that it might take time to load the content (i.e. over the network) and automatically waits for it (but no longer than required).
+* Blazingly fast iteration. Tests are interpreted, no need to compile anything. Maestro is able to continuously monitor your test files and rerun them as they change.
+* Declarative yet powerful syntax. Define your tests in a `yaml` file.
+* Simple setup. Maestro is a single binary that works anywhere.
+
+## Examples
+
+#### Twitter
+
+<figure><img src=".gitbook/assets/twitter_continuous_v3_fast.gif" alt=""><figcaption></figcaption></figure>
+
+#### Simple Examples
+
+{% tabs %}
+{% tab title="Android" %}
+```yaml
+# flow_contacts_android.yaml
+
+appId: com.android.contacts
+---
+- launchApp
+- tapOn: "Create new contact"
+- tapOn: "First Name"
+- inputText: "John"
+- tapOn: "Last Name"
+- inputText: "Snow"
+- tapOn: "Save"
+```
+{% endtab %}
+
+{% tab title="iOS" %}
+```yaml
+# flow_contacts_ios.yaml
+
+appId: com.apple.MobileAddressBook
+---
+- launchApp
+- tapOn: "John Appleseed"
+- tapOn: "Edit"
+- tapOn: "Add phone"
+- inputText: "123123"
+- tapOn: "Done"
+```
+{% endtab %}
+{% endtabs %}
+
+## Platform Support
+
+| Platform        | Support |
+| --------------- | ------- |
+| **iOS**         | ✅       |
+| **Android**     | ✅       |
+| **ReactNative** | ✅       |
+| **Flutter**     | ✅       |
+
+## Resources
+
+* Blog Post: [**Introducing: Maestro — Painless Mobile UI Automation**](https://blog.mobile.dev/introducing-maestro-painless-mobile-ui-automation-bee4992d13c1)
+* GitHub Repository: [**https://github.com/mobile-dev-inc/maestro**](https://github.com/mobile-dev-inc/maestro)****
+* Public Slack Channel: [**Join the workspace**](https://docsend.com/view/3r2sf8fvvcjxvbtk), then head to the `#maestro` channel
+
+## Get Started
+
+Get started by installing the Maestro CLI:

SUMMARY.md

@@ -0,0 +1,88 @@
+# Table of contents
+
+* [What is Maestro?](README.md)
+* [GitHub Repo](https://github.com/mobile-dev-inc/maestro)
+
+## Getting Started
+
+* [Installing Maestro](getting-started/installing-maestro/README.md)
+  * [macOS](getting-started/installing-maestro/macos.md)
+  * [Windows](getting-started/installing-maestro/windows.md)
+  * [Linux](getting-started/installing-maestro/linux.md)
+* [Run a Sample Flow](getting-started/run-a-sample-flow.md)
+* [Writing Your First Flow](getting-started/writing-your-first-flow.md)
+* [Maestro Studio](getting-started/maestro-studio.md)
+* [Running Flows on CI](getting-started/running-flows-on-ci.md)
+
+## Platform Support
+
+* [Supported Platforms](platform-support/supported-platforms.md)
+* [Android - Views](platform-support/android-views.md)
+* [Android - Jetpack Compose](platform-support/android-jetpack-compose.md)
+* [iOS - UIKit](platform-support/ios-uikit.md)
+* [iOS - SwiftUI](platform-support/ios-swiftui.md)
+* [React Native](platform-support/react-native.md)
+* [Flutter](platform-support/flutter.md)
+* [Web Views](platform-support/web-views.md)
+
+## Examples
+
+* [Android contacts flow automation](examples/android-contacts-flow-automation.md)
+* [Facebook signup flow automation](examples/facebook-signup-flow-automation.md)
+* [Advanced: Wikipedia Android](examples/advanced-wikipedia-android.md)
+
+## Reference
+
+* [Tap On View](reference/tap-on-view.md)
+* [Assertions](reference/assertions.md)
+* [Scroll and Swipe](reference/scroll-and-swipe.md)
+* [Back Button Press](reference/back-button-press.md)
+* [Text Input](reference/text-input.md)
+* [Keyboard](reference/keyboard/README.md)
+  * [Copy & Paste text](reference/keyboard/copy-and-paste-text.md)
+* [Take Screenshot](reference/take-screenshot.md)
+* [Open Link](reference/open-link.md)
+* [App Files](reference/app-files.md)
+* [App Lifecycle](reference/app-lifecycle.md)
+* [Geo Location](reference/geo-location.md)
+* [Build and Install your App](reference/build-and-install-your-app/README.md)
+  * [iOS](reference/build-and-install-your-app/ios.md)
+
+## CLI
+
+* [Cloud](cli/cloud.md)
+* [Test Suites & Reports](cli/test-suites-and-reports.md)
+* [Tags](cli/tags.md)
+* [Recording Your Flow](cli/recording-your-flow.md)
+* [Continuous Mode](cli/continuous-mode.md)
+* [View Hierarchy](cli/view-hierarchy.md)
+
+## Advanced
+
+* [Nested Flows](advanced/nested-flows.md)
+* [Wait](advanced/wait.md)
+* [Loops](advanced/loops.md)
+* [Conditions](advanced/conditions.md)
+* [Parameters & Constants](advanced/parameters-and-constants.md)
+* [JavaScript](advanced/javascript/README.md)
+  * [Run JavaScript](advanced/javascript/run-javascript.md)
+  * [Outputs](advanced/javascript/outputs.md)
+  * [Access element text](advanced/javascript/access-element-text.md)
+  * [Make HTTP(s) requests](advanced/javascript/make-http-s-requests.md)
+* [Experimental](advanced/experimental/README.md)
+  * [Network Mocking](advanced/experimental/network-mocking/README.md)
+    * [Setup](advanced/experimental/network-mocking/setup/README.md)
+      * [Android](advanced/experimental/network-mocking/setup/android.md)
+      * [iOS](advanced/experimental/network-mocking/setup/ios.md)
+    * [Matching Rules](advanced/experimental/network-mocking/matching-rules.md)
+  * [Maestro Mock Server](advanced/experimental/maestro-mock-server/README.md)
+    * [Getting started](advanced/experimental/maestro-mock-server/getting-started.md)
+    * [Writing rules](advanced/experimental/maestro-mock-server/writing-rules.md)
+  * [Maestro WebDriver](advanced/experimental/maestro-webdriver.md)
+* [Detect Maestro in your App](advanced/detect-maestro-in-your-app.md)
+
+## Troubleshooting
+
+* [Known Issues](troubleshooting/known-issues.md)
+* [Bug Report](troubleshooting/bug-report.md)
+* [Rollback Maestro](troubleshooting/rollback-maestro.md)

advanced/conditions.md

@@ -0,0 +1,42 @@
+# Conditions
+
+{% hint style="warning" %}
+By design, Maestro discourages the usage of conditional statements unless absolutely necessary as they could easily ramp up the complexity of your tests.
+{% endhint %}
+
+### runFlow conditionally
+
+```yaml
+- runFlow:
+    when:
+      visible: Some Text
+    file: {reference to another yaml file}
+```
+
+{% content-ref url="nested-flows.md" %}
+[nested-flows.md](nested-flows.md)
+{% endcontent-ref %}
+
+### Conditions
+
+Supported conditions include:
+
+<pre class="language-yaml"><code class="lang-yaml"><strong>visible: { Element matcher }        # True if matching element is visible
+</strong>notVisible: { Element matcher }     # True if matching element is not present
+true: { Value }                     # True if given value is true or not empty
+</code></pre>
+
+### JavaScript
+
+Usage of JavaScript conditions is possible via `true` condition:
+
+```yaml
+- runFlow:
+    when:
+      true: ${MY_PARAMETER == 'Something'}
+    file: subflow.yaml
+```
+
+{% content-ref url="javascript/" %}
+[javascript](javascript/)
+{% endcontent-ref %}

advanced/detect-maestro-in-your-app.md

@@ -0,0 +1,20 @@
+# Detect Maestro in your App
+
+It's sometimes useful to be able to add logic in your app that depends that whether you are running within the context of Maestro. In order to detect Maestro, check to see whether the Maestro-specific port is open on your device:
+
+| Platform | Maestro Port on Device |
+| -------- | ---------------------- |
+| iOS      | 22087                  |
+| Android  | 7001                   |
+
+Here's an example of how to check for Maestro in an Android app:
+
+```kotlin
+fun isMaestro(): Boolean {
+    return try {
+        Socket("localhost", 7001).use { true }
+    } catch(ignored: IOException) {
+        false
+    }
+}
+```

advanced/experimental/README.md

@@ -0,0 +1,17 @@
+# Experimental
+
+Experimental features are not yet supported by Maestro Cloud and breaking changes might be introduced as we work on them. Use with caution.
+
+Your feedback is vital to us and will help us decide the future of those features.
+
+{% content-ref url="network-mocking/" %}
+[network-mocking](network-mocking/)
+{% endcontent-ref %}
+
+{% content-ref url="maestro-mock-server/" %}
+[maestro-mock-server](maestro-mock-server/)
+{% endcontent-ref %}
+
+{% content-ref url="maestro-webdriver.md" %}
+[maestro-webdriver.md](maestro-webdriver.md)
+{% endcontent-ref %}

advanced/experimental/maestro-mock-server/README.md

@@ -0,0 +1,37 @@
+# Maestro Mock Server
+
+{% hint style="warning" %}
+This is an experimental feature. It is not yet supported by Maestro Cloud and breaking changes might be introduced as we work. on it.
+{% endhint %}
+
+### Basics
+
+Here are key facts about Maestro Mock Server.
+
+* Maestro Mock Server works on a concept of _rules_, that are defined in a _workspace._
+* A rule describes what HTTP(s) request to incercept and what to reply back. 
+* Rules are defined in JavaScript files. A single JS file can contain multiple rules.
+* There must always be a root `index.js` file in the mock server workspace. From that file, other JS files can be imported defining other rules.
+* Maestro Mock Server requires integrating Maestro SDK in order to send all HTTP requests to the Mock Server instead of your original API
+* Network requests that did not match any rule will continue to their real destination as if there was no mocking in place.
+* In order for rules to be applied, they need to be _deployed_ using `maestro mockserver deploy <path to your rules>`
+
+Here is the simplest example of a rule that will match a `GET` call to your `/endpoint` path and will reply with `Hello Maestro` instead of the usual response:
+
+```javascript
+// .maestro/mockserver/index.js
+
+get('/endpoint', (req, res) => {
+    res.json({
+        message: "Hello Maestro"
+    });
+});
+```
+
+### Getting started
+
+Please follow the documentation to get up and running with Maestro Mock Server!
+
+{% content-ref url="getting-started.md" %}
+[getting-started.md](getting-started.md)
+{% endcontent-ref %}

advanced/experimental/maestro-mock-server/getting-started.md

@@ -0,0 +1,54 @@
+# Getting started
+
+{% hint style="info" %}
+Note that this is Android only for now, iOS support is coming soon!
+{% endhint %}
+
+First, install the latest version of `maestro` as this functionality is available from version `1.22.0` and up.
+
+{% content-ref url="../../../getting-started/installing-maestro/" %}
+[installing-maestro](../../../getting-started/installing-maestro/)
+{% endcontent-ref %}
+
+### Setup
+
+Run the following to start the Maestro Mock Server:
+
+```
+maestro mockserver open
+```
+
+There, you will be presented with setup instructions walking you through how to integrate the Maestro SDK into your application. Essentially, the following steps are required:
+
+1\) Add the following dependency to your `build.gradle` (or similar):
+
+```
+implementation 'dev.mobile:maestro-sdk-android:+'
+```
+
+\
+2\) Initialize the Maestro SDK:
+
+```
+MaestroSdk.init("<project_id>")
+```
+
+Note that the project id will be prefilled in your setup instructions, but if you ever want to retrieve it you can run `maestro mockserver projectid`
+
+3\) Then, replace your API base url with a base url provided by Maestro SDK.
+
+```
+val baseUrl = MaestroSdk.mockServer().url("https://api.company.com")
+```
+
+You can then use `baseUrl` as you normally would.
+
+{% hint style="warning" %}
+The URL passed in should start with `https://` and should **not** have a trailing /, as that is added by Maestro SDK automatically. You can then access your API endpoint by sending requests to `${baseUrl}${path}` - you don't need to add `/` in between.
+{% endhint %}
+
+4\) Build and run your app and you should start seeing events in the Maestro Mock Server UI!
+
+### Initializing mockserver workspace
+
+You can run `maestro mockserver init` to generate a sample rule locally that you can keep building on.