Verify your install

npx botscent check tests a Botscent install from outside. It requests your page, opens the page in a local Chrome, and reads your project. Run it at the end of every install, and again after each fix.

1. Start the site

Start the site that you installed Botscent in. A local server and a deployed site both work.

2. Run the check

From the project's directory, run the check against the URL of one page:

npx botscent check http://localhost:3000/

The check prints one line for each check, then a summary line.

3. Read the output

This output comes from a run against the Botscent site, which runs Next.js on Vercel:

botscent check 0.0.0: https://botscent.nibnalin.me/
PASS     reachable     200, text/html; charset=utf-8
PASS     server-half   entry 1;botscent-check;1790995621428;ua.declared-agent-token on check's own request
PASS     entry         fresh (+0.9 s) and single
PASS     no-store      Cache-Control: no-store
PASS     person        no entry on a request without agent evidence
PASS     cache         cached HTML (Age: 1335), decorated after the cache lookup
PASS     page-script   botscent 0.0.0 started 852 ms after navigation
PASS     page-verdict  agent [browser.webdriver-flag, ua.headless-chrome] under automation, as expected
PASS     transport     the page received 1;;1790995622694;ua.headless-chrome
PASS     probes        10 ok
PASS     csp           no policy
SKIPPED  script        no botscent.js tag; the page half is bundled, or absent
PASS     stack         Next.js; on Vercel
SKIPPED  adapters      not run inside a project (pass --project <dir>)
Installed.

Each line gives the outcome, the check id and what the check observed. A line that is not a pass also gives the likely cause and the fix.

The last line is Installed., Unverified: neither half could be confirmed. or a Broken: line with the number of failed checks.

4. Fix each failure

If a line says FAIL, apply the fix that the line gives. Then run the check again. For the common failures, see Common fixes.

If a line says UNKNOWN, read its likely cause. At an origin server with the transport off, an UNKNOWN line for server-half is expected.

What the check does

The check does 3 things, in this order:

1. It requests the page as a navigation, with the user agent botscent-check/<version>. Then it requests the page again at once, with an empty user agent. If a cache stored the first response, the cache serves the stored copy to the second request.
2. It opens the page in a local Chrome or Chromium over the DevTools protocol. It reads the page verdict, the page half's diagnostics, the Server-Timing entries, console errors and Content Security Policy violations.
3. It reads the project in the current directory, or in the directory that --project gives. It finds the frameworks and every botscent import. It compares a Next.js proxy or a Vercel middleware file with its version at git HEAD.

Chrome under the DevTools protocol sets the webdriver flag, as any automation does. So the page half reports an agent in the check's browser, with the reason browser.webdriver-flag. The page-verdict check expects this.

Options

Outcomes

The checks

The checks run and print in this order:

Exit codes

Output for scripts and agents

With --json, the check prints one JSON object. This sample shows only the first of the 14 checks:

{
  "check": "0.0.0",
  "url": "https://botscent.nibnalin.me/",
  "checks": [
    {
      "id": "reachable",
      "outcome": "pass",
      "observed": "200, text/html; charset=utf-8"
    }
  ],
  "exit": 0
}

Each check has id, outcome and observed, and can have detail, cause and fix. The detail field holds the page's own text, such as its error messages.

With --report, the check adds a block to paste into an issue. The block has the versions, the stack, the adapters, the Botscent entries and the diagnostics. It has no query string, cookie, address or detail text.

The option names, the JSON field names, the check ids, the outcomes and the exit codes stay the same across minor versions. The text of each line can change in any release.

Common fixes

Warning: If person fails, turn the transport off now. A cache serves an agent's entry to people, and their pages then report an agent.

Related

• npx botscent check: the full reference for the command.
• From the server to the page: what the Server-Timing entry is, and when an adapter writes it.
• Quickstart: install Botscent with one prompt, or pick your framework.
• Log verdicts for a week: the first step once the check passes.