Generally, Anton, the TestFirst AI Assistant, can help you write test cases for testing web applications. In this article, you will find general information on the Gherkin language, selector types (AI Selectors, Quick Selectors, Custom Selectors) and the usage of the data repository items in your test cases. 

You can automate test cases in TF Automate by simply writing them in the text pane using Gherkin specification that can be found here. The Gherkin spec contains all the currently implemented sentences with their descriptions and examples. 

Gherkin General Information

Gherkin is a human-readable syntax that describes the behavior of the software with a set of scenarios. 

Gherkin can support multiple languages. You can check the list of supported languages here. You can switch the language using the dropdown in the test case title line. 

Gherkin keywords

There are several keywords used in the TestFirst Automate Gherkin implementation: 

• Scenario - a keyword indicating the start of a test case step. A scenario must contain an action and an expected result, and can contain a precondition.
• Given - a keyword indicating the precondition of a test step or the test case as a whole. 
• When - a keyword indicating the action to be taken to achieve the expected result. 
• Then - a keyword indicating the expected result of a test step.
• And - a connecting keyword, used within the precondition, action, and expected result when there is more than one precondition, action to be taken and/or more than one expected result to be achieved.

Example: 

Scenario: Navigate to TestFirst website
    Given browser "Chrome"
    When I visit "https://www.testfirst.com/"
    And I click "Features"
    Then "START NOW" is displayed
    And "Features That Make You Go Fast" is displayed

In the example:

1. The scenario has the title "Navigate to TestFirst website". It can be any plain text, as the title is only there to help you understand what is done in the test step.
2. The precondition indicated by the Given keyword, states that the test case should be executed in browser Chrome. 
3. The action indicated by the When keyword, states that to achieve the expected result, we need to visit the specified URL and click a specific element on the page. The action part of the scenario contains 2 sentences. One starts with the When keyword, the other continues with the And keyword.
4. The expected result indicated by the Then keyword, checks for the presence of specific elements on the page. The And keyword allows for multiple elements to be checked.

Autocompletion of the Sentences

When you start writing a sentence in TF Automate, the auto-completer will suggest all the possible options for continuing the sentence, sorted by relevance. Thus, if you are writing a test case for a web application, and have a Given browser "<Browser" sentence in the beginning of the test case, the auto-completer will first suggest the sentences relevant to the web application testing. 

When you click on the sentence in the auto-completer list, it will insert the next portion of the sentence, till the next optional part of the sentence or the next argument. 

Selectors

In TestFirst Automate, selectors can be described in one of 3 ways.

1. AI Selectors

2. Quick Selectors

3. Custom Selectors

1. AI Selectors

AI Selectors are smart, auto-generated element locators powered by machine learning. They’re designed to find UI elements without requiring technical selectors (like XPaths or CSS), making them ideal for non-technical users or complex UIs such as enterprise dashboards with dynamic tables and nested elements.

AI Selectors remove the need for fragile, complex locators by intelligently identifying elements based on human-like descriptions provided in selectors. 

For example:

When I click "'Login' button"

In this example, during automated run, TestFirst analyzes the page and tries to find the best matching elements for a given description (in this example, the Login button). 

AI Selectors also understands intent—whether it’s finding a button ‘next to’ something or using plain language in your native tongue to describe an action.

For example:

When I click "'Sign up' button near to Login"

In this example, TestFirst would look for a Sign up button only near to Login. If there are other Sign up buttons or links etc., those would be ignored by TestFirst.

ℹ️ AI Selectors require Cloud Credits to function. If you don't want to use AI selectors, you still have the option of using Quick Selectors or Custom Selectors.

Tips for Writing Good AI Selectors

These are some of the ways you can increase the success of AI Selectors.

1. When locating an input field, consider appending “input field” phrase and wrapping the field name with single quote, for example:
   1. ‘Username’ input field
   2. ‘Password’ input field
2. Same applies to other element types, for example:
   1. ‘Submit’ button
   2. ‘Add Payroll Item’ button
   3. ‘Shutdown’ icon
   4. ‘Add Item’ dropdown
3. When using another element to locate a related element, you can use the following relations:
   1. 'Amount' input field near to 'Bonus'
   2. 'Amount' input field near to the last 'Bonus'
4. When locating an element that is in a list (flat list, a dropdown, or other list), you can specify neighbour elements if the element you’re looking for appears in multiple places. For example, let’s assume there's a “Bonus” item in the form, and also there's a “Bonus” item in an item selection dropdown, and you want to select a value from the dropdown. In many cases you can simply say “‘Bonus’ item in dropdown”, but depending on how the website is internally implemented, this may not work as expected. In that case you can add neighbour items in the selector. Assuming that the dropdown also contains “Allowance” and “Commission” items along with “Bonus”, you can make the following selector:
   1. 'Bonus' item in dropdown select near to 'Allowance' and 'Commission'
