In-test Allure API for enriching test reports with steps, metadata, screenshots, and attachments.
All functions are no-ops when *context* is nil, meaning they are
safe to call even when not running under the Allure reporter.
Usage in tests:
(ns my-app.login-test (:require [com.blockether.spel.allure :as allure] [com.blockether.spel.page :as page] [com.blockether.spel.locator :as locator]))
(defdescribe login-flow (allure/epic "Authentication") (allure/feature "Login") (allure/severity :critical)
(it "logs in with valid credentials"
(allure/step "Navigate to login page"
(page/navigate page "https://example.com/login"))
(allure/step "Enter credentials"
(allure/parameter "username" "admin")
(locator/fill (locator/locator page "#username") "admin")
(locator/fill (locator/locator page "#password") "secret"))
(allure/step "Submit and verify"
(locator/click (locator/locator page "button[type=submit]"))
(allure/screenshot page "After login"))))
In-test Allure API for enriching test reports with steps, metadata,
screenshots, and attachments.
All functions are no-ops when `*context*` is nil, meaning they are
safe to call even when not running under the Allure reporter.
Usage in tests:
(ns my-app.login-test
(:require [com.blockether.spel.allure :as allure]
[com.blockether.spel.page :as page]
[com.blockether.spel.locator :as locator]))
(defdescribe login-flow
(allure/epic "Authentication")
(allure/feature "Login")
(allure/severity :critical)
(it "logs in with valid credentials"
(allure/step "Navigate to login page"
(page/navigate page "https://example.com/login"))
(allure/step "Enter credentials"
(allure/parameter "username" "admin")
(locator/fill (locator/locator page "#username") "admin")
(locator/fill (locator/locator page "#password") "secret"))
(allure/step "Submit and verify"
(locator/click (locator/locator page "button[type=submit]"))
(allure/screenshot page "After login"))))Dynamic var holding the current test's Allure context atom during
execution. Bound by the reporter's wrap-try-test-case. nil when
not running under the Allure reporter.
The atom contains: {:labels [{:name "epic" :value "Auth"} ...] :links [{:name "BUG-1" :url "..." :type "issue"} ...] :parameters [{:name "browser" :value "chromium"} ...] :attachments [{:name "screenshot" :source "uuid.png" :type "image/png"} ...] :steps [] ;; completed top-level steps :step-stack [] ;; stack for nesting (open steps in progress) :description nil} ;; markdown description
Dynamic var holding the current test's Allure context atom during
execution. Bound by the reporter's `wrap-try-test-case`. nil when
not running under the Allure reporter.
The atom contains:
{:labels [{:name "epic" :value "Auth"} ...]
:links [{:name "BUG-1" :url "..." :type "issue"} ...]
:parameters [{:name "browser" :value "chromium"} ...]
:attachments [{:name "screenshot" :source "uuid.png" :type "image/png"} ...]
:steps [] ;; completed top-level steps
:step-stack [] ;; stack for nesting (open steps in progress)
:description nil} ;; markdown descriptionDynamic var holding the java.io.File where the HAR (HTTP Archive)
will be written. Bound by with-traced-page. The HAR is written
when the BrowserContext closes. The Allure reporter captures this
path and attaches the HAR file as a download link after the test
completes. When nil (default), no HAR is captured.
Dynamic var holding the java.io.File where the HAR (HTTP Archive) will be written. Bound by `with-traced-page`. The HAR is written when the BrowserContext closes. The Allure reporter captures this path and attaches the HAR file as a download link after the test completes. When nil (default), no HAR is captured.
Dynamic var holding the allure-results output directory (java.io.File). Bound by the reporter alongside context.
Dynamic var holding the allure-results output directory (java.io.File). Bound by the reporter alongside *context*.
Dynamic var holding the current Playwright Page instance for automatic
step screenshots. When non-nil, every lambda step automatically captures
a "Post: <step>" screenshot after execution. Bind alongside the
test-fixtures *page*:
(binding [allure/page page] (f))
When nil (default), no automatic screenshots are taken.
Dynamic var holding the current Playwright Page instance for automatic step screenshots. When non-nil, every lambda step automatically captures a "Post: <step>" screenshot after execution. Bind alongside the test-fixtures `*page*`: (binding [allure/*page* page] (f)) When nil (default), no automatic screenshots are taken.
Dynamic var holding the test-level Writer for stderr accumulation. Same as test-out but for err.
Dynamic var holding the test-level Writer for stderr accumulation. Same as *test-out* but for *err*.
Dynamic var holding the test-level Writer for stdout accumulation.
Bound by the reporter's wrap-try-test-case to a per-test
StringWriter. Step capture tees to this so stdout flows to both
the step attachment AND the test-level system-out.
Dynamic var holding the test-level Writer for stdout accumulation. Bound by the reporter's `wrap-try-test-case` to a per-test StringWriter. Step capture tees to this so stdout flows to both the step attachment AND the test-level system-out.
Dynamic var holding the current test's display title.
Bound by the reporter's wrap-try-test-case to the test case
identifier (e.g. "captures screenshot and attaches to report").
Used by test fixtures for the Playwright trace title.
Dynamic var holding the current test's display title. Bound by the reporter's `wrap-try-test-case` to the test case identifier (e.g. "captures screenshot and attaches to report"). Used by test fixtures for the Playwright trace title.
Dynamic var holding the java.io.File where the Playwright trace zip
will be written. Bound by with-traced-page. The Allure reporter
captures this path and attaches the trace file (with MIME type
application/vnd.allure.playwright-trace) after the test completes.
When nil (default), no trace is captured.
Dynamic var holding the java.io.File where the Playwright trace zip will be written. Bound by `with-traced-page`. The Allure reporter captures this path and attaches the trace file (with MIME type application/vnd.allure.playwright-trace) after the test completes. When nil (default), no trace is captured.
Dynamic var holding the current Playwright Tracing object.
Bound by test fixtures (with-page, with-traced-page, with-api-tracing)
when tracing is active. When bound, step* automatically calls
tracing.group()/groupEnd() so steps appear as groups in the
Playwright Trace Viewer.
Dynamic var holding the current Playwright Tracing object. Bound by test fixtures (with-page, with-traced-page, with-api-tracing) when tracing is active. When bound, `step*` automatically calls tracing.group()/groupEnd() so steps appear as groups in the Playwright Trace Viewer.
(api-step step-name & body)Execute an API step with automatic request/response logging.
Wraps the body in an allure step. If the body returns a Playwright APIResponse, automatically attaches status, url, content-type as parameters and the response body as an attachment to the report.
Usage:
(allure/api-step "Create user" (api/api-post ctx "/users" {:data "{"name": "Alice"}" :headers {"Content-Type" "application/json"}}))
;; Parameters in report: ;; status → 201 ;; url → https://api.example.com/users ;; ok? → true ;; content-type → application/json ;; Attachment: ;; Response Body (application/json)
Works with any expression — only attaches metadata when the result is an APIResponse instance. No-op when not running under the Allure reporter.
Execute an API step with automatic request/response logging.
Wraps the body in an allure step. If the body returns a Playwright
APIResponse, automatically attaches status, url, content-type as
parameters and the response body as an attachment to the report.
Usage:
(allure/api-step "Create user"
(api/api-post ctx "/users"
{:data "{\"name\": \"Alice\"}"
:headers {"Content-Type" "application/json"}}))
;; Parameters in report:
;; status → 201
;; url → https://api.example.com/users
;; ok? → true
;; content-type → application/json
;; Attachment:
;; Response Body (application/json)
Works with any expression — only attaches metadata when the result
is an APIResponse instance. No-op when not running under the Allure
reporter.(attach att-name content content-type)Attach string content to the test report.
content-type is a MIME type, e.g. "text/plain", "application/json".
Attach string content to the test report. `content-type` is a MIME type, e.g. "text/plain", "application/json".
(attach-api-response! resp)Attach APIResponse metadata to the current allure step as parameters, attachments, and console log output. Safe — swallows all errors.
Captures:
This function is public because it is referenced by the api-step macro
which expands in the calling namespace.
Attach APIResponse metadata to the current allure step as parameters,
attachments, and console log output. Safe — swallows all errors.
Captures:
- Parameters: status, status-text, url, ok?, content-type, content-length
- Attachments: "Response Headers" (full HTTP header block),
"Response Body" (pretty-printed JSON, raw XML/HTML/text)
- Console log: status line, url, content-type, body preview
(shows as ⏵ marker sub-steps in the Allure report)
This function is public because it is referenced by the `api-step` macro
which expands in the calling namespace.(attach-bytes att-name bytes content-type)Attach binary content to the test report.
content-type is a MIME type, e.g. "image/png", "application/pdf".
Attach binary content to the test report. `content-type` is a MIME type, e.g. "image/png", "application/pdf".
(description text)Set the test description (markdown supported).
Set the test description (markdown supported).
(epic value)Set the epic label for this test.
Set the epic label for this test.
(feature value)Set the feature label for this test.
Set the feature label for this test.
(link name url)Add a link to the test report.
Add a link to the test report.
(make-context)Create a fresh context map for a test case. Called by the reporter.
Create a fresh context map for a test case. Called by the reporter.
(parameter name value)Add a parameter to the test or current step.
Add a parameter to the test or current step.
(reporter-active?)Returns true when the Allure reporter is active (i.e. we're generating a report). Fixtures use this to auto-enable tracing.
Returns true when the Allure reporter is active (i.e. we're generating a report). Fixtures use this to auto-enable tracing.
(screenshot pg att-name)Take a Playwright screenshot and attach it to the report.
pg is a Playwright Page instance. att-name is the display name.
Take a Playwright screenshot and attach it to the report. `pg` is a Playwright Page instance. `att-name` is the display name.
(set-reporter-active! active?)Called by the Allure reporter at begin/end of test run.
Called by the Allure reporter at begin/end of test run.
(severity level)Set the severity label. Level should be one of: :blocker :critical :normal :minor :trivial
Set the severity label. Level should be one of: :blocker :critical :normal :minor :trivial
(step step-name)(step step-name & body)Add a step to the test report.
Two arities:
Steps can nest arbitrarily:
(allure/step "Login" (allure/step "Enter username" (locator/fill username-input "admin")) (allure/step "Enter password" (locator/fill password-input "secret")) (allure/step "Click submit" (locator/click submit-btn)))
All step calls are no-ops when not running under the Allure reporter.
Add a step to the test report.
Two arities:
- (step name) — marker step (checkpoint, no body)
- (step name & body) — lambda step (executes body, timed, nestable)
Steps can nest arbitrarily:
(allure/step "Login"
(allure/step "Enter username"
(locator/fill username-input "admin"))
(allure/step "Enter password"
(locator/fill password-input "secret"))
(allure/step "Click submit"
(locator/click submit-btn)))
All step calls are no-ops when not running under the Allure reporter.(step* step-name)(step* step-name f)Internal function backing the step macro. Prefer the macro.
Two arities:
Does NOT take screenshots. Use ui-step for steps that need
before/after screenshots, or call screenshot explicitly.
Internal function backing the `step` macro. Prefer the macro. Two arities: - (step* name) — marker step (records a named checkpoint, no body) - (step* name f) — lambda step (executes f, records timing and status) Does NOT take screenshots. Use `ui-step` for steps that need before/after screenshots, or call `screenshot` explicitly.
(story value)Set the story label for this test.
Set the story label for this test.
(tms name url)Add a test management system link.
Add a test management system link.
(ui-step step-name & body)Execute a UI step with automatic before/after screenshots.
Creates a parent step with two nested child steps:
Requires *page* to be bound (typically done by the reporter's
with-traced-page or test fixtures).
When Playwright tracing is active (*trace-path* is bound), the
explicit screenshots are skipped — the trace already captures visual
state on every action, so the screenshots would only add noise to
the trace timeline without providing additional value.
The step hierarchy in the Allure report (without tracing):
✓ Login to application ├── Before: Login to application (screenshot) ├── ... (your actions) └── After: Login to application (screenshot)
Usage:
(allure/ui-step "Fill login form" (locator/fill username-input "admin") (locator/fill password-input "secret") (locator/click submit-btn))
Falls back to a regular step when *page* is not bound.
No-op when not running under the Allure reporter.
Execute a UI step with automatic before/after screenshots.
Creates a parent step with two nested child steps:
- "Before: <name>" — screenshot captured before the action
- "After: <name>" — screenshot captured after the action
Requires `*page*` to be bound (typically done by the reporter's
`with-traced-page` or test fixtures).
When Playwright tracing is active (`*trace-path*` is bound), the
explicit screenshots are skipped — the trace already captures visual
state on every action, so the screenshots would only add noise to
the trace timeline without providing additional value.
The step hierarchy in the Allure report (without tracing):
✓ Login to application
├── Before: Login to application (screenshot)
├── ... (your actions)
└── After: Login to application (screenshot)
Usage:
(allure/ui-step "Fill login form"
(locator/fill username-input "admin")
(locator/fill password-input "secret")
(locator/click submit-btn))
Falls back to a regular step when `*page*` is not bound.
No-op when not running under the Allure reporter.cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |