DramaFinder Setup Runbook¶

This file is a runbook for Claude to execute after the user confirms the setup plan in SKILL.md Step 1. Do not relay it to the user as documentation — perform the steps.

Constants¶

KNOWN_LATEST = 1.1.2 — fallback version if Maven Central lookup fails. Bump when the library releases.

Step 1 — Resolve the latest version¶

Run:

curl -s "https://repo1.maven.org/maven2/org/vaadin/addons/dramafinder/maven-metadata.xml" \
  | grep -o '<release>[^<]*</release>' | sed 's/<[^>]*>//g'

If the command returns a non-empty version string, use it. Otherwise, use KNOWN_LATEST.

Step 2 — Edit `pom.xml`¶

Two edits, both in pom.xml:

2a. Add the version property¶

Inside <properties>, add:

<dramafinder.version>RESOLVED_VERSION</dramafinder.version>

Replace RESOLVED_VERSION with the value from Step 1. If a <dramafinder.version> property already exists, leave it alone.

2b. Add the dependencies¶

Inside <dependencies>, add (skip whichever is already present):

<dependency>
    <groupId>com.microsoft.playwright</groupId>
    <artifactId>playwright</artifactId>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>org.vaadin.addons</groupId>
    <artifactId>dramafinder</artifactId>
    <version>${dramafinder.version}</version>
    <scope>test</scope>
</dependency>

Note the groupId is org.vaadin.addons (not org.vaadin.addons.dramafinder).

Step 3 — Copy `SpringPlaywrightIT` (Spring Boot projects, DramaFinder before 2.0)¶

Skip this step entirely if the project is not a Spring Boot project, or if the resolved DramaFinder version is 2.0 or later: the library then ships org.vaadin.addons.dramafinder.spring.SpringPlaywrightIT, and tests extend it directly. It needs spring-boot-starter-test (test scope), which every Spring Boot project already has; DramaFinder itself never adds Spring to the classpath.

If find src/test/java -name SpringPlaywrightIT.java already returns a result, skip — the file exists and will be used as-is.

Otherwise:

Find the base package by locating the class annotated with @SpringBootApplication under src/main/java. Take its package (e.g., com.example.app).
Target package is <basePackage>.it.support (e.g., com.example.app.it.support).
Read templates/SpringPlaywrightIT.java.tmpl from this skill directory.
Substitute {{PACKAGE}} with the target package.
Write the result to src/test/java/<basePackage-as-path>/it/support/SpringPlaywrightIT.java.

Step 4 — Add a CLAUDE.md pointer¶

Skill matching is heuristic: a future task that never mentions Vaadin, Playwright, or tests won't trigger the skill on its own. A standing pointer in the project's CLAUDE.md fixes that (it is loaded into context every session).

Skip this step if CLAUDE.md already mentions vaadin-playwright-test. Otherwise append to CLAUDE.md (create the file if it doesn't exist):

## Integration testing

This project uses DramaFinder for Playwright integration tests. For any
integration/IT test work (writing, editing, or running tests for Vaadin
views), use the `vaadin-playwright-test` skill.

Step 5 — Confirm dependencies resolve¶

Optional but recommended: run mvn -q dependency:resolve to surface any pom syntax errors before generating tests. Skip if the user wants to proceed without compile-time verification.

Debugging with a visible browser (informational)¶

To run tests with a visible browser, pass -Dheadless=false:

mvn -Dit.test=MyViewIT -Dheadless=false verify

A debug-ui profile can be added to pom.xml for shorthand -Pdebug-ui. Mention this only if the user asks about debugging.