Testing

Wearing the glasses for every change is slow. The VDK has three tools so you mostly do not have to:

• The visor command, on your computer: talk to Visor on the phone, watch what your app does, and stand in for the band or the glasses.
• FakeVisor, in your tests: Visor inside your app's process, driven by your test code.
• visor fake, on your computer: FakeVisor behind the same doors Visor opens on a phone, for scripts, web pages, MCP clients and the visor command, with no phone at all.

The visor command

Install

The command needs Java 17 or later, and adb to reach a phone. Android Studio brings both.

The fast way, one line that installs the latest release and puts visor on your PATH. Run it again to update.

curl -fsSL https://visor.macedonga.com/install.sh | sh          # macOS and Linux
irm https://visor.macedonga.com/install.ps1 | iex               # Windows, in PowerShell

The script on macOS and Linux puts the command in ~/.visor and starts it from ~/.local/bin/visor; the one on Windows puts it in %LOCALAPPDATA%isor and adds its bin folder to your PATH. Both say so if Java is missing.

The manual way:

1. Download visor-<version>.zip from the releases.
2. Unzip it where you keep tools.
3. Put its bin folder on your PATH.

From a clone of visor-kit, ./gradlew :cli:installDist builds it in tools/cli/build/install/visor.

visor --version says which version you have.

Set up the phone

1. Connect the phone with adb, over USB or wireless debugging: adb devices must list it. With more than one device, pick one with visor -s SERIAL ....
2. In Visor, turn on Developer mode, in Settings, Advanced settings, Tools. It opens the socket the command uses; apps do not need it.

visor finds adb through ANDROID_HOME or the PATH, forwards a free port to Visor's socket, and removes the forward when it ends. Only adb can reach the socket: Visor checks that each connection comes from adb's shell user.

Commands

Add --json for JSON only, one value per line, to pipe into jq or a script.

Watch the camera

visor live films with the glasses until Ctrl+C. Write to a file, or to standard output for a player:

visor live - | ffplay -fflags nobuffer -
visor live walk.hevc '{"quality":"full_hd","frameRate":30,"audio":true}'
ffmpeg -i walk.hevc -i walk.hevc.aac -c copy walk.mp4

In PowerShell 5, pipe through cmd /c or save to a file: PowerShell's pipe changes binary data.

See what your app does

Run visor trace in one terminal and use your app:

$ visor trace
Tracing the VDK. Ctrl+C stops.
16:02:11.204  com.example.app  call        kit.hello #1  {"protocol":1,"kit":"0.1.0"}
16:02:11.209  com.example.app  result      kit.hello #1 4 ms  {"protocol":1,"visor":"2.4.0",...}
16:02:11.240  com.example.app  subscribe   band.gestures #2
16:02:13.811  com.example.app  event       band.gestures #2  {"finger":"index","action":"tap","derived":"double_tap",...}
16:02:15.002  com.example.app  call        camera.photo #3  {"import":true}
16:02:18.517  com.example.app  result      camera.photo #3 3515 ms  {"id":"...","type":"photo","uri":"content://..."}

Stand in for the band or the glasses

simulate takes the real source out of the topics you name: apps subscribed to them get only what you type, and the band is not borrowed. It ends when you press Ctrl+C or close the input, and then the real source comes back without your app noticing.

$ visor simulate band.gestures
Simulating ["band.gestures"]: apps get only what you type here. Ctrl+C or end of input stops.
index double_tap
middle hold
thumb up

For band.gestures, a line is FINGER ACTION, or FINGER ACTION DERIVED when the band's reading should differ from the action. For glasses.inputs, a line is SOURCE ACTION, such as touchpad swipe_forward. For any other topic, a line is the event's JSON:

$ visor simulate glasses.status
{"paired":true,"link":"connected","battery":4,"worn":true}
{"paired":true,"link":"disconnected"}

With several topics, start each line with its topic. visor inject sends a single event, simulated or not, to the apps subscribed now:

