.agents/skills/driver-ui-tests/SKILL.md
Guidelines for writing UI tests using IDE Starter and UI Driver frameworks.
// Driver core
import com.intellij.driver.client.Driver
import com.intellij.driver.sdk.waitForProjectOpen
import com.intellij.driver.sdk.advancedSettings
// Test utilities
import com.intellij.driver.tests.utils.waitForIndicators
import com.intellij.driver.tests.utils.Plugin
import com.intellij.driver.tests.utils.PluginInstaller
import com.intellij.driver.tests.utils.Plugins
// IDE Starter framework
import com.intellij.ide.starter.driver.runIdeTest
import com.intellij.ide.starter.ide.IDETestContext
import com.intellij.ide.starter.models.IDEStartResult
import com.intellij.ide.starter.models.VMOptions
import com.intellij.ide.starter.runner.IDERunContext
import com.intellij.ide.starter.runner.Starter
import com.intellij.ide.starter.utils.catchAll
// Extended test infrastructure
import com.intellij.ide.starter.extended.allure.AllureHelperExtended.step
import com.intellij.ide.starter.extended.allure.Subsystems
import com.intellij.ide.starter.extended.engine.newTestContainerExtended
import com.intellij.ide.starter.extended.engine.TestContainerExtended
import com.intellij.ide.starter.extended.license.StagingLicenseGenerator.licenseProductCode
import com.intellij.ide.starter.extended.loadMetadataFromServer
import com.intellij.ide.starter.extended.setupTestMetadataSchemeWithGroupsFromCode
// Test framework
import com.intellij.testFramework.TestApplicationManager
community/platform/remote-driver)com.intellij.ide.starter.models.TestCase see src/com/intellij/ide/starter/projectcommunity/tools/intellij.tools.ide.starter/src/com/intellij/ide/starter/ide/IdeProductProvider.kt)See tests/intellij.ide.starter.extended/src/com/intellij/ide/starter/extended/data/cases
Page objects extend UiComponent with ComponentData constructor:
class MyPageObject(data: ComponentData) : UiComponent(data) {
val myButton = x { byAccessibleName("Button Name") }
val myPanel = x { byClass("PanelClassName") }
fun clickMyButton() {
myButton.click()
}
}
// Extension function on Finder to create the page object
fun Finder.myPageObject(): MyPageObject = x(
xQuery { byAccessibleName("Root Element Name") }, MyPageObject::class.java
)
// Use specific ui component to specify the context of the search
fun AnotherPageObject.myPageObject(): MyPageObject = x(
xQuery { byAccessibleName("Root Element Name") }, MyPageObject::class.java
)
| Selector | Usage |
|---|---|
byAccessibleName("name") | Find by accessible name attribute |
byClass("ClassName") | Find by Swing/AWT class name |
byVisibleText("text") | Find by visible text content |
See directory tests/remote-driver-tests
See directory community/platform/remote-driver/test-sdk/src/com/intellij/driver/sdk/ui
When multiple elements match a selector, scope to a parent element:
// BAD - will fail if multiple InstallButtons exist
ui.x { byClass("InstallButton") }.click()
// GOOD - scope to a parent element first
val detailPane = ui.x { byClass("PluginDetailsPageComponent") }
detailPane.x { byClass("InstallButton") }.click()
element.keyboard { typeText("search text") }
ui.keyboard { key(KeyEvent.VK_ENTER) }
ui.keyboard { hotKey(KeyEvent.VK_META, KeyEvent.VK_COMMA) } // Cmd+,
Every UI test must have the following annotations at the class level:
| Annotation | Purpose | TestOps Custom Field |
|---|---|---|
@Subsystems.* | Categorizes the test by subsystem | Subsystem |
@Features.* | Specifies the feature being tested | Feature |
@Components.* | Identifies the component under test | Component |
For tests linked to TestOps test cases, also add:
@AllureId("test_case_id") - Links the test to the TestOps test case IDThe annotation values should match the corresponding TestOps custom fields (Subsystem, Feature, Component).
Available annotations: See tests/intellij.ide.starter.extended.allure/src/com/intellij/ide/starter/extended/allure/Annotations.kt
Example with TestOps test case:
@Subsystems.Java
@Features.Completion
@Components.Editor
class MyTestFromTestOps {
@Test
@AllureId("318541") // Required when test case exists in TestOps
fun `my test from testops`(testInfo: TestInfo) {
// ...
}
}
Example for new test (not yet in TestOps):
@Subsystems.UI
@Features.PluginManager
@Components.Miscellaneous
class MyNewTest {
@Test
fun `my new test`(testInfo: TestInfo) {
// ...
}
}
@Subsystems.Java
@Features.Completion
@Components.Editor
class MyTest {
val testCase = TestCase(IdeProductProvider.IU, myProject)
@Test
@AllureId("123456") // Required if test case exists in TestOps
fun `my test name`(testInfo: TestInfo) {
val context = Starter.newContext(testName = "TestName", testCase = testCase)
context.applyVMOptionsPatch {
addSystemProperty("ide.ui.non.modal.settings.window", "true")
}
context.runIdeTest(testName = testInfo.displayName) {
waitForIndicators(5.minutes) // Wait for indexing to complete
step("Step description") {
// Test actions here
}
}
}
}
Always wait for indicators at the start of your test:
waitForIndicators()
This ensures the project is fully imported and indexed before interacting with the IDE.
Use openFile instead of UI-based file navigation:
// GOOD - Direct and reliable
openFile(relativePath = "src/Main.java")
// AVOID - UI-based approach is slower and more fragile
invokeAction("GotoFile", now = false)
ui.keyboard { typeText("Main.java") }
ui.keyboard { key(KeyEvent.VK_ENTER) }
now ParameterThe now parameter controls whether the action completes before continuing:
// now = true: Waits for action to complete (use when keyboard input follows)
invokeAction("ToggleBookmarkWithMnemonic", now = true)
ui.keyboard { key(KeyEvent.VK_1) } // This input goes to the bookmark dialog
// now = false: Returns immediately (use when waiting for UI to appear)
invokeAction("ShowSettings", now = false)
ui.x { byClass("SettingsDialog") }.shouldBe { present() }
Rule: Use now = true when the next step is keyboard input to prevent input going to the wrong component.
Rule: Use now = false when you expect to the UI dialog to appear.
Use waitFor to wait for specific conditions:
waitFor("description of what we're waiting for", 30.seconds) {
ui.x { byClass("MyComponent") }.present()
}
waitFor("text to appear", 10.seconds) {
ui.x { byClass("Tree") }.hasText("expected text")
}
Driver tests require a fully built IDE. There are several ways to run them:
The tests.cmd script builds the IDE from sources and runs tests. Recommended for dev server mode.
Example:
./tests.cmd \
-Dintellij.build.test.patterns=com.intellij.driver.tests.idea.java.FindAndGoToTest \
-Dintellij.build.test.main.module=intellij.driver.tests
Key parameters:
-Dintellij.build.test.patterns - fully qualified test class name (or pattern)-Dintellij.build.test.main.module=intellij.driver.tests - required for driver testsExample with specific test:
./tests.cmd \
-Dintellij.build.test.patterns=com.intellij.driver.tests.idea.ultimate.httpclient.BuiltInHttpClientBrotliCompressionUiTest \
-Dintellij.build.test.main.module=intellij.driver.tests
After test failure, check:
out/ide-tests/tests/{IDE-version}/{TestName}/{test-method}/log/ui-hierarchy/ui.htmlout/ide-tests/tests/{IDE-version}/{TestName}/{test-method}/log/idea.logout/ide-tests/tests/{IDE-version}/{TestName}/{test-method}/log/screenshots/out/ide-tests/tests/{IDE-version}/{TestName}/{test-method}/error/Thread.sleep() or delay() - Driver framework automatically waits for UI elementsstep("description") { } for better logs