Type into a TextField

To simulate typing text into a text field in your tests, use the TypingText() method from the PanelSimulator class. This method sends the appropriate keyboard events to the target element, mimicking a real user interaction. Focus the text field before calling this method.

Example

The following example shows how to simulate typing text into a text field:

[Test]
public void TypingTextExample()
{
    // Make sure the UI is totally up to date.
    simulate.FrameUpdate();

    // Fetch and focus the textField's textElement.
    var textField = rootVisualElement.Q<TextField>("MyTextField");
    var textElement = textField.Q<TextElement>();
    Assume.That(textField, Is.Not.Null);
    textField.Focus();

    Assume.That(textField.text, Is.Empty);
    Assume.That(textField.hasFocusPseudoState, Is.True);

    // Type into the textField.
    var typedText = "Typed text.";
    simulate.TypingText(typedText);
    simulate.FrameUpdate();

    Assert.That(textField.text, Is.EqualTo(typedText));
}

Platform differences at runtime

When running tests in Play mode or in a runtime assembly, the behavior of the TypingText() method can vary based on the platform due to its different requirements and behaviors at runtime.

The following table summarizes the differences:

Platform Events sent Requirements
Windows, Mac, Linux, WebGL UI Toolkit events You must focus on the TextElement.
XboxOne, PS5, PS4, Android, iPhone, tvOS Directly on TouchScreenKeyboard You must focus on the TextElement to summon the TouchScreenKeyboard.
Nintendo Switch Unsupported N/A

Usage when a TouchScreenKeyboard is present

You can use the test fixtures to execute UI interactions synchronously and force the UI Toolkit loop to run.

However, for platforms that pop a TouchScreenKeyboard, such as an iPhone, tests must wait in real time before calling TypingText. Because the TouchScreenKeyboard functionality is not controlled by UI Toolkit, tests must wait until the keyboard is visible and ready before trying to type.

The following example shows how to simulate typing text into a text field when a TouchScreenKeyboard is involved:

[UnityTest]
[UnityPlatform(include = new[] { RuntimePlatform.IPhonePlayer, RuntimePlatform.Android })]
public IEnumerator TypingText_TouchScreenKeyboard_Example()
{
    // Make sure the UI is totally up to date.
    simulate.FrameUpdate();

    // Fetch and focus the textField's textElement.
    var textField = rootVisualElement.Q<TextField>("MyTextField");
    var textElement = textField.Q<TextElement>();
    Assume.That(textField, Is.Not.Null);
    textField.Focus();

    Assume.That(textField.text, Is.Empty);
    Assume.That(textField.hasFocusPseudoState, Is.True);

    // Wait real time for the
    // TouchScreenKeyboard to pop on the device.
    float timeout = Time.realtimeSinceStartup + 1f;
    while (!TouchScreenKeyboard.visible)
    {
        if (Time.realtimeSinceStartup > timeout)
        {
            throw new TimeoutException("TouchScreenKeyboard did not pop within the timeout period.");
        }
        yield return null;
    }
    
    // Type into the textField.
    var typedText = "Typed text.";
    simulate.TypingText(typedText);
    simulate.FrameUpdate();

    Assert.That(textField.text, Is.EqualTo(typedText));
}

Additional resources