Documentation

Installation

Install the Sigil CLI tool globally using the .NET SDK (requires .NET 8+):

Terminal

# Install the CLI
dotnet tool install -g Sigil.Executor

# Verify installation
sigil --version

# Run a test
sigil run test.sigil -a "http://localhost:3000"

That's it! No npm packages, no config files. Just add sig attributes to your elements and run tests.

Quick Start

Get Sigil running in under 5 minutes:

1. Add sig attributes to your HTML

<button sig="login">Login</button>
<input sig="email" type="email" />
<input sig="password" type="password" />
<div sig="dashboard">...</div>

2. Create test.sigil

type email "[email protected]"
type password "secret123"
click login
wait dashboard 5000
assert visible dashboard

3. Run the test

sigil run test.sigil -a "http://localhost:3000"

Marker Attributes

Sigil supports three attributes for marking elements (in priority order):

Supported Attributes

<!-- Option 1: sig (shortest, recommended) -->
<button sig="checkout">Submit</button>
<input sig="email" type="email" />

<!-- Option 2: data-testid (React Testing Library compatible) -->
<button data-testid="checkout">Submit</button>

<!-- Option 3: data-sigil-id (explicit, full name) -->
<button data-sigil-id="checkout">Submit</button>

Use sig for new projects. Existing data-testid attributes work automatically - no changes needed!

Script Injection

Sigil automatically injects the marker detection script via CDP. No setup required.

Default Behavior

# Script injection is ON by default
sigil run test.sigil -a "http://localhost:3000"

# Elements with sig/data-testid/data-sigil-id get visual markers
# Works with any framework - no npm package needed

Disable Injection

# If your app already has Sigil.Blazor or @getsigil/core:
sigil run test.sigil --no-inject -a "http://localhost:3000"

Framework Support

Sigil works with any web framework. No packages to install - just add sig attributes and run tests.

Supported Frameworks

# Works out of the box with:
React (Create React App, Next.js, Vite)
Vue (Vue CLI, Nuxt, Vite)
Angular
Blazor (Server & WebAssembly)
Svelte / SvelteKit
Vanilla HTML/JS
Any other web framework

# No npm/NuGet packages needed. Just run:
sigil run test.sigil -a "http://localhost:3000"

click / doubleclick / rightclick

Click on a marker element.

click marker-id
doubleclick marker-id
rightclick marker-id

# Examples
click submit-button
doubleclick file-item
rightclick table-row

hover / drag

Move mouse or drag elements.

hover marker-id
drag source target

# Examples
hover tooltip-trigger
drag card-1 column-done

type / clear

Type text into a field or clear it.

type marker-id "text"
clear marker-id

# Examples
type email-input "[email protected]"
clear search-box
type search-box "new search"

press / hotkey

Press keys or key combinations.

press key
hotkey key+key+...

# Supported keys: Enter, Tab, Escape, Backspace, Delete,
# Up, Down, Left, Right, Home, End, PageUp, PageDown, F1-F12

press Enter
hotkey ctrl+a
hotkey ctrl+shift+s

focus / blur

Set or remove focus from elements.

focus marker-id
blur marker-id

# Examples
focus search-input
blur input-field  # triggers onblur

select

Select an option from a dropdown.

select marker-id "option-text"

# Works with native <select> and component libraries
select country-dropdown "United States"
select priority-select "High"

check / uncheck

Check or uncheck checkboxes.

check marker-id
uncheck marker-id

# Examples
check agree-terms
uncheck newsletter-opt-in

navigate / goto

Navigate to URLs or use browser history.

navigate "url"
goto "url"
back
forward
refresh

# Examples
navigate "http://localhost:5000/dashboard"
refresh

scroll / scrollto

Scroll the page or to a specific marker.

scroll direction-or-pixels
scrollto marker-id

# Directions: up, down, pageup, pagedown, top, bottom
scroll down
scroll 500  # scroll down 500px
scrollto footer-content

wait / waitgone

Wait for markers to appear or disappear.

wait marker-id timeout-ms
waitgone marker-id timeout-ms

# Examples
wait dashboard-header 5000
waitgone loading-spinner 10000

delay / waitnetwork

Fixed delays or wait for network activity.

delay milliseconds
waitnetwork timeout-ms

# Examples
delay 500
waitnetwork 5000  # wait for requests to settle

assert visible / hidden

Assert marker visibility.

assert visible marker-id
assert hidden marker-id

# Examples
assert visible dashboard-header
assert hidden error-message

assert text / value

Assert element content or input values.

assert text marker-id "expected"
assert value marker-id "expected"

# Examples
assert text page-title "Dashboard"
assert value email-input "[email protected]"

assert checked / unchecked

Assert checkbox state.

assert checked marker-id
assert unchecked marker-id

# Examples
check agree-terms
assert checked agree-terms

read / readvalue

Read text content or input values.

read marker-id
read marker-id variable-name
readvalue marker-id

# Examples
read user-count
read total-price price_value
readvalue email-input

readattr

Read an attribute from an element.

readattr marker-id attr-name
readattr marker-id attr-name variable

