Checksum.ai Tests

Quick Start

1. Run npm install -D checksumai.
2. Navigate to the directory where you want to add Checksum tests and run npx checksumai init.
3. Run npx playwright install --with-deps to install Playwright dependencies.
4. Edit checksum.config.ts to include necessary configurations such as:
   • apiKey
   • baseURL
   • username
   • password
5. Update login.ts with your login function using Playwright. See the Login Function section below for guidance.
6. Run npx checksumai test to execute the example test and verify successful login.
7. If you haven't already, visit app.checksum.ai to complete the configuration and generate a test. Then, wait for the pull request (PR) to be created and approve it.

Login Function

1. This function is executed at the start of each test.
2. We recommend using a consistent seeded user for every test. For example, before each test, call a webhook that creates a user, seeds it with data, and returns the username and password. This approach ensures test reliability and allows parallel test execution. Configure this webhook in your project for consistent test generation.
3. After logging in, assert that the login was successful. Playwright waits for assertions to be correct, ensuring that the page is ready for interaction before proceeding.
4. To reuse authentication states between tests, refer to the Playwright guide on authentication. At the start of the login function, check if the user is already authenticated and return if so.

Checksum AI Magic

The tests generated by Checksum are based on Playwright. When executed using the Checksum CLI with an API key, Checksum enhances Playwright's functionality, improving test reliability and automatically maintaining tests.

Autonomous Test Agent

Checksum runs your Playwright tests regularly, but we added a few extra features to make tests more reliable. All of the features can be turned on/off through checksum.config.ts

Smart Selectors When generating tests, Checksum stores extensive metadata for each action (see the test-data folder). If a traditional selector fails, this metadata is used for correction. For example, if a test identifies an element by its ID but the ID changes, Checksum utilizes other data points (e.g., element class, text, parents) to locate the element. Use the checksumSelector("<id>") method to link an action to its metadata. Do not alter the IDs.

Checksum AI If Smart Selectors also fail, Checksum's custom-trained model can regenerate the failed section of the test. In such cases, the model might add, remove, or alter actions to achieve the same objectives, without changing the assertions. The assumption is that as long as the assertions pass, the model has successfully fixed the test. Use the .checksumAI("<natural language description of the test>") method to guide the model in fixing the test.

You can modify the description as needed for our model. Additionally, you can include steps with only ChecksumAI descriptions, prompting our model to generate the Playwright code. For example, await page.checksumAI("Click on 'New Task' button") without the actual action will have our model generate the necessary Playwright code. You can even author entire tests in this manner.

Run Modes

Checksum offers three run modes:

1. Normal - Tests are executed using the Autonomous Test Agent as defined in the config file.
2. Heal - If the Autonomous Test Agent corrects a test, a new test file with the fix is created. By default, this file is created locally, but you can also configure the Agent to open a PR to your GitHub repository by setting autoHealPRs to true.
3. Refactor (Work in Progress) - The Autonomous Test Agent runs the test and, for each action, regenerates a regular Playwright selector, a Smart Selector, and a Checksum AI description.

Mock Data

When generating tests, Checksum records all backend responses, allowing tests to run in the same backend context. This is particularly useful for debugging or initial test runs, especially if your testing database/context differs from that used for test generation. Note that if your backend response format changes, the mocked data may not work as expected.

CLI Commands

1. init - Initialize the Checksum directory and configurations.
2. test - Run Checksum tests. Accepts all Playwright command line flags. To override checksum.config.ts, pass full or partial JSON as a string, e.g., --checksum-config='{"baseURL": "https://example.com"}'.

Running with GitHub Actions

See the example file github-actions.example.yml.

Troubleshooting

Q: I'm seeing various exceptions when I run "npx checksumai test", even before the test starts.

A: If you had a pre-installed version of Playwright, it might not be compatible with Checksum. Remove both Playwright and Checksum libraries, delete the relevant folder from node_modules, and run npm install -D checksumai.