5. When verifying a text or a number you can explicitly say to exclude the title element, for example:
   1. 'Prorated Subtotal' value (excluding title)
6. When there are multiple very similar items, and you’re looking for one of them, you can use a relation to other item, like:
   1. ‘Item’ button near to ‘Remove’ button

When should I use AI Selectors?

AI Selectors are best suited when:

• The test writer is not familiar with technical selectors.

• The application under test is complex (e.g., data-heavy dashboards, dynamic layouts).

• You want faster and more resilient test creation with minimal configuration.

For more common questions about AI Selectors, be sure to check out the Frequently Asked Questions section.

2. Quick Selectors

Quick Selectors are lightweight selectors that TestFirst automatically generates based on common attributes like IDs, class names, or visible text. They're designed to help users rapidly create selectors without needing full automation logic or AI resolution.

The notation for using Quick Selectors is to use an exclamation mark at the beginning of the selector description. For example:

When I click "!Login"

This quick selector would look for elements (buttons, links etc.) using a set list of selectors that "may" contain the word "Login".

When should I use Quick Selectors?

Quick Selectors is good when you are writing tests to automate applications with unique and obvious UI elements on the page. For example, when there is only one button on a page that is called exactly "Login", then it may be good idea to utilize a Quick Selector as it is likely that one of the system-defined selectors could match with the desired element on the page.

ℹ️ The exact list of system-defined Quick Selectors can be seen in the Debug Log during test runs. For local/remote runs started within TF Automate, the Debug Log is found in the Execution Console. For remote runs started from a test plan, the Debug Log is always attached to the first step of the test result. 

Another advantage of using Quick Selectors is that it doesn't consume Cloud Credits. Since it utilizes system-defined sets of selectors based on a description, it doesn't cost money to generate.

The main down side of Quick Selectors is that they work less reliably since they are predefined and pretty limited in options they look for. Quick Selectors also don't do a great job if the UI contains items that are not identifiable by text or texts that appear multiple times on the page. 

For more common questions about Quick Selectors, be sure to check out the Frequently Asked Questions section.

3. Custom Selectors

Sometimes neither AI Selectors nor Quick Selectors would work. Or sometimes super users might want to have full control of the selector definitions. In such cases, you may create your own custom selectors in TF Automate.

To use custom selectors, you first need to create one.

For example, if you want to create a selector named Login, you’ll need to add it to the data repository. This article explains how to add a custom selector to the data repository.

Custom selectors are used by wrapping the selector name in single curly braces. For example:

When I click "{Login}"

However, creating good custom selectors is just as important. It can be a bit of a rabbit hole, so we’ve put together this article to guide you through best practices.

Creating custom selectors often requires HTML, XML, CSS and a bit of programming knowledge. They are the most time consuming to create. On the other hand, if your application doesn't change much, once created, they are the fastest during test runs. 

Just like Quick Selectors, custom selectors also don't cost any cloud credits. 

When should I use Custom Selectors?

Use Custom Selectors when you need full control and precision over how an element is located during automation.

They’re ideal for:

• Targeting highly dynamic or unstable elements

• Handling cases where AI or Quick Selectors aren’t accurate or resilient

• Reusing a carefully crafted XPath or CSS selector across multiple tests

• Working with edge cases, like hidden elements, nested components, or specific attributes

🛠️ Custom Selectors are manually defined using XPath or CSS, and are a great choice when you need reliability and exact targeting.

For more common questions about custom selectors, be sure to check out the Frequently Asked Questions section.

Some Additional Notes on Selectors

When I click "Some text in \"double quotes\" here"

When I click "Selector with a {{variable}}"

Given selector alias "<Selector alias>" for "<Selector>"

Frequently Asked Questions

What are AI Selectors in TestFirst Automate?
AI Selectors are smart, auto-generated element locators powered by machine learning. They’re designed to find UI elements without requiring technical selectors (like XPaths or CSS), making them ideal for non-technical users or complex UIs such as enterprise dashboards with dynamic tables and nested elements.

When should I use AI Selectors?
AI Selectors are best suited when:

• The test writer is not familiar with technical selectors.

• The application under test is complex (e.g., data-heavy dashboards, dynamic layouts).

• You want faster and more resilient test creation with minimal configuration.

Do AI Selectors consume cloud credits every time a test runs?
No. AI Selectors only consume cloud credits the first time they are resolved. Once an element is found, the selector is cached, and future executions no longer use additional credits for that selector—saving cost and improving performance.

