Locators - TestlumFramework/Testlum GitHub Wiki

Locators

Before describing the Web related commands, it is necessary to know how to create a locator and connect it to a scenario.

Available types of locators in Testlum

  • id
  • class
  • xpath
  • cssSelector
  • text

Testlum supports using locators by two different ways

  • By using locator attribute in needed web command from special separate files in special folders with names that can be used in different scenarios without duplicating the entire locator.
  • Directly in the field for the locator - the locator is entered in the field in its entirety each time.
Locators from files

To create locators for the locator field you need:

Create a file in the locators folder with the name of the page or component (e.g: loginPage.xml)

  • component folder - contains files from page components that do not change according to the page (it can be a footer, a header). Also, for use, these locators must be included in the pages file required for use
  • pages folder - contains files of different pages that change according to the link.

📁 Example folder structure:

locators/
├── component/
│   └── header.xml
├── pages/
│   └── loginPage.xml

component locator file structure

<component>

    <locators>
        <locator locatorId="searchField">
            <xpath>.//input[@type='text']</xpath>
        </locator>
    </locators>

</component>

pages locator file structure

<page>

   <details>
       <name>Sign In</name>
       <url>http://localhost:3000/</url>
       <description>Sign In for regression tests</description>
   </details>

   <include component="header.xml"/>

   <locators>
       <locator locatorId="email">
           <xpath>.//input[@type="email"]</xpath>
           <id>email</id>
           <className>emailClass</className>
           <cssSelector>.emailClass</cssSelector>
           <text>Input Your Email</text>
       </locator>
   </locators>

</page>

📝 details

Element Type Required Default Description
name String true - Name of the test or scenario (e.g., "Sign In")
url String true - URL where the scenario starts
description String false - Description of the test's purpose

🧩 Optional include

After including component to locator's page you can access included locator by:

locator="pageFileName.locatorIdFromComponentFile"

<click comment = "Click on 'email' button" locator="loginPage.searchField"/>
Attribute Type Required Default Description
component String true - Path to the component XML file to be included (e.g., reusable blocks like headers or footers)

📌 locators and locator

Attribute / Element Type Required Default Description
locatorId (attribute) String true - Unique identifier to reference the locator
xpath String false - XPath expression used to find the element in the DOM
id String false - HTML id attribute of the element
className String false - HTML class name used to locate the element
cssSelector String false - CSS selector to identify the element
text String false - Text inside the element for matching or validation

Now you can use your locator loginPage.email for any command you need, and for any test.

<click comment = "Click on 'email' button" locator="loginPage.email"/>
Direct usage of locators in the command field
  1. Use the locatorStrategy attribute in each command that you need to specify locator type (xpath id className cssSelector text)
  2. Write locator in the locator field.
<click comment = "Click on 'email' button" locator="//input[@type='email']" locatorStrategy="xpath"/>
⚠️ **GitHub.com Fallback** ⚠️