kensho-robot

A Robot Framework Listener (v3) that emits the canonical Kensho v1 JSON format. Run your tests, then point the kensho CLI at kensho-results/ to get a self-contained static HTML report.

Install

pip install kensho-robot
# or, in this monorepo:
pip install -e packages/robot

Run

robot --listener kensho_robot.Listener tests/
# => kensho-results/run.json + kensho-results/cases/*.json

# Generate the HTML report (uses the JS CLI from the same monorepo):
npx kensho generate
npx kensho open

Pass listener options after a colon:

robot --listener kensho_robot.Listener:output=kensho-results:project_name=Demo tests/

What it produces

• kensho-results/run.json — run manifest (project, env, totals, timing).
• kensho-results/cases/<stableId>.json — one file per Robot test.
• kensho-results/attachments/<caseId>/... — files registered via kensho_robot.attach.

Each case gets a stable id (tc_<16 hex>) hashed from its full name + file path, so test history correlates across runs and across adapters (JS, pytest, and Go all use the same FNV-1a-based hash).

Listener hook → Kensho mapping

Tags we read

Robot tags do double duty as Kensho metadata. Aliases all work; @-prefixes are optional.

*** Settings *** Documentation on the suite becomes the default case.behavior.feature for every test inside (override per-test with @feature:).

[Documentation] on a test becomes case.description.

[Template] My Keyword records the template name in case.parameters[].

Helper API

Import the helpers from kensho_robot. All four are no-ops outside a running test, so it's safe to call them from shared library code.

import kensho_robot as kensho

def open_login_page():
    with kensho.step("warm up CDN"):
        ...
    with kensho.step("issue request"):
        ...

def attach_screenshot():
    kensho.attach("/tmp/screen.png", kind="screenshot")
    kensho.label("traffic", "synthetic")
    kensho.link("https://jira.example.com/browse/PROJ-123",
                kind="jira", label_text="PROJ-123")

Errors and broken vs fail

• PASS → status: 'pass'.
• FAIL from a test-body keyword → status: 'fail'. The Robot failure message becomes case.errors[].message; the full message goes into case.errors[].stack.
• FAIL whose source is a [Setup] or [Teardown] keyword → status: 'broken' (infrastructure, not a real assertion failure).
• SKIP / NOT RUN → status: 'skip'.
• Any other status (e.g. parse errors) → status: 'broken'.

Environment auto-detected

GitHub Actions, CircleCI, GitLab CI, Jenkins, Buildkite, Azure DevOps — CI provider, branch, commit, run URL, OS, architecture, Python version.

Pass KR_AUTHOR, KR_COMMIT_MSG, KR_STAGE, KR_BASE_URL, KR_APP_VERSION, KR_BUILD_NUMBER, KR_RELEASE, KR_REGION, KR_LOCALE, KR_TRIGGER, or KR_FEATURE as env vars to populate the matching fields on run.env.

Design notes

• Zero runtime dependencies beyond robotframework. The schema lives in the JS workspace; we vendor the minimum (id-hashing, status mapping, env capture) inline so the adapter installs in seconds.
• The listener never raises out of a hook — a broken adapter must not break a test run. All errors come out as warnings.warn.
• IDs are stable across adapters: the FNV-1a hash matches kensho-pytest, kensho-go, and the JS reporters byte-for-byte, so a test run on Robot rolls up to the same history as the same suite run elsewhere.

License

Apache-2.0.