sakuli-migration

Migrate Sakuli v1/v2 browser test scripts to Playwright tests running in the check_cep container.

2|Updated Mar 2, 2026
One-click install
npx skills add https://github.com/lausser/check_cep --skill sakuli-migration-lausser
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: sakuli-migration
Source: https://github.com/lausser/check_cep/tree/main/.agents/skills/sakuli-migration
Command: npx skills add https://github.com/lausser/check_cep --skill sakuli-migration-lausser

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Migrating legacy Sakuli monitoring tests to Playwright is error-prone: image-based SikuliX steps get silently replaced with DOM selectors, navigation paths get shortcut, and cookie banners break converted tests. This Skill enforces a faithful migration that preserves each step's original locator strategy. ## Core Features & Use Cases - Locator-intent preservation: Image-based steps (screen.find) become vision.clickByImage/typeByImage calls, DOM-based steps (_click, _setValue) become Playwright locators, and image-first-with-fallback steps become clickByImageOr/typeByImageOr. - Complete translation table: 30+ Sakuli API mappings (Sahi selectors, SikuliX screen operations, keyboard, popups, assertions) with before/after code snippets. - Migration rules and anti-patterns: Eight core rules covering route shortcuts, fallback discipline, template re-capture, non-migrateable desktop steps, and multi-stage image location. - Use Case: Given a Sakuli v1 script that navigates a site, fills a form via _setValue, and clicks a submit button via screen.find("submit.png"), produce a Playwright test with page.goto, page.locator().fill(), and vision.clickByImage() that runs inside the check_cep container. ## Quick Start Migrate my Sakuli test script to a Playwright test for the check_cep container, preserving image-based steps as vision calls and DOM steps as locators.

Frequently Asked Questions about sakuli-migration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate a Sakuli test script to Playwright?

Read the original script, classify each step as image-based, DOM-based, or framework boilerplate, then translate using the Sakuli-to-Playwright mapping table. Image steps become vision.clickByImage or typeByImage calls, DOM steps become page.locator calls, and TestCase boilerplate is removed.

How do I convert Sakuli screen.find image steps to Playwright?

Convert screen.find("btn.png").click() to vision.clickByImage(page, 'assets/btn.png', { region: 'main' }) from the check-cep-vision library. Do not replace image steps with DOM selectors, since that changes the original test's locator strategy.

Can Sakuli Sahi selectors like _click and _setValue map to Playwright?

Yes. _click(_link("Home")) maps to page.getByRole('link', { name: 'Home' }).click(), and _setValue(_textbox("email"), v) maps to page.locator('input[name="email"]').fill(v). The translation table covers over 30 Sahi API mappings.

Why do migrated image-matching steps fail inside the container?

Legacy Sakuli templates were captured under different viewport, DPR, and font rendering conditions. Re-capture all templates inside the container at 1280x720, DPR 1, with animations disabled, and narrow the search region before lowering confidence.

When is it acceptable to replace an image step with a DOM locator?

Only when the live site makes image matching unstable or impossible, such as animated controls or frequent redesigns. The switch must be a documented engineering decision with a comment explaining why image matching was abandoned for that step.

What Sakuli steps cannot be migrated to Playwright?

SikuliX desktop automation using Environment or Region for system-level keyboard, mouse, or desktop windows has no browser equivalent. These steps must be flagged with a comment as not migrateable rather than silently dropped.