e2e-box 0.0.0-stage → 1.0.1

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 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
- # Temporary Holding Version
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
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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