# Connecting adb in WSL2 to a phone or the Windows emulator

I run Claude Code and Gradle inside WSL2. When I wrote the `device-testing` skill for an Android reminders app, the emulator ran on Windows, so the skill starts with how to bridge the two. Later I moved the emulator into WSL2 itself, headless on `/dev/kvm`, which skips option B. For a real phone, A is still the skill's first choice.

Keep the repo on WSL's ext4 (`~/...`). Gradle on `/mnt/c` is much slower.

## A: physical device over Wi-Fi

Android 11 and later: Developer options → [Wireless debugging](https://developer.android.com/tools/adb#connect-to-a-device-over-wi-fi) → Pair device with pairing code.

```bash
adb pair 192.168.1.x:PAIR_PORT      # once, with the code shown on the phone
adb connect 192.168.1.x:CONN_PORT   # every session; the port changes after a reboot
adb devices
```

Nothing to set up on Windows, and it works until the phone changes networks. On Xiaomi phones the Wireless debugging toggle sometimes turns itself off after a reboot; turn it back on.

## B: the Windows emulator, or USB through Windows

The emulator binds to Windows localhost, so the adb client in WSL has to talk to the Windows adb server. On Windows, once per boot (allow it through the firewall when asked):

```powershell
adb kill-server; adb -a -P 5037 start-server
```

In WSL:

```bash
export ADB_SERVER_SOCKET=tcp:$(ip route show default | awk '{print $3}'):5037
adb devices   # emulator-5554 shows up
```

Keep the Windows and WSL adb versions close, or the client restarts the server and the link drops. With [`networkingMode=mirrored`](https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking) in `.wslconfig`, `localhost` is shared and the socket is `tcp:127.0.0.1:5037`.

## C: USB passthrough

`usbipd bind` and `usbipd attach --wsl` from [usbipd-win](https://github.com/dorssel/usbipd-win). More setup than A for the same result.

## The skill

Save it as `.claude/skills/device-testing/SKILL.md`. The original test matrix was all about alarms surviving Doze, reboots and the rest; this version keeps the matrix's shape and the two rows that apply to any app.

````markdown
---
name: device-testing
description: WSL2 to Android device and emulator connection, the install loop, and the app's device test matrix with adb procedures. Use when connecting a device, installing builds, running instrumented tests, or simulating Doze, reboot or other device states.
---

# Device testing from WSL2

Claude Code and Gradle run in WSL2. The repo lives on WSL ext4 (`~/...`), never `/mnt/c`:
Gradle is several times slower there.

## One-time setup in WSL

```bash
sudo apt-get install -y openjdk-17-jdk unzip
# Android SDK, headless: put cmdline-tools under ~/android-sdk, then
export ANDROID_HOME=$HOME/android-sdk   # add to your shell rc, plus platform-tools on PATH
sdkmanager "platform-tools" "platforms;android-35" "build-tools;35.0.0"
```

## Connecting, best option first

**A. Physical device over Wi-Fi.** Android 11+: Developer options → Wireless debugging →
Pair device with pairing code.

```bash
adb pair 192.168.1.x:PAIR_PORT
adb connect 192.168.1.x:CONN_PORT   # per session; the port changes across reboots
adb devices
```

**B. Windows-hosted emulator.** WSL must use the Windows adb server:

```powershell
adb kill-server; adb -a -P 5037 start-server   # on Windows, once per boot
```

```bash
export ADB_SERVER_SOCKET=tcp:$(ip route show default | awk '{print $3}'):5037
adb devices
```

Keep Windows and WSL adb versions close. With `networkingMode=mirrored`, use `tcp:127.0.0.1:5037`.

**C. USB passthrough (usbipd-win)**: only if Wi-Fi is unusable.

## Install loop

```bash
./gradlew assembleDebug && adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n <pkg>/.MainActivity
adb logcat --pid=$(adb shell pidof -s <pkg>)   # only this app's process
```

## Test matrix

One row per condition the app must survive. For each: set up the scenario, run the
procedure, check the result on the device and in the logs, then restore the device.

| Scenario | Procedure | Restore |
|---|---|---|
| Doze | screen off, then `adb shell dumpsys battery unplug` and `adb shell dumpsys deviceidle force-idle` | `adb shell dumpsys deviceidle unforce`, `adb shell dumpsys battery reset` |
| Reboot with work pending | `adb reboot`, don't reopen the app | none |
| <your scenario> | <exact command> | <exact command> |

The closest adb stand-in for the user swiping the app away is `adb shell am kill <pkg>`.
`adb shell am force-stop <pkg>` also cancels the app's alarms by OS design: useful to
demonstrate, but not a pass/fail scenario.

## Instrumented tests

`./gradlew connectedDebugAndroidTest` runs on whatever `adb devices` shows. Keep the core
logic unit-testable (inject the clock and system services); the matrix is for what no JVM
test can reach.
````

see also: [Kotlin For React Devs Skill](/articles/kotlin-for-react-devs-skill)
