compose-ui-test-server

A library that enables coding agents and automation tools to control Compose Desktop applications at runtime via HTTP. Agents can click buttons, enter text, wait for UI elements, and capture screenshots through simple REST API calls.

Use Case

This library is designed for AI coding agents (like Claude Code) to interact with running Compose Desktop applications. When enabled, the app exposes an HTTP server that agents can use to:

• Navigate through the UI by clicking buttons and entering text
• Wait for specific UI elements to appear
• Capture screenshots to verify the current state
• Perform automated workflows and testing scenarios

Features

• HTTP-based control of running Compose Desktop apps
• Zero-configuration launcher with automatic mode switching
• Conditional startup via environment variable (disabled by default)
• Built-in endpoints for common UI operations
• Extensible with custom endpoints for app-specific shortcuts
• Screenshot capture for visual verification

Installation

Add the dependency to your desktop source set in build.gradle.kts:

kotlin {
    sourceSets {
        @OptIn(org.jetbrains.compose.ExperimentalComposeLibrary::class)
        val desktopMain by getting {
            dependencies {
                implementation("io.github.forketyfork:compose-ui-test-server:0.2.0")

                // Required: Compose UI Test framework
                implementation(compose.uiTest)
            }
        }
    }
}

Quick Start

1. Use the Application Launcher

Replace your main() function with runApplication:

import io.github.forketyfork.composeuittest.WindowConfig
import io.github.forketyfork.composeuittest.runApplication

fun main() =
    runApplication(
        windowConfig = WindowConfig(
            title = "My App",
            minimumWidth = 1024,
            minimumHeight = 768,
        ),
    ) {
        App()
    }

That's it! Your app now supports agent control with zero additional configuration.

2. Add Test Tags to UI Elements

For agents to interact with UI elements, add test tags:

import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.testTag

Button(
    onClick = { /* ... */ },
    modifier = Modifier.testTag("login_button")
) {
    Text("Login")
}

TextField(
    value = username,
    onValueChange = { username = it },
    modifier = Modifier.testTag("username_field")
)

3. Run Your App

Normal mode (default):

./gradlew run

Agent-controlled mode:

COMPOSE_UI_TEST_SERVER_ENABLED=true ./gradlew run

When the environment variable is set, your app automatically starts with an HTTP server that agents can use to control the UI.

4. Control via HTTP

Once running in agent-controlled mode:

# Health check
curl http://localhost:54345/health

# Click a button by test tag
curl http://localhost:54345/onNodeWithTag/submit_button/performClick

# Enter text into a field
curl "http://localhost:54345/onNodeWithTag/username_field/performTextInput?text=myuser"

# Wait for an element to appear
curl "http://localhost:54345/waitUntilExactlyOneExists/tag/welcome_screen?timeout=5000"

# Capture a screenshot
curl "http://localhost:54345/captureScreenshot?path=/tmp/current_state.png"

Available Endpoints

Environment Variables

Advanced Configuration

Server Configuration

For more control over the test server, pass a server configuration:

import io.github.forketyfork.composeuittest.ComposeUiTestServerConfig
import io.github.forketyfork.composeuittest.WindowConfig
import io.github.forketyfork.composeuittest.runApplication

fun main() =
    runApplication(
        windowConfig = WindowConfig(title = "My App"),
        serverConfig = ComposeUiTestServerConfig(
            port = 8080,
            host = "0.0.0.0",
            defaultScreenshotPath = "/tmp/app_screenshot.png",
            defaultTimeout = 10_000L,
        ),
    ) {
        App()
    }

Custom Endpoints

Add app-specific shortcuts for common agent workflows:

import io.github.forketyfork.composeuittest.TestEndpoint
import androidx.compose.ui.test.ComposeUiTest
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performTextInput
import androidx.compose.ui.test.performClick
import io.ktor.server.routing.Route
import io.ktor.server.routing.get
import io.ktor.server.response.respondText

class LoginEndpoint(
    private val username: String,
    private val password: String
) : TestEndpoint {
    override fun Route.configure(composeTest: ComposeUiTest) {
        get("/shortcuts/login") {
            composeTest.onNodeWithTag("username").performTextInput(username)
            composeTest.onNodeWithTag("password").performTextInput(password)
            composeTest.onNodeWithTag("login_button").performClick()
            call.respondText("Login completed")
        }
    }
}

To use custom endpoints, use the lower-level API:

import androidx.compose.ui.test.runComposeUiTest
import androidx.compose.ui.window.Window
import androidx.compose.ui.window.application
import io.github.forketyfork.composeuittest.ComposeUiTestServer
import io.github.forketyfork.composeuittest.isTestServerEnabled

fun main() {
    if (isTestServerEnabled()) {
        runComposeUiTest {
            setContent { App() }
            ComposeUiTestServer(this)
                .registerEndpoint(LoginEndpoint("[email protected]", "password"))
                .start()
                .awaitTermination()
        }
    } else {
        application {
            Window(onCloseRequest = ::exitApplication, title = "My App") {
                App()
            }
        }
    }
}

Platform Support

Currently supports Desktop (JVM) only due to Skia dependencies for screenshot capture.

Claude Code Skill Installation

This library includes a skill that teaches Claude Code how to control Compose Desktop apps and set up new projects. Install it to enable automatic UI control capabilities.

Personal Installation (all your projects)

mkdir -p ~/.claude/skills/compose-ui-control
curl -o ~/.claude/skills/compose-ui-control/SKILL.md \
  https://raw.githubusercontent.com/forketyfork/compose-ui-test-server/main/SKILL.md

Project Installation (this project only)

mkdir -p .claude/skills/compose-ui-control
curl -o .claude/skills/compose-ui-control/SKILL.md \
  https://raw.githubusercontent.com/forketyfork/compose-ui-test-server/main/SKILL.md

Using the Skill

Once installed, Claude Code can:

• Automatically use the skill when you ask it to interact with UI, click buttons, or test the app
• Manually invoke it with /compose-ui-control
• Set up new projects with agent control capabilities

Example prompts that trigger the skill:

• "Click the login button in the app"
• "Enter my username and password"
• "Take a screenshot of the current state"
• "Wait for the dashboard to appear"
• "Add agent control to this Compose Desktop project"

Skill Reference

See SKILL.md for the full skill documentation that Claude Code uses.

License

MIT License - see LICENSE for details.