Key concepts
This guide covers the key concepts you should know before you get started.
How it works
Actions
When you first run a test, the SDK performs an extraction. During an extraction, the SDK waits for your app to idle, then sends your instructions and a snapshot of your HTML to the API to be analyzed.
With this information, the API generates a test script containing the elements and actions required to perform your instructions. Test scripts use xpaths to locate the element, which are constructed to try and match the semantic meaning of your instructions. This way, the test script is resilient to deviations and changes in your HTML.
If the test is successful, the extraction is saved in the specified cache directory.
The next time you run the test, the SDK only waits until your HTML matches the cached state (by performing xpath lookups) - avoiding the need to perform any unnecessary waits or additional extractions. The resulting effect is that your tests will run as fast as hand-written tests.
Assertions
Assertions work in the same way, except instead of building a list of actions, it builds a list of assertions to be evaluated by the browser.
The assertions are provided by the API as a set of Javascript evaluations that the SDK will run directly inside the browser.
For advanced use cases, we recommend you use Carbonate to lookup the element you need and perform the assertion manually.
What are actions, assertions and lookups?
We've not actually explained the difference between these terms yet so here's a brief introduction.
Instructions
Instructions is the generic term for anything you're asking the AI to do. Actions, assertions and lookups are all different types of instructions.
Actions
Actions are something you want to be done by the AI:
Examples
- Fill in the email field with X
- Click the hamburger menu
- Sort the table by the Name column
Assertions
Assertions are something you want to be verified by the AI.
Examples
- The email field should contain the value X
- I should see a mobile menu
- The columns should be sorted by Name
Lookups
Lookups are something you want to find using the AI. Lookups have most of the benefits of actions and assertions but they let you implement the action or assertion yourself.
Examples
- The email field
- The hamburger menu in the header
- The Name column in the table