A beginner-friendly introduction to Mobilewright: what it is, why it's great, and how closely it resembles Playwright.
Mobile test automation has a reputation for being painful. You install lots of tools, run servers in the background, wait on things by hand, and get tests that fail for no clear reason.
If you used Playwright for web testing, you know it doesn't have to be that way. The good news is that the same experience now exists for mobile apps. It's called Mobilewright. Oh yes!!
In this post I'll explain what Mobilewright is, why I like it, and how closely it resembles Playwright. You don't need any mobile testing experience to follow along.
What is Mobilewright?
Mobilewright is an open-source framework for writing automated tests for Android and iOS apps. It lets you:
- Open your app on an emulator, a simulator or a real phone
- Find things on the screen (buttons, text fields, labels)
- Tap, type, swipe and scroll
- Check that the app shows what it should
In short, it's Playwright, but for phones. Its authors designed it to feel the same: the same way of writing tests, the same kind of commands, and the same reports.
Why QAs will love it
1. Setup is short
Traditional mobile automation often means setting up a separate automation server, drivers and a lot of configuration before your first test runs.
With Mobilewright you install a package, run one command to check your setup (mobilewright doctor), and you're ready. That command tells you what is missing and what to fix, so you are not left guessing.
2. It waits for you
The most common beginner mistake in UI testing is adding "sleep 5 seconds" everywhere and hoping the app has loaded.
Like Playwright, Mobilewright waits automatically. When you say "tap this button", it waits until the button appears. When you say "expect this text to be visible", it keeps checking until the text shows up or a timeout runs out. Your tests get faster and less flaky without extra effort from you.
3. One test can cover Android and iOS
You write the test once and choose which device to run it on. The same test can run on an Android emulator today and an iPhone simulator tomorrow. Important to note is you can use same element locator for both Android and iOS, which is not the case with other frameworks.
4. Local first, cloud when you need it
You can start on your laptop with a free emulator. When you are ready, the same tests can run on real devices in the cloud, usually by changing one setting and not your tests.
5. Reports that show what went wrong
When a test fails, you get an HTML report that shows which step failed, the error, and a snapshot of what was on the screen. Debugging turns into reading the report instead of guessing.
How Mobilewright resembles Playwright
This is what makes it so easy to learn. If you know Playwright, here's how the concepts map:
| Playwright (web) | Mobilewright (mobile) |
|---|---|
page: the browser tab |
screen: the phone screen |
browser |
device: the phone itself |
getByRole, getByText, getByTestId
|
Same locator methods |
click() |
tap() |
fill() |
fill() |
expect(...).toBeVisible() |
expect(...).toBeVisible() |
playwright.config.ts |
mobilewright.config.ts |
| Projects = browsers | Projects = devices |
npx playwright test |
npx mobilewright test |
npx playwright show-report |
npx mobilewright show-report |
| Fixtures and Page Objects | Fixtures and Screen Objects |
Here's one small example so you can see it for yourself.
Playwright (web):
test('user can log in', async ({ page }) => {
await page.getByTestId('username').fill('demo');
await page.getByTestId('password').fill('Bigs3cret!');
await page.getByRole('button', { name: 'Log in' }).click();
await expect(page.getByText('Welcome')).toBeVisible();
});
Mobilewright (mobile):
test('user can log in', async ({ screen }) => {
await screen.getByTestId('username').fill('demo');
await screen.getByTestId('password').fill('Bigs3cret!');
await screen.getByRole('button', { name: 'Log in' }).tap();
await expect(screen.getByText('Welcome')).toBeVisible();
});
That's the whole difference: page becomes screen and click becomes tap. Everything else carries over, including your habits, your project structure and your team's existing Playwright knowledge.
Beginner tips from my experience
Ask developers for test IDs. The most reliable way to find an element is a stable ID that the app developers add for testing. It's a small request that makes every test more stable.
Use the Page Object pattern from day one. Create one class per app screen (for example a Login screen or a Home screen) that holds its buttons and actions. Your tests then read like plain English, and when the UI changes you update one file.
Keep tests independent. Start every test from a fresh app state. If one test depends on another, a single failure spreads through the whole suite.
Prepare data outside the app. If a test needs a user account, create it with an API call, not by tapping through sign-up screens. Save the UI steps for what you actually want to test.
Pin your versions. Mobilewright is young and improves quickly. That's exciting, but pin your versions so an update doesn't surprise you in the middle of a sprint.
Read the failure report before changing code. The screen snapshot in the report usually tells you exactly what went wrong.
Bonus: it works well with BDD
If your team likes writing tests in plain language (Given / When / Then), Mobilewright works with Gherkin feature files through Playwright's BDD tooling. Product owners and testers can read the scenarios, and the automation runs underneath.
Final thoughts
For years, mobile testing felt like a different, more difficult world than web testing. Mobilewright closes that gap. If you can write a Playwright test, you can write a mobile test.
Install it, run doctor, write one test for your login screen, and watch it run on a phone. That first green test is very satisfying. 📱✅
Have you tried testing mobile apps yet? What was the hardest part for you? Let me know in the comments! 👇
Top comments (0)