wacat video demonstrating AI capabilities

wacat - Challenge Your Web App with Cat Chaos and AI-Driven Testing!

Imagine, you leave your computer for a while and go to pick up a cup of coffee. Meanwhile, your cat walks over your keyboard and causes some chaos.

wacat (walking cat) application

Navigates to the root URL of your web application
Visits every link in your application in a random order
Inputs random text into forms
Selects random values from dropdown menus, checkboxes, etc
Clicks every button in a random order

Additionally, wacat:

Detects error messages on web pages using AI
- This is an optional feature and requires an OpenAI API key
Generates AI-driven content for input fields
- Optional feature requiring an OpenAI API key
- Supports generating invalid or broken input content
Detects HTTP errors (e.g., HTTP 500 errors) between the browser and server
Detects errors in the browser's console log
Detects user-defined error messages on web pages
- These error messages are specified in a parameter file
- Use this if AI is not enabled
Supports user-defined configurations for random form text inputs
Can read form inputs from external files (e.g., resources like Combined-Wordlists)
Can focus exclusively on testing links, which is useful for smoke testing your application
Supports some authentication scenarios
- Authentication configurations are provided in a JSON file
Allows configuration of pages that should not be visited
Allows configuration of buttons to avoid pushing
Adding headers for authentication and other purposes
Supports a headless mode
Allows configuration of page download wait times and overall test timeout values
Supports running in CI pipelines

Technical details

wacat uses the Playwright tool internally. It is tested to work on Windows, Linux, and Mac.

Reporting bugs and requesting features

If you encounter a bug or need a specific feature, please create a new issue.

Current Version

The current version of wacat is 1.5.4. Please refer to the end of this page for the change history.

Warnings

Please ensure you only test your own web application or have explicit permission to test someone else’s application. Testing the vulnerabilities of an application without authorization could be illegal.

The application is designed to stay within the host you are testing. However, as this is a hobby project, unexpected behavior is possible. It's important to monitor wacat's actions and use Ctrl + C to stop the process if it navigates to an unintended page.

Additionally, if your application requires authentication and your wacat authentication configuration is incorrect or incompatible, it could lead to issues such as account lockouts. wacat could also potentially disrupt your application's database or other components. For these reasons, it is strongly recommended to use wacat only in a testing environment.

Installation

Install Node.js

Install Node.js from here. wacat has been tested and verified to work with Node.js version 20 on Linux, Mac, and Windows.

Clone wacat and install it

Clone the wacat repository, navigate to the wacat folder, and run the following command:

npm install && npx playwright install --with-deps && npm run build && npm install -g

Note: You may be prompted for your password when running the above command, as the Playwright tool is installed globally.

Optional: Add OpenAI API Key

If you want to use AI for error detection (see details below), add your OpenAI API key and model to a .env file:

OPENAI_API_KEY=<your key here>
OPENAI_API_MODEL=<your model here>

Important: Providing an OpenAI API key will result in charges from OpenAI for API usage. While wacat has been thoroughly tested, please be aware that programming errors could lead to a higher-than-expected number of calls to the OpenAI API.

Additionally, please note that if your website contains sensitive material, the contents of your pages will be sent to the OpenAI API, and you must ensure that this aligns with your intended use. For example, it is possible that the content you send may be used as training data.

You can also add the following optional environment variable to the .env file:

MAX_PAGE_CONTENT_CHARS=<your value here>

This value sets the maximum number of characters sent to the OpenAI API for error detection. The default is 3000 if not specified. See additional details below.

You can optionally use the following environment variable:

AI_GENERATED_INPUT_TEXTS=true

When set to true, the OpenAI API will generate values for all input fields on each page. By default, this value is set to false. Please note that enabling this option can result in significant API usage. Therefore, it is recommended to have at least a Tier 1 usage plan, as it allows for a higher number of requests per minute compared to the Free tier. Using the Free tier plan is possible, but it may be very slow if there are numerous OpenAI API calls.

Updating wacat

To update wacat to the latest version, run:

git pull && npm install && npx playwright install --with-deps && npm run build && npm i -g

Running

Basic usage

Run the following command in the wacat folder:

wacat test <your url>

For example, the command:

wacat test https://mikesmallhelp-test-application.vercel.app/

tests a simple application at the URL https://mikesmallhelp-test-application.vercel.app/. The application includes the following pages:

First, the wacat application opens the Chromium browser and navigates to the root URL provided in the command:

The root page does not contain any input fields, dropdown menus, or similar elements. wacat simply collects links to the two subpages and visits them. On each subpage, wacat performs the following actions:

Presses the button
Fills the form fields, selects options from dropdown menus, etc.
Presses the button again

Here is the command for you to copy, paste, and run. You can follow the same process to run all other examples. Feel free to experiment with the provided test applications.

wacat test https://mikesmallhelp-test-application.vercel.app/

Testing in url: https://mikesmallhelp-test-application.vercel.app/. Please wait...


Running 1 test using 1 worker
[chromium] › test.spec.ts:41:1 › test an application
In the page: https://mikesmallhelp-test-application.vercel.app/
In the page: https://mikesmallhelp-test-application.vercel.app/working-page2
Push the button #1
Filling the #1 text input field a value: _k6AKNU3z"{=myqS.K
The label is 'Your Date of Birth Here', so generating an appropriate random content for the input field
Filling the #2 text input field a value: 16/09/2004
The #1 drop-down list. Selecting the option #2
Selecting the #1 checkbox
The #1 radio button group. Selecting the radio button #3
Filling the #1 email input field a value: pvcgigtju.nwntltbk@uqimkbwwiz.com
Filling the #1 password input field a value: A#1!!a#!#AaA!A
Filling the #1 search input field a value: SZOmqATkrV
Filling the #1 url input field a value: https://nrebn.com
Push the button #1
In the page: https://mikesmallhelp-test-application.vercel.app/working-page
Push the button #1
Filling the #1 text input field a value: _k6AKNU3z"{=myqS.K
The label is 'Your Date of Birth Here', so generating an appropriate random content for the input field
Filling the #2 text input field a value: 16/09/2004
The #1 drop-down list. Selecting the option #2
Selecting the #1 checkbox
The #1 radio button group. Selecting the radio button #2
Filling the #1 email input field a value: uxxdxqcjhq.mhettm@ukyefgvdsk.gov
Filling the #1 password input field a value: aa2B#1aA!##2A#!AaA
Filling the #1 search input field a value: lSjsBVOzkhCC
Filling the #1 url input field a value: https://vpo7ut.net
Push the button #1
  1 passed (24.3s)

Note: The default wait time for each page is 5000 milliseconds. To adjust this wait time, use the --wait flag (see details later).

Optional: Detect errors on the page with AI

Here is an example application that contains an error message, "An unexpected error occurred! Please try again after some time.", on one of its subpages:

If you provide an OpenAI API key (see above), wacat can use AI to detect error messages like this on the page.

For example, run the command:

wacat test https://mikesmallhelp-test-application-error-in-page.vercel.app/

The command output might look like this:

Testing in url: https://mikesmallhelp-test-application-error-in-page.vercel.app/. Please wait...

 ›   Error: 
 ›   Error occurred: Command failed: ROOT_URL='https://mikesmallhelp-test-application-error-in-page.vercel.app/' npx playwright test --project=chromium --headed
 ›    + stderr:  + stdout: 
 ›   Running 1 test using 1 worker
     [chromium] › test.spec.ts:45:1 › test an application
 ›   In the page: https://mikesmallhelp-test-application-error-in-page.vercel.app/
     Check with the AI that the page doesn't contain errors.
     In the page: https://mikesmallhelp-test-application-error-in-page.vercel.app/working-page
     Check with the AI that the page doesn't contain errors.
     Push the button #1
     Check with the AI that the page doesn't contain errors.
     Filling the #1 text input field a value: AyXoEJ_Sd$(7+JqeROkD
     The #1 drop-down list. Selecting the option #2
     Push the button #1
     Check with the AI that the page doesn't contain errors.
     In the page: https://

Wacat

Install / Use

README