Build and test Oobee

What this guide covers

This guide shows how to build the Oobee engine from source, run its tests and lint it. It also shows how to regenerate the HTML report from an existing results folder, which saves a full scan when you change the report templates. It is for contributors. It does not cover how to design a change.

Prerequisites

• Node.js 20 or later, and Java 11 or later with VeraPDF for PDF scans. Refer to Install Oobee manually.
• A clone of the Oobee repository.
• Google Chrome or Playwright’s Chromium.

Step 1: Install and build

In the repository folder, install the dependencies and compile the TypeScript:

npm install
npm run buildCopy to clipboardErrorCopied

npm run build copies the EJS templates, errorMeta.json and exclusions.txt into dist, then runs tsc. A stale dist folder keeps old behaviour, including bugs that you fixed in src/. Rebuild after every change.

Step 2: Run the engine

Run the CLI or the interactive mode from the built output:

npm run cli -- -c website -u <WEBSITE_URL> -p 5 -k "<YOUR_NAME>:<YOUR_EMAIL>"
npm startCopy to clipboardErrorCopied

To run the engine in Docker, build the image and pass the command:

docker build -t oobee .
docker run oobee node dist/cli.js -c website -u <WEBSITE_URL> -k "<YOUR_NAME>:<YOUR_EMAIL>"Copy to clipboardErrorCopied

Step 3: Run the tests

Run the unit tests with:

npm testCopy to clipboardErrorCopied

The command runs the files in tests/ with the Node.js test runner (node --test) and turns telemetry off. The files cover core helpers, address classification, URL and redirect guards, Safe Browsing archive handling, PDF limits, proxy and DNS behaviour, and the client scanner.

Run the end-to-end tests with:

npm run test:e2eCopy to clipboardErrorCopied

These tests run CLI scans against local servers, including PDF scans and scans over IPv4 and IPv6. They need a built dist, Chromium, and, for the PDF test, VeraPDF and a Java runtime on the path. Tests that use live sites run only when you set E2E_LIVE=1.

Step 4: Check types and lint

Check types without writing output, then lint:

npx tsc --noEmit
npm run lintCopy to clipboardErrorCopied

npm run lint fails on any warning. The lint rules use the Airbnb base rules with Prettier. Run npm run lint:fix to fix what can be fixed automatically. Prettier uses single quotes, two-space indents, a 100-character line and trailing commas.

Regenerate the HTML report

When you change the report templates in src/static/ejs/, regenerate the report from an existing results folder instead of running a scan:

npx tsx dev/runGenerateJustHtmlReport.ts results/<REPORT_FOLDER>Copy to clipboardErrorCopied

The script reads the existing JSON files in the folder and prints the path of the new report. Run npm run build first if you want to check the built copy of the templates, because npm run build is what copies the templates into dist/static/.

Check a change to the report templates

The report template partials share one global script scope. A top-level const, let or class in one partial can collide with the same name in another, and the browser then skips the whole script block without an error message. tsc does not check EJS files. After a change under src/static/ejs/, render the whole report, open it in a browser and check that the console has no errors. Refer to Contributor guidelines for the rule.

Constraints and limitations

Related content

• Oobee architecture — how the engine is organised.
• Contributor guidelines — pitfalls and rules to follow.