# Examples
readattr link href
readattr image src image_url
readattr button disabled

screenshot / log

Capture screenshots or output log messages.

screenshot filename.png
log "message"

# Examples
screenshot login-page.png
log "Starting login test"

upload

Upload a file to a file input.

upload marker-id "file-path"

# Examples
upload file-input "/path/to/document.pdf"
upload avatar-upload "./images/profile.jpg"

Running Multiple Tests

Sigil supports running multiple test files simultaneously with full control over concurrency, viewports, and output.

Basic Syntax

# Single test
sigil run test.sigil -a "http://localhost:3000"

# Multiple tests (glob pattern)
sigil run tests/*.sigil -a "http://localhost:3000"

# Multiple tests (explicit)
sigil run -s test1.sigil -a "http://localhost:3000" \
          -s test2.sigil -a "http://localhost:3000"

Concurrency Control

# Default: 20 concurrent tests
sigil run tests/*.sigil -a "http://localhost:3000"

# Limit concurrent tests
sigil run tests/*.sigil -j 5 -a "http://localhost:3000"
sigil run tests/*.sigil --max-concurrent-tests 5 -a "http://localhost:3000"

# Sequential (1 at a time)
sigil run tests/*.sigil --sequential -a "http://localhost:3000"

Tests are queued and executed as slots become available. When a test finishes, the next one in the queue starts automatically. Progress is shown in real-time:

[1/500] login-test.sigil (desktop): PASS
[2/500] checkout-test.sigil (desktop): PASS
[3/500] search-test.sigil (mobile): FAIL
...

Viewports

# Named viewport presets
sigil run test.sigil --viewport desktop -a "http://localhost:3000"  # 1920x1080
sigil run test.sigil --viewport tablet -a "http://localhost:3000"   # 768x1024
sigil run test.sigil --viewport mobile -a "http://localhost:3000"   # 375x667

# Multiple viewports (runs each test on each viewport)
sigil run test.sigil --viewports desktop,tablet,mobile -a "http://localhost:3000"

# Shorthand for desktop,tablet,mobile
sigil run test.sigil --viewports responsive -a "http://localhost:3000"

# Custom viewport sizes
sigil run test.sigil --viewports 1920x1080,768x1024,375x667 -a "http://localhost:3000"

# Multiple scripts + multiple viewports (full matrix)
sigil run tests/*.sigil --viewports responsive -a "http://localhost:3000"

Different Addresses Per Test

# Each test can have its own address
sigil run -s login.sigil -a "http://localhost:3000/login" \
          -s dashboard.sigil -a "http://localhost:3000/dashboard" \
          -s checkout.sigil -a "http://localhost:3000/checkout"

Output & Reports

# Generate HTML summary report
sigil run tests/*.sigil --summary -a "http://localhost:3000"

# Specify output directory
sigil run tests/*.sigil --summary -o ./test-results -a "http://localhost:3000"

Headless Mode (CI/CD)

# No visible browser window
sigil run tests/*.sigil --headless -a "http://localhost:3000"

Script Injection

# Default: auto-inject sigil.js via CDP
sigil run tests/*.sigil -a "http://localhost:3000"

# Disable injection (app has Sigil.Blazor or @getsigil/core)
sigil run tests/*.sigil --no-inject -a "http://localhost:3000"

Full Example: Overnight Regression Suite

sigil run regression/*.sigil \
  -j 5 \
  --headless \
  --summary \
  -o ./nightly-results \
  -a "http://localhost:3000"

This runs all .sigil files in regression/, max 5 at a time, headless, with an HTML report saved to ./nightly-results.

Headless Mode

Run tests without a visible browser window:

sigil run test.sigil --headless -a "http://localhost:3000"

Perfect for CI/CD pipelines and automated testing environments.

CI/CD Integration

Add Sigil to your GitHub Actions workflow:

.github/workflows/test.yml

- name: Install Sigil
  run: dotnet tool install -g Sigil.Executor

- name: Run UI Tests
  run: sigil run tests/*.sigil --headless -a "http://localhost:3000"

Component Libraries

Sigil works with popular UI component libraries:

# Supported libraries:
- MudBlazor
- Bootstrap
- Radzen
- Syncfusion
- Telerik
- Ant Design
- MatBlazor
- Native HTML

# Works with select, check/uncheck, read, assert
select mud-dropdown "Option 1"
assert text mud-text "Hello"

Tip: Wrap component library checkboxes in a div with sig for best results.

npm Package (Optional)

You probably don't need this. The executor injects the script automatically. Only install if you need programmatic control:

npm install @getsigil/core

// Only for advanced use cases:
import { Sigil } from '@getsigil/core';
Sigil.init({ enabled: true });
Sigil.show();   // Show markers
Sigil.hide();   // Hide markers

Blazor Package (Optional)

You probably don't need this. The executor injects the script automatically. Only install for advanced Blazor-specific features:

dotnet add package Sigil.Blazor

// SigilScope provides Blazor-native marker rendering
<SigilScope>
  <button sig="submit">Submit</button>
</SigilScope>