Elsetest documentation

Elsetest tests a website the way nobody scripts: a real Chrome browser clicks, types, selects and submits its way through the site, at random and with test input made to break things, and checks look at the pages it reaches along the way. It records a video and a log of the run, so you can see what it did and where it found each problem.

No configuration needed. Download Elsetest, start it and give it your site's address: it finds the forms, links and buttons, closes cookie banners and starts testing. The options, config files and plugins further down are for advanced use, when you want more control over a test.

Getting started

Download Elsetest for Linux, Windows or macOS. Nothing else needs installing: the first run downloads the Chrome it tests with. Start it, and its window asks for the site to test. Or from a terminal:

elsetest --url staging.example.com

Test a staging site with test data rather than your live site: Elsetest creates, changes and deletes data the way a user can, and types attack-like input. For a live site, block the requests that send data, so forms aren't sent:

elsetest --url www.example.com --blockRequests POST,PUT,PATCH,DELETE

To have the test logged in, let Elsetest watch you log in once. Setup then makes a config file for the site, with how to log in, whether it's a live site, and the AI model to use, if any:

elsetest --setup --url staging.example.com

Results

Each run writes a log, elsetest.log, and a video, elsetest.mp4, into a folder of its own, by default under Elsetest in your Documents folder (dir). The log has every action and every problem found: server errors, failed requests, console errors and JavaScript exceptions, and what the checks find. The video outlines what the test acts on in blue and the problems in red, with a caption saying what each is (highlight).

Config files

Every option can be set on the command line or in a JSON config file, and the plugins' options too:

{
  "url": "https://staging.example.com",
  "ignoreSelector": "#chat-widget",
  "plugins": [
    { "alias": "Login", "username": "tester@example.com", "password": "secret" },
    { "alias": "TypeJsInjection", "frequency": "off" }
  ]
}

elsetest --config staging.json --duration 10m

--printConfig prints the options given as a config file, to start one from. --printSchema prints the config file's JSON Schema, with every option and its description, for an editor to check a config file with, or for an AI to write one for your site.

What to test: url, scope, duration
The site: ignoreSelector, ignoreText, errorSelector, messageSelector, cookies, localStorage, delay, blockRequests
Results: highlight, highlightExplain, logLevel, ignoreLogs, failOn, dir, video
UI: gui, headless, windowSize, chrome

CI

In a pipeline, run Elsetest headless for a set time, and fail the build on the problems found with failOn. Without a terminal, it runs without its window. For the account, set ELSETEST_API_KEY to the API key that elsetest --login stored in credentials.json in your settings folder (~/.config/elsetest on Linux).

# GitHub Actions
- run: curl -fsSL https://elsetest.com/download/linux-x64 | tar xz
- run: ./elsetest/elsetest --config staging.json --headless --duration 10m --failOn error --dir results
  env:
    ELSETEST_API_KEY: ${{ secrets.ELSETEST_API_KEY }}
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: elsetest
    path: results

Exit code	Meaning
`0`	The test ran to its end (`--duration`).
`1`	The test couldn't go on: the site didn't load or stopped answering, the login failed, the browser didn't start...
`2`	Your testing time ran out.
`3`	Problems found, with `--failOn warn` or `--failOn error`.
`130`	Stopped with Ctrl+C.

Plugins

Plugins do the testing. In each step of a run, one plugin instance is picked at random, weighted by its frequency, and acts on the page: a check (e.g. CheckAccessibility) looks at the page it has got to, an action (e.g. ClickLink) uses it. Each instance has an alias (e.g. TypeEmail) and is of a plugin (e.g. Type); instances of the same plugin differ in their options. Change them with --plugin:

elsetest --url staging.example.com --plugin alias=TypeEmail frequency=off

Checks: what Elsetest finds

Accessibility testing: WCAG checks with axe-core: Checks the page's accessibility (WCAG) with axe-core and logs the problems found, with how to fix them.
AI testing: an AI model checks and uses your site: Has an AI model look at the page as a tester would (CheckWithAi), or use the site with a purpose, e.g. fill in forms with valid data and go through a checkout (ActWithAi), and logs the problems it finds. Needs an API key: --plugin name=Ai apiKey=... (for all of them).
Broken text: placeholders, mojibake and missing translations: Logs text the site shows without filling it in: message placeholders ({0}, {name}, %s), template code ({{name}}, ${name}), missing translations (??key??), JavaScript values ([object Object], NaN, undefined), broken character encoding (pÃ¥ for på, �) and HTML entities shown as text (&).
Overlapping text and icons: Logs text in the window that overlaps an icon or other text.
Spell checking in English and Swedish: Logs words in the page's English and Swedish text that look misspelled: not in the dictionary, but one letter from a word that is.
HTML validation with html-validate: Validates the page's HTML and logs the problems found.

Actions: how Elsetest uses the site

Random clicking: links, buttons, checkboxes and file uploads: Clicks random elements matching its selector, or random positions on them.
Going back and forward: Goes back or forward a page in the browser history.
Logging in: Logs in with a username and password. The login form is found automatically, or by the site marking its elements with data-elsetest-login attributes, which win over the selectors and auto-detection.
Scrolling: Scrolls the page with the mouse wheel or the keyboard.
Selecting options in dropdowns: Selects random options in dropdowns.
Typing test input: emails, emojis, long text and injection strings: Types text into, or clears, random input fields matching its selector; its instances differ in what they type.

Detectors: where Elsetest looks

Staying near errors: Detector, run after every plugin: when an element matching its selector (e.g. an error message) is on the page, other plugins favour the page area around it for a while. frequency doesn't apply.
Following dialogs and new content: Detector, run after every plugin: when elements are added to the page or shown (e.g. a dialog opens), other plugins favour them for a while. frequency doesn't apply.

This page is generated from the help texts of Elsetest 0.9.8. The same help is in the program: elsetest --help.