How much do AI Selectors cost in cloud credits?
AI Selectors in TestFirst consume cloud credits only the first time they are resolved. The cost is based on the size of the page content being analyzed and is calculated as:

0.3 cloud credits per 10,000 tokens

Here’s what that means:

• The "token" count depends on the size and complexity of the page's HTML (DOM).

• Smaller, simpler pages may cost only a fraction of a credit.

• Heavier or complex pages (like dashboards with many nested elements) may use slightly more.

Once resolved, AI Selectors are cached and do not cost credits again unless the test is updated and those selectors need to be re-resolved.

💡 This makes AI Selectors highly cost-efficient — thousands can be resolved each month on the PRO plan without exceeding your 600-credit allowance.

What is a “token” when calculating AI Selector costs in TestFirst?
A token is a unit of text used behind the scenes by GPT (which power parts of TestFirst's AI functionality, like AI Selectors).

Think of a token as:

• A piece of a word, not always a full word

• For example, the sentence “Click the login button” is 6 tokens

• Larger blocks of text (like a full HTML page) can contain thousands of tokens

If I update a test that uses AI Selectors, will it consume cloud credits again?
Yes — but only partially. When you update a test (e.g., by editing a step or changing test logic), only the AI Selectors from the point of change onward need to be re-resolved. For example, if you update step 5 in a 10-step test, steps 1–4 will remain cached, while steps 5–10 will be re-evaluated and may consume cloud credits during the next run. After re-resolution, those selectors are cached again and won't cost credits in future runs (until the next edit beyond that point).

What are Quick Selectors in TestFirst?
Quick Selectors are lightweight selectors that TestFirst automatically generates based on common attributes like IDs, class names, or visible text. They're designed to help users rapidly create selectors without needing full automation logic or AI resolution.

Do Quick Selectors cost cloud credits?
No. Quick Selectors are free to use and do not consume any cloud credits. They’re resolved instantly within the test runner using known heuristics, making them a cost-effective option for straightforward UI elements.

Can I define my own selectors (i.e. custom selectors) in TestFirst?
Yes. You can write Custom Selectors using CSS or XPath to precisely identify elements in your application. This is useful when you need fine control or want to optimize selector stability for a frequently changing UI.

Can I use mixed selector types in the same test case?
Yes — TestFirst allows you to use a mix of AI Selectors, Quick Selectors, and Custom Selectors within the same test case.

This gives you flexibility to:

• Use AI Selectors for convenience and non-technical steps

• Drop in Quick Selectors for fast interactions with straightforward elements

• Apply Custom Selectors when you need full control or precision

🧠 You can even start with AI or Quick Selectors and later replace specific steps with Custom ones as needed — no need to rewrite the entire test.

This hybrid approach is great for balancing speed, maintainability, and accuracy in your test writing.

How does TestFirst's AI-powered assistant aid in test automation?
TestFirst's AI-powered assistant, Anton, enables users to generate automated test cases effortlessly by typing desired actions in natural language, simplifying the test creation process.

Can you compare AI Selectors, Quick Selectors and Custom Selectors?

Sure - here is a summarized table view what they are and when they should be used.

What is Anton in TestFirst?
Anton is TestFirst’s built-in AI assistant that helps you write automated tests faster and smarter. Think of it as your personal test co-pilot — you describe what you want to test in plain English, and Anton generates the test steps and selectors for you. It's perfect for teams that want to move fast without needing to dive into code or complex UI locators.

💡 Note: Anton is available only on the PRO or ULTIMATE plan.

How does Anton help me write better automated tests?
Anton makes automation easy by:

• Understanding natural language: Just describe the action — e.g., “Click the login button” — and Anton turns it into executable test steps.

• Auto-generating selectors: Anton uses AI to identify and create the right selector for the element you're referring to.

• Reducing setup time: You don’t need to search the DOM or write technical XPath/CSS selectors — Anton handles the details.

• Improving test clarity: Since tests are created in simple language, they’re easy to review, maintain, and share across the team.

Which selector type does Anton use when generating test steps?
Anton uses AI Selectors by default when generating test steps in TestFirst Automate.

Using Variables or Custom Selectors from Data Repository

In order to use a data repository item (variables, selectors) in your sentences, we developed the curly-brace syntax. After you type in the first curly brace, an auto-completer helps you identify the required item from a dropdown.

Examples of using "selectors" from the data repository

When I click "{Selector from the data repository}"
When I click "{Folder in the data repository.Selector in this folder}"

Examples of using "variables" from the data repository

When I type "{{Variable from the data repository}}" in "<Selector>"
When I type "{{Folder in the data repository.Variable in the folder}}"