e2e-box 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +202 -2
- package/agent/dist/e2e-box-agent.jar +0 -0
- package/dist/cli.js +13251 -0
- package/package.json +64 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pedro Laxe and e2e-box contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,203 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pedrolaxe/e2e-box/main/assets/logo-dark.svg">
|
|
4
|
+
<img src="https://raw.githubusercontent.com/pedrolaxe/e2e-box/main/assets/logo-light.svg" alt="e2e-box" width="420">
|
|
5
|
+
</picture>
|
|
6
|
+
</p>
|
|
2
7
|
|
|
3
|
-
|
|
8
|
+
<p align="center">
|
|
9
|
+
End-to-end testing for native Android apps <strong>over adb</strong>, with Maestro-style YAML flows.<br>
|
|
10
|
+
A local Next.js dashboard with live device mirroring, a live log, a step queue and a flow recorder.
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<img src="https://img.shields.io/badge/Android-adb-4ade80?style=flat-square" alt="Android over adb">
|
|
15
|
+
<img src="https://img.shields.io/badge/flows-YAML%20(Maestro)-a78bfa?style=flat-square" alt="Maestro-style YAML flows">
|
|
16
|
+
<img src="https://img.shields.io/badge/Next.js-15-1b1631?style=flat-square" alt="Next.js 15">
|
|
17
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-facc15?style=flat-square" alt="MIT license"></a>
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
<p align="center">
|
|
21
|
+
<img src="https://raw.githubusercontent.com/pedrolaxe/e2e-box/main/assets/banner.png" alt="e2e-box: dashboard with device mirror, YAML editor and live steps" width="820">
|
|
22
|
+
</p>
|
|
23
|
+
|
|
24
|
+
## Getting started
|
|
25
|
+
|
|
26
|
+
**Just the CLI** (in your app's repo, or in CI):
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npx e2e-box # runs the flows in .e2e-box/ or .maestro/
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
**The dashboard** (mirror, recorder, editor) runs from a clone:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
git clone https://github.com/pedrolaxe/e2e-box.git && cd e2e-box
|
|
36
|
+
pnpm install
|
|
37
|
+
pnpm dev # http://127.0.0.1:3334
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Requirements: `adb` (Android SDK platform-tools) and an Android device with **USB debugging** turned on (or an emulator).
|
|
41
|
+
adb is looked up in `ADB_PATH`, `ANDROID_HOME`, `%LOCALAPPDATA%\Android\Sdk` and finally on the `PATH`.
|
|
42
|
+
|
|
43
|
+
The dashboard is available in **English** and **Brazilian Portuguese**: the EN/PT switch at the top changes it and remembers
|
|
44
|
+
your choice; without one, it follows the browser language. The engine log and the CLI output are in Portuguese for now.
|
|
45
|
+
|
|
46
|
+
## On-device agent
|
|
47
|
+
|
|
48
|
+
To read the screen quickly, e2e-box pushes a small agent (`agent/dist/e2e-box-agent.jar`, ~5KB) to
|
|
49
|
+
`/data/local/tmp` and runs it with `app_process` (no APK install). It keeps the accessibility connection
|
|
50
|
+
open and answers in ~20ms, versus 1–3s for `uiautomator dump`; it also types **accented** text straight into
|
|
51
|
+
the focused field (no ADBKeyboard needed). It starts on the first screen read and is pushed again when the jar changes.
|
|
52
|
+
|
|
53
|
+
- With the agent, the engine waits for the **screen to settle** (two identical reads) after each action instead of
|
|
54
|
+
fixed pauses. Without it (`E2E_BOX_NO_AGENT=1`, or if it fails to start), it falls back to `uiautomator dump` and pauses.
|
|
55
|
+
- While the agent is connected, an external `uiautomator dump` does not work (only one client at a time).
|
|
56
|
+
- Security: each session starts its own agent (stopping previous ones) with a random socket name and secret;
|
|
57
|
+
the agent only accepts connections from `shell`/root, and both sides prove the secret via HMAC before any
|
|
58
|
+
command. Other apps on the device cannot read the screen or receive what is typed.
|
|
59
|
+
- Only one process runs flows per device: the dashboard and the CLI would kill each other's agent. Whoever comes second
|
|
60
|
+
gets a notice saying who is running, and the inspector and recorder stay locked on that device until it finishes.
|
|
61
|
+
- Rebuild after changing `agent/src`: `node agent/build.mjs` (JDK 17+ and Android SDK with build-tools).
|
|
62
|
+
|
|
63
|
+
## Workspaces
|
|
64
|
+
|
|
65
|
+
`e2e-box.config.json` lists the flow folders. It ships with **Exemplos** (`./flows`), which opens Settings and runs
|
|
66
|
+
on any Android device.
|
|
67
|
+
|
|
68
|
+
For your app, the best setup is to keep the flows in the app's repo, in **`.e2e-box/`** or **`.maestro/`**, and clone
|
|
69
|
+
e2e-box next to it. The `+` in the sidebar suggests sibling folders (pointing to whichever of `.e2e-box/` or `.maestro/`
|
|
70
|
+
already exists) and detects the `appId` of Expo/React Native apps; or edit the file:
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{ "id": "my-app", "name": "My app", "dir": "../my-app/.maestro", "appId": "com.company.myapp" }
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
With no `workspaces` in `e2e-box.config.json` (or no file at all), e2e-box looks for `.e2e-box/` and `.maestro/` in the
|
|
77
|
+
folder it runs from and uses each one as a workspace, with the `appId` from `app.json`. A `config.yaml` at the root of the
|
|
78
|
+
folder (Maestro's workspace config) is not listed as a flow.
|
|
79
|
+
|
|
80
|
+
Test usernames and passwords go in `e2e-box.local.json` (kept out of git), per workspace; see `e2e-box.local.example.json`.
|
|
81
|
+
|
|
82
|
+
Files in subfolders show up as subflows (called with `runFlow`).
|
|
83
|
+
|
|
84
|
+
## Creating flows from the dashboard
|
|
85
|
+
|
|
86
|
+
1. `+` on a workspace creates the file.
|
|
87
|
+
2. On the mirror, pick a mode:
|
|
88
|
+
- **Inspect**: clicking shows the element (text, desc, id) and suggests steps (`tapOn`, `assertVisible`, `point`).
|
|
89
|
+
- **● Record**: every tap/swipe goes to the device **and** becomes a YAML step at the cursor line.
|
|
90
|
+
- Vertical scrolling becomes `scrollUntilVisible` up to the element of the next tap (or `scroll` if there is none).
|
|
91
|
+
- Text that changes becomes a regex: a greeting with a name (`"Hello .*"`) goes in that way; numbers (`"Orders \(\d+\)"`) are offered as an option.
|
|
92
|
+
- Tapping a text field focuses the "type on the device" box, and whatever you type becomes `inputText`.
|
|
93
|
+
- Stop with **■ Stop and save**, the **■ REC** badge on the screen, or **Esc** (saves the YAML).
|
|
94
|
+
- **Control**: just controls the device.
|
|
95
|
+
3. The "type on the device" field generates `inputText`; the back/hide keyboard/↵ buttons generate `back`/`hideKeyboard`/`pressKey`.
|
|
96
|
+
4. `Ctrl+S` saves, `Ctrl+Enter` runs. If the `---` between the header and the steps is missing, e2e-box adds it.
|
|
97
|
+
|
|
98
|
+
The mirror uses **video** (`screenrecord` in H.264, decoded in the browser with WebCodecs, ~20–50 fps) and falls back
|
|
99
|
+
to **screenshots** (`screencap`, ~1 fps) if the browser does not support it or the video fails; the button under the device
|
|
100
|
+
switches between them. Only one video at a time: the tab that opens the video keeps it, the other switches to screenshots and
|
|
101
|
+
takes the video back when you return to it.
|
|
102
|
+
|
|
103
|
+
Each run is stored in `runs/<date>/` with a `report.json`; on failure, also `falha.png` and `falha-hierarquia.xml`.
|
|
104
|
+
|
|
105
|
+
## Trusting your tests
|
|
106
|
+
|
|
107
|
+
- **Passed without checks**: if no step verified the result, the dashboard shows "Passed without checks" instead of green, and
|
|
108
|
+
the CLI warns. `assertVisible`, `assertNotVisible`, `assertTrue` and `extendedWaitUntil` count; checks done by the precondition do not.
|
|
109
|
+
- **Fragile steps**: the editor flags `tapOn: ""`, the screen root (`id: action_bar_root`) and taps by `point`. When the flow runs,
|
|
110
|
+
the engine reads the element under the tap and the editor offers to replace the step with a text selector.
|
|
111
|
+
- **Precondition**: `onFlowStart` in the header runs before the steps. If it fails, the error says the precondition was not met
|
|
112
|
+
instead of the flow tapping around on the wrong screen. Example: `onFlowStart: [{ runFlow: subflows/go-home.yaml }]`.
|
|
113
|
+
- **Run part of a flow**: with the cursor on a step, **▶ Step N** runs only that step and **▶ From here** runs to the end, on
|
|
114
|
+
whatever screen the device is on (without `onFlowStart`). Partial runs do not change the flow's status dot in the list.
|
|
115
|
+
- **Run details**: clicking a run opens its timeline, with a screenshot per step, each step's log and, on failure, the error and
|
|
116
|
+
what was on screen. Screenshots are kept for the 30 most recent runs; the CLI does not take them.
|
|
117
|
+
- **Flakiness**: the **5x** button runs the flow five times in a row and shows how many passed and which step failed.
|
|
118
|
+
|
|
119
|
+
## Multiple devices, cables and rotation
|
|
120
|
+
|
|
121
|
+
- **Multiple devices**: each one has its own run. Pick the device at the top and run; when you switch, the dashboard shows the
|
|
122
|
+
other device's log and steps, and the list marks which ones are `running`. The mirror shows one device at a time.
|
|
123
|
+
- **Device disconnected**: the flow stops immediately with a disconnected-device error (no waiting for timeouts, no `retry`,
|
|
124
|
+
no evidence). The dashboard waits for the same device to come back, and the mirror and agent reconnect on their own.
|
|
125
|
+
- **Rotated screen**: the engine tracks rotation on every step (`%` points and "on screen" checks) and the mirror reopens in
|
|
126
|
+
landscape, with taps landing in the right place.
|
|
127
|
+
|
|
128
|
+
## CLI (CI / terminal)
|
|
129
|
+
|
|
130
|
+
Published on npm with no dependencies: it only needs Node 18+ and `adb`. Use `npx e2e-box`, or add it to your app with
|
|
131
|
+
`npm i -D e2e-box` and call `e2e-box` from a script. Inside the e2e-box repo, `pnpm e2e` runs the same CLI from source.
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
npx e2e-box # no target: the .e2e-box/ and .maestro/ folders in the current directory
|
|
135
|
+
npx e2e-box .maestro/login.yaml
|
|
136
|
+
npx e2e-box .maestro/ -e USER=test -v
|
|
137
|
+
npx e2e-box .maestro/ --all-devices # on every connected device, at the same time
|
|
138
|
+
npx e2e-box my-app:login.yaml # <workspace>:<file>, with an e2e-box.config.json
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Exits with code 1 if any flow fails and 2 if it cannot start (no device, or the device is busy).
|
|
142
|
+
`-d <serial>` picks the device; repeat it for several, or use `--all-devices`. Each device runs the flows in sequence,
|
|
143
|
+
devices run in parallel, and each output line starts with the serial. Evidence for failed runs goes to `runs/`.
|
|
144
|
+
|
|
145
|
+
### GitHub Actions
|
|
146
|
+
|
|
147
|
+
```yaml
|
|
148
|
+
name: e2e
|
|
149
|
+
on: [push]
|
|
150
|
+
jobs:
|
|
151
|
+
android:
|
|
152
|
+
runs-on: ubuntu-latest
|
|
153
|
+
steps:
|
|
154
|
+
- uses: actions/checkout@v4
|
|
155
|
+
- uses: actions/setup-node@v4
|
|
156
|
+
with:
|
|
157
|
+
node-version: 22
|
|
158
|
+
- name: Enable KVM
|
|
159
|
+
run: |
|
|
160
|
+
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
|
|
161
|
+
sudo udevadm control --reload-rules
|
|
162
|
+
sudo udevadm trigger --name-match=kvm
|
|
163
|
+
- uses: reactivecircus/android-emulator-runner@v2
|
|
164
|
+
with:
|
|
165
|
+
api-level: 34
|
|
166
|
+
arch: x86_64
|
|
167
|
+
script: |
|
|
168
|
+
adb install -r app-release.apk # your build
|
|
169
|
+
npx e2e-box
|
|
170
|
+
- uses: actions/upload-artifact@v4
|
|
171
|
+
if: failure()
|
|
172
|
+
with:
|
|
173
|
+
name: e2e-runs
|
|
174
|
+
path: runs/
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## Supported commands
|
|
178
|
+
|
|
179
|
+
| Command | Notes |
|
|
180
|
+
|---|---|
|
|
181
|
+
| `launchApp` | `appId`, `clearState`, `stopApp`, `permissions` (grants the denied ones) |
|
|
182
|
+
| `stopApp`, `killApp`, `clearState` | |
|
|
183
|
+
| `tapOn`, `doubleTapOn`, `longPressOn` | text, `id`, `index`, `point: "50%,89%"`, `repeat`, `optional`, relative (`below`, `above`, `leftOf`, `rightOf`, `childOf`, `containsChild`) |
|
|
184
|
+
| `inputText`, `inputRandom*`, `eraseText`, `copyTextFrom`, `pasteText` | accents through the agent; without it, through [ADBKeyboard](https://github.com/senzhk/ADBKeyBoard) if it is the active keyboard, or without accents (with a warning). Text from `${VAR}` shows as `•••` in the log |
|
|
185
|
+
| `pressKey`, `back`, `hideKeyboard` | Enter, Back, Home, Backspace, Tab, Escape, Volume… |
|
|
186
|
+
| `scroll`, `swipe`, `scrollUntilVisible` | `direction`, `start`/`end`, `from`, `timeout`, `visibilityPercentage` |
|
|
187
|
+
| `assertVisible`, `assertNotVisible`, `assertTrue`, `extendedWaitUntil` | waits up to `lookupTimeoutMs` (7s) |
|
|
188
|
+
| `runFlow` | `file`, `commands`, `when: visible/notVisible/platform`, `env` |
|
|
189
|
+
| `repeat`, `retry` | `times`, `while`, `maxRetries` |
|
|
190
|
+
| `waitForAnimationToEnd`, `takeScreenshot`, `openLink` | |
|
|
191
|
+
| `wait: 1000` | e2e-box extension (pause in ms) |
|
|
192
|
+
|
|
193
|
+
Variables: `${NAME}` comes from the header's `env:`, the workspace `env`, `runFlow`, or the env field in the dashboard / `-e` in the CLI.
|
|
194
|
+
Text matching works like Maestro: a case-insensitive regex that must match the whole text, against `text`, `content-desc` and `hint`.
|
|
195
|
+
|
|
196
|
+
Not supported yet (skipped with a warning): `evalScript`, `runScript`, `setLocation`, `travel`, `addMedia`, video recording and AI commands.
|
|
197
|
+
|
|
198
|
+
Security: the API only accepts calls from its own page (local Host, the app's Origin and JSON); workspaces must live inside
|
|
199
|
+
the folder that contains e2e-box, and subflows inside their workspace.
|
|
200
|
+
|
|
201
|
+
## License
|
|
202
|
+
|
|
203
|
+
[MIT](LICENSE)
|
|
Binary file
|