visor inject band.gestures index tap
visor inject glasses.status '{"paired":true,"link":"connected","battery":15}'

Visor checks every event against the topic's type before it sends it, so a typo fails here, not in your app. Made-up events go to apps only: the glasses, the band and Visor's own screens never see them.

Script the glasses

call runs any method, which makes the command a quick way to script the glasses:

visor call camera.photo '{"import":false}'
visor call band.buzz '{"durationMs":120,"strength":128}'
visor call display.prompter.show '{"text":"Two minutes left"}'
visor --json watch band.gestures | jq -r .event.derived

Record once, replay anywhere

record saves what the wearer does, with the state it happens in, so you can play it back while you work on your app, on the phone or on visor fake:

visor record walk.jsonl                     # glasses.status, glasses.inputs, band.status, band.gestures
visor record taps.jsonl band.gestures       # only these topics
visor replay walk.jsonl                     # into the apps on the phone
visor --fake replay walk.jsonl --loop       # into visor fake, over and over

In a JVM test, FakeVisor.replay plays a recording into your app the same way, paced or all at once:

fake.replay(File("src/test/resources/walk.jsonl").reader())          // at its recorded pace
fake.replay(File("src/test/resources/taps.jsonl").reader(), paced = false)

Each line is one event, {"t": 1520, "topic": "band.gestures", "event": {...}}, with t in milliseconds from the start of the recording. While a replay runs, its topics are simulated: apps get the recorded events, at their recorded times, and nothing from the real glasses or band. The events keep the times they were recorded with. A recording is plain JSON, so a test can read it too, or you can write one by hand.

FakeVisor

FakeVisor (com.macedonga.visor:kit-testing) is Visor in your process. It answers every method from state your test sets, so tests run without a phone, glasses or band. It runs the same server code as Visor, so scopes, streams and errors behave the same way.

import com.macedonga.visor.kit.testing.FakeVisor
import com.macedonga.visor.kit.testing.connect

@Test
fun warnsOnLowBattery() = runBlocking {
    val fake = FakeVisor()
    val visor = fake.connect()

    fake.glasses.battery = 4
    val screen = BatteryWarning(visor)
    screen.refresh()

    assertEquals("Charge the glasses", fake.display.prompter.value)
    assertEquals(listOf("kit.hello", "display.prompter.show"), fake.calls)
    fake.close()
}

It runs as a plain JVM unit test: no emulator, no Robolectric. Calls answer from the fake's state at once, and streams of state send it first, so a test needs no waiting. Events you send while nothing collects are dropped, as with the real band: start collecting before you call fake.band.gesture(...).

What the fake offers:

In an app with kit-testing, the fake's imported captures and live photos open with the app's ContentResolver, as Visor's do: their content:// URIs point at a provider that kit-testing adds to the app. Without bytes given, each holds a 1x1 PNG. In a plain JVM test the URIs open nothing.

The fake films nothing: your test sends each live sample. Wait until the app watches, or the sample is lost:

fake.live.watching.first { it }
fake.live.sendVideoConfig(parameterSets)
fake.live.sendVideo(keyframe, ptsUs = 0, key = true)

FakeVisor itself is plain Kotlin, in com.macedonga.visor:kit-fake: a JVM test or tool can drive it without Android. kit-testing adds connect(), which needs the Android library.

Recorded feeds

DAT's mock plays a video file as the camera and a CSV as the motion sensors; FakeVisor does both:

launch { File("walk.csv").reader().use { fake.glasses.playMotion(it, loop = true) } }
launch { File("street.h265").inputStream().use { fake.live.play(it, "video/hevc", 504, 896, 24, loop = true) } }

The CSV is DAT's: no header, 14 numbers a row, the time in nanoseconds, the accelerometer, gyroscope and magnetometer as x, y, z, and the orientation as w, x, y, z. The camera takes an Annex-B H.264 or H.265 stream; ffmpeg makes one from any clip without re-encoding: ffmpeg -i clip.mp4 -c:v copy -bsf:v hevc_mp4toannexb street.h265 (h264_mp4toannexb for H.264). It starts once an app watches the live camera.

Without a phone: visor fake

visor fake runs FakeVisor on your computer, behind the doors Visor opens on a phone:

• JSON-RPC over WebSocket on ws://127.0.0.1:7333/rpc, as Visor's network door, with no token;
• MCP on http://127.0.0.1:7333/mcp, for an assistant on your computer;
• the visor command, with --fake in place of -s SERIAL;
• the Display simulator on http://127.0.0.1:7333/display.

Every scope is granted. Its console plays the glasses, and prints what apps do to them:

$ visor fake
FakeVisor on ws://127.0.0.1:7333/rpc and http://127.0.0.1:7333/mcp; visor --fake on port 7334. Type help.
The Display simulator: http://127.0.0.1:7333/display
00:23:47  Display: the prompter shows "Hello from the fake"
00:23:47  Band: a buzz of 400 ms
gesture index double_tap
battery 12
ask what is on the calendar today
00:24:02  Voice: the glasses say "Two meetings, the first at ten."

From another terminal, the command works on the fake as on a phone: visor --fake trace, visor --fake watch band.gestures, visor --fake call display.prompter.show '{"text":"Hi"}'. The Python client has visor_kit.connect_fake() and the TypeScript one Visor.connectFake(). --port N moves the doors to N and the command's port to N + 1; --lan opens the doors to the local network.

The Display simulator

Open http://127.0.0.1:7333/display while visor fake runs. It draws the layout an app shows on the fake Display at 600 by 600, by the same rules Visor uses to send it to the glasses, and it plays the wearer:

• the arrow keys move the focus as the touchpad and the band do, Enter selects, Backspace or Esc goes back; a click on an element selects it too. The app gets the clicks and the back as from the glasses, and each move on glasses.inputs as nav_*, select and back from the touchpad;
• the Display adds light, so its black is clear: the page draws it over a background (black, a room, a street in daylight, a night street, or your webcam) with a brightness slider;
• a checkbox makes it dim and sleep after 20 and 25 seconds, as the Display does;
• a video plays, and its pauses, end and failures reach the app on display.video;
• Screenshot and Record save the display as a PNG or a WebM (Chrome crops them to the display);
• Screen switches to the Briefing: the app's cards in the panel's material, one under another. Enter or a click opens a card's detail, its pages swipe with the arrows, its buttons click as on the glasses (the app gets them on display.cards.clicks, and an element's toast shows), and Backspace closes it.

DAT's icons are drawn with the nearest Material Symbol; the Briefing glyphs and the weather illustrations come from Meta's own icon CDN, as the Display fetches them. Check a layout on the glasses before you ship it.

visor --fake card card.json puts a card on the fake Briefing from a file, as visor card does on a phone, and visor --fake call METHOD @params.json takes any method's params from a file. With visor fake --port 7400, give the same port to the command: visor --fake=7400 status.

In the app itself, fake.display.preview(context) from kit-testing is a view with the same renderer: it draws what the fake Display shows and clicks what you tap, as DAT's createPreviewView() does. fake.display.briefingPreview(context) draws the Briefing with the app's cards: a tap opens a card's detail, a tap there clicks, and a double tap goes back.

Web apps on the Display

Visor.connectGlasses() works only in the Display's browser. Elsewhere, connect the same page to visor fake with Visor.connectFake(), and pick with onGlasses(): see Web apps on the Display.

The samples

• samples/android is an app with a button for every capability. Build it with ./gradlew :sample:installDebug, and use it with visor trace to see a whole exchange.
• samples/python holds small scripts on the Python client: a teleprompter pager turned by the band, a journal of the assistant's answers, and the glasses' settings.
• samples/web is a glasses console in one page, on the network door, with no build step.