Just in case you haven’t met yet… TQL meet ET Users, ET users meet TQL
Welcome to the first instalment of a series of blog posts on the new Test Query Language (TQL) Features introduced in Enterprise Tester 4.0 and above.
The posts are going to be spread over the next couple of months, at about one a week, and each post will build on the last, so that at the end you should be a TQL guru.
Throughout this series I’m going to encourage you to try out the examples yourself and will provide you with all the data necessary (as baselines), so you can execute the queries on your own Enterprise Tester servers, if you have any trouble trying out the examples then please leave a comment on the post.
So let’s get started!
How to start querying
Within Enterprise Tester there are two ways to start searching your data, Globally, or within a package.
To search globally you can either type some text into the search box in the top right corner of the Enterprise Tester UI and press enter, or just click the magnifying glass to the right of the search text box:
This will take you to the global search window, which let’s you search for any type of entity, across all the projects that are visible to you.
Alternatively you can click on a requirement package, script package, execution package or the incidents folder for a project, and then click the “Filter” button, to open up filtering for that grid.
In these cases we say that the results of the search are “Scoped” i.e. you want see anything returned in the results that is not within the selected package/project.
Once you have arrived at the search screen, make sure you have the “Search” tab selected.
This will allow you to construct a query through the user interface, and is by far the easiest way to get started writing TQL queries in Enterprise Tester.
The Search tab is split into three sections:
- Simple
- Advanced
- Custom
From the simple tab you can perform all your basic filtering tasks – everything you used to do from the filter drop-down of the grids in earlier versions of Enterprise Tester is available here, and a lot more.
For more advanced searches (or should we say more esoteric querying needs) you have the Advanced tab. This is like the Kitchen sink of search filtering – and is split into different categories based on the kind of information you want to search on.
Clicking on a section will expand it to display all the possible filtering options.
Last of all there is the Custom tab – this will be empty unless you have defined some custom fields within Enterprise Tester, and allows you to filter on the values of those custom fields.
Adding some data
Before we proceed, let’s add a test project with some test data (this will require you to be an Administrator, if you are not the Administrator of your ET instance, you will have to ask your Administrator nicely to set up a test project just for you).
Navigate to the admin tab, expand your organisation and right click on the Projects folder.
Select “Add Project” – you will be shown the add new project screen.
Give the project a name such as “TQL Tutorial”.
Click the “Current User” button to make yourself the project manager for this project.
Click “Save” to save your changes.
Now we have our project set up, we will need to import some data – to do so, download this baseline:
(A baseline is snapshot of project or package level information, see the user guide for more info).
Now right click on the project and select “Manage Baselines”.
Next click the “Import” toolbar button, you will then be taken to the import grid.
Click upload, select the baseline file you downloaded above and click OK.
Once uploaded the file will be available in the list, click the baseline to select it, then click the “Import” button.
Click OK to proceed (after making sure you are restoring the baseline to your new project, not one of your existing production projects!).
After a few seconds the restore should complete.
We now have some test data.
Our first search
Let’s return back to the simple search at the application level – click the magnifying glass, and once the search screen has loaded, click the “Search” button to execute an “empty” search.
In the results we can see entities of different types being returned – by default if we don’t specify anything in the query we will get all entity types back except Packages.
Now let’s change our query, to only get back Requirements, by clicking the “Requirements” checkbox and clicking search.
We can see the results returned – now click the “Query” tab to see the resulting Query.
As you can see our selection on the “Search” tab has been reflected in a query and we didn’t have to write the TQL ourselves.
Next make a change in the TQL window, let’s change the word “Requirement” to “Script” to get back only scripts in our search results.
Clicking search, we can see the new results. But wait, what if you want to add some more criteria to your query – no problem, just return to the Search tab.
We can now see that our change to the query is reflected on the search screen – now let’s filter our scripts by status, to only include those which are “Approved”.
If we now move back to the query tab we can see that our two selections are combined using the word “AND”.
Hopefully you can now see how we can use these search screens to jump-start our TQL query writing.
Infix Expressions (AND and OR)
Let’s take a closer look at the current query – as you can see we have two expressions (we call them terminal expressions) representing our two criteria.
And these are joined by an “AND” – this means that both of these expressions must be true for the result to be included in the result set – so in this case it’s not enough that their type is requirement or status is “approved”, they must match both expressions.
Enterprise Tester does support matching on either/or of these criteria too though – to do that change “AND” to “OR” like so:
These “AND” and “OR” key words are called “infix” operators, which means they can be used between expressions.
Beyond using the search screen to build queries easily, we also support dragging and dropping from the Tree to add additional query fragments.
So for example, to get results only from the project we added earlier, “TQL Tutorial”, we could drag and drop the project from the Explorer tree onto the TQL editor window.
At that point you will see a menu pop up with different fragments you can add to your query, let’s select the value:
Project = ‘TQL Tutorial’
You can see it was automatically added to our query as an “AND”.
Sorting
TQL also supports sorting – you can sort your query by clicking on the column’s header in the grid, let’s click on “Name”.
Notice the query has now been updated to include the sort order.
We can either click the same column again to toggle the sort direction (ascending or descending) – or we can edit the query and change the order ourselves.
You can sort in reverse order by using the “DESC” keyword after the name of the field you wish to order by.
Though you can not order by two or more fields in the user interface, we do support this in TQL, just separate each field with a comma like so:
ORDER BY Package ASC, LastUpdatedAt DESC
You might have noticed that while typing in the query the border changed to red and the Green tick became a red cross – this indicates that the query contains a syntax error. You can opt to keep typing, or if you want to see the details of the error you can hover your mouse over the textbox, or press Enter – which will replace the grid on the bottom half of the screen with the error message.
In some cases error messages will also include a link to the online help i.e. if you passed it an invalid value or unsupported operator.
Lets take a look at the help system next.
Help!
It’s not always clear what you can do with a field, or what fields are available – but fear not, help is at hand – just click the “Query Help” link above the TQL editor and in-line help will pop-up.
Let’s take a quick tour of what’s in the help, and how to navigate around.
Note: We offer a PDF extract of all the online help content for those that don’t have access ET, or prefer to read off-line – you can download it here.
When first accessing help you will be taken to the TQL topic, this provides an overview of searching and is a good jumping off point.
If you are looking for fields you can search on, then expand the “TQL topic”, and the expand the “Fields” topic, from here you can see a list of all the fields you can search on.
If we click on a field and take a look at it’s help we can see that we provide it’s name, description, some example queries that use it and some additional information about what you can do with the field.
In order the additional information let’s you know:
The supported operators (this let’s you now what you can do with the field, clicking on an operator will take you to a page that explains how the operator works – in our previous queries above the “IN” and “=” keywords are both operators. You can learn more about operators in the next post in this series.
The supported indexes – within Enterprise Tester when searching you are generally searching the “Entities” index – but in some cases you may use special types of query to search “into” other indexes. In most cases all you need to know is that if “Entity” is NOT listed as one of the supported indexes, you will not be able to use the field in your queries – we will cover the topic of indexes and sub-selects later on in the series, as it’s an advanced feature we don’t expect most users of TQL to need.
The supported types – This provides a list of all the types that have this field.
And last of all there is supported features – this indicates if:
- The field supports aggregation (if it does not, it won’t be available for use in graphs, and can not be used in aggregation expressions).
- You can sort by the field.
- If the field supports sub-selects (which we will cover more in a later post).
Once you have found the information you need in the help, just hit the Escape key or click the X icon in the top right to close the help window.
Saving our query for later
Last of all, once you have got your query just the way you want it, you might want to save it for use in the future, to do that click the “Save” button, which will switch to you the “Manage” tab.
From here you can give your query a name, an optional description and decide if you want to share it with the rest of your team, or keep it all to yourself.
Saved queries also retain your column selections – we can pick which columns to display by clicking the “Columns” toolbar button.
Let’s select to display these columns:
- Package
- Number
- Name
- Priority
- Status
And then save our query again, to apply these changes.
Once you have saved a query they can be later found on the Shared Queries and My Queries tab of the Manage screen, once you have a lot of saved queries, you may find it easier to find them by typing into the Search box, which will automatically filter the list as you type.
Till next time
Well I hope you all enjoyed this first post.
In the next post we will be getting down into the basics of TQL itself, examining each of the available operators, and taking a wider look at writing more complex queries.
If you have any feedback on this series, or have any topics you would like to see covered, please leave comments below – we always love your feedback.