We recently announced Dolt's built-in test engine, which allows users to execute query suites against their databases and automatically validate results against predefined assertions. We think this feature is a necessity for enabling agentic workflows that operate on data. If you want to learn more about the internals of dolt_tests, you can check out this blog or read through the documentation here.

Today, we're excited to announce that the Dolt Workbench now natively supports Dolt's test engine, enabling unit test workflows entirely from the UI. Let's walk through the new interface and discuss how to use it.

Tests Page

The first thing you'll notice after connecting the workbench to a Dolt database is the new "Tests" tab on the top navbar.

If you click on that, you'll reach the Tests page. This is where you can create, delete, modify, and run your tests.

Create Tests

Let's start by creating a new test. Click the "Create" button at the top right, then "Create Test".

This will create a blank test with some default values. Notice that the new test appears underneath the "Ungrouped" header. This is used to distinguish between tests that are assigned to a test group and those that are not. Since we haven't created a test group yet, our test falls into the "Ungrouped" category.

Let's make this test a bit more interesting. My database has a table called grades with the following schema:

CREATE TABLE `grades` (
  `id` varchar(36) NOT NULL DEFAULT (uuid()),
  `student_id` varchar(36) NOT NULL,
  `course_id` varchar(36) NOT NULL,
  `letter_grade` varchar(2) NOT NULL,
  `numeric_grade` decimal(5,2) NOT NULL,
  `created_at` timestamp DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `course_id` (`course_id`),
  UNIQUE KEY `unique_student_course` (`student_id`,`course_id`),
  CONSTRAINT `grades_ibfk_1` FOREIGN KEY (`student_id`) REFERENCES `students` (`id`),
  CONSTRAINT `grades_ibfk_2` FOREIGN KEY (`course_id`) REFERENCES `courses` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_bin

I'd like to write a test to verify that the letter_grade column is always either 'A', 'B', 'C', 'D', or 'F'. Here's one way to do that:

Now, I can run my test by pressing the green run button at the top right corner of the test dropdown. When I run the test, Dolt will execute the query I just wrote, then check whether or not the single value returned by the query is exactly equal to zero. Let's run it and see what happens:

Great, the test passed! To illustrate the failing case, I'll run the following query, which will assign the letter grade E to one of the rows in the grades table.

UPDATE `grades` SET `letter_grade` = 'E' WHERE `id` = '1a3cac52-02d8-4f5d-bc30-6fd682baa5fd'

Now, if I run the same test, I'm met with the following error message:

Create Test Groups

Most of the time, you'll probably want to execute more than a single test at once. One of the ways to do this is by creating a test group. In the workbench, you can create a new group by clicking "Create" at the top right, followed by "Create Group". This will bring up the following pop-up:

Here, you can create an empty group with a name of your choosing. Initially, your new group won't have any tests assigned to it. Let's assign the test we defined in the previous section to the data_integrity group. Now that the group exists, the group name will populate in the "Test Group" dropdown section of the test. Selecting it will assign the test to the group.

Now, I'll write a few more tests and assign all of them to the data_integrity group. After doing this, I can run all tests in the group at once by clicking the run button at the group level.

Since all the tests in the group passed, the group is marked with the green "Passed" indicator. If at least one test in a group fails, then the group is marked with the "Failed" indicator. Also, note the blue plus button at the top right of the group tab — this can be used to quickly create a new test and immediately assign it to that group. Similarly, the delete button will delete the group as well as all tests that belong to it.

Finally, you might want to run all of your tests at once. To do this, simply click the "Run All" button in the top right corner of the page.

Run Tests Before Merge

A common use case for the Dolt test framework is to execute your tests on a branch before merging in order to validate any changes. To make this process more seamless, we added a component that allows you to run tests before performing a merge from the workbench. If you have tests defined on your branch, you'll see the following section above the Merge option:

After clicking "Run", the test results are displayed here immediately.

In this example, one of our tests failed. If you click on the failing test, it will bring you to the test's definition as well as the error message on the Tests page. After fixing the issue, all tests are passing and our branch is ready to merge!

Conclusion

Here at DoltHub, we're really excited about making our built-in testing functionality as easy-to-use as possible. If there's anything you'd like to see as it relates to dolt_tests or the workbench, join our Discord and let us know!