Sigil.Executor 0.1.0

Sigil

Visual marker-based UI testing for modern development. Built for AI-assisted workflows.

Installation

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

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

# Verify installation
sigil --version

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

Quick Start

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 "user@test.com"
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):

<button sig="checkout">Submit</button>


<button data-testid="checkout">Submit</button>


<button data-sigil-id="checkout">Submit</button>

Commands Reference

Mouse Commands

click marker-id
doubleclick marker-id
rightclick marker-id
hover marker-id
drag source target

Input Commands

type marker-id "text"
clear marker-id
press Enter
hotkey ctrl+a
hotkey ctrl+shift+s
focus marker-id
blur marker-id

Form Commands

select marker-id "option-text"
check marker-id
uncheck marker-id

Navigation Commands

navigate "url"
goto "url"
back
forward
refresh

Scroll Commands

scroll down
scroll 500
scrollto marker-id

Wait Commands

wait marker-id 5000
waitgone marker-id 10000
delay 500
waitnetwork 5000

Assertions

assert visible marker-id
assert hidden marker-id
assert text marker-id "expected"
assert value marker-id "expected"
assert checked marker-id
assert unchecked marker-id

Data Extraction

read marker-id
read marker-id variable-name
readvalue marker-id
readattr marker-id attr-name
readattr marker-id attr-name variable

Utility Commands

screenshot filename.png
log "message"
upload marker-id "/path/to/file.pdf"

Running Multiple Tests

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"

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

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

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"

CI/CD Integration

GitHub Actions

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

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

Framework Support

Sigil works with any web framework:

• React (Create React App, Next.js, Vite)
• Vue (Vue CLI, Nuxt, Vite)
• Angular
• Blazor (Server & WebAssembly)
• Svelte / SvelteKit
• Vanilla HTML/JS

Component Libraries

Supported libraries:

• MudBlazor
• Bootstrap
• Radzen
• Syncfusion
• Telerik
• Ant Design
• MatBlazor
• Native HTML

Optional Packages

npm Package

You probably don't need this. The executor injects the script automatically.

npm install @getsigil/core

import { Sigil } from '@getsigil/core';
Sigil.init({ enabled: true });
Sigil.show();
Sigil.hide();

Blazor Package

You probably don't need this. The executor injects the script automatically.

dotnet add package Sigil.Blazor

<SigilScope>
  <button sig="submit">Submit</button>
</SigilScope>

License

Pro license required for:

• Parallel execution
• Multi-viewport testing
• HTML summary reports
• Commercial use

Free tier includes:

• 100 test runs (full features trial)
• Unlimited sequential tests (after trial)
• All viewport sizes
• CLI & CI/CD support

Support

• Documentation: https://usesigil.dev/docs
• Email: support@getsigil.dev