Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
target
spotless-index
.since-index
*.iml
.idea
3 changes: 1 addition & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@ each Vaadin component in a *tester* that drives it the way a browser would.

- Java 21+, Maven (multi-module)
- Vaadin 25 / Flow — a `provided` dependency, one fixed version per branch
- Kotlin for the older mock and internal layer in `shared/src/main/kotlin`
- JUnit 6 (Jupiter) for the test API and for this repository's own tests
- An annotation processor (`locator-processor`) that generates the typed
locator API at build time
Expand Down Expand Up @@ -84,7 +83,7 @@ mvn test -pl junit6 -Dtest=BasicGridTesterTest#basicGrid_selectionOnClick
# Run the tests matching a pattern
mvn test -pl junit6 -Dtest="*ComboBox*Test"

# Generate the Javadoc/Dokka artifacts the way CI does
# Generate the Javadoc artifacts the way CI does
mvn clean install -DskipTests -Djavadocs
```

Expand Down
11 changes: 8 additions & 3 deletions CONVENTIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,9 +112,7 @@ Go through the Vaadin extension points rather than around them — fire service
and session lifecycle events through the `VaadinService` event bus, and forward
`Instantiator` calls to the real instantiator instead of reimplementing them.

New code in `shared` is written in Java. The Kotlin sources under
`shared/src/main/kotlin` are the older mock and internal layer and are being
ported to Java; do not add new Kotlin files there.
This repository is written in Java; do not add Kotlin sources.

See [`guidelines/architecture.md`](guidelines/architecture.md).

Expand Down Expand Up @@ -152,6 +150,13 @@ detail.
Javadoc describes the code today, not what changed. Change history belongs in
commit messages.

In a tester, spell cross-package `@link` and `@throws` targets out in full:
`locator-processor` copies the Javadoc into the generated `*Locator`, which has
no imports. Every module builds clean under doclint, warnings included, so every
published member needs a description, its `@param`s and its `@return` — a class
that would otherwise get an undocumented default constructor declares an
explicit one.

See [`guidelines/documenting.md`](guidelines/documenting.md).

## Testing
Expand Down
499 changes: 499 additions & 0 deletions de-kotlin-plan.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion guidelines/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ found too — a Dialog's content, a Grid's header, footer and editor components,
a Card's slots.

`ElementConditions` holds the element-level predicates the query builds on.
`Locator` (the internal Kotlin one, not the public locator API) and
`Locator` (the internal one, not the public locator API) and
`DepthFirstTreeIterator` do the walking; `PrettyPrintTree` renders the tree for
`TreeOnFailureExtension`.

Expand Down
10 changes: 10 additions & 0 deletions guidelines/documenting.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,16 @@ order:
- **Mark internal API as internal.** "For internal use only. May be renamed or
removed in a future release." on classes like `BaseBrowserlessTest` is what
keeps them changeable.
- **Spell cross-package `@link` and `@throws` targets out in full** in a
tester. `locator-processor` copies a tester method's Javadoc into the
generated `*Locator`, which has no imports, so `{@link Span}` resolves in the
tester and fails there. Write `{@link com.vaadin.flow.component.html.Span
Span}`. Same-package names and `{@link #member}` are fine — the processor
rewrites the latter to point back at the tester.
- **Every published member needs a comment.** Every module builds clean under
doclint, warnings included, so a missing `@param`, `@return` or description
shows up in the `-Djavadocs` build. A class that would otherwise get an
undocumented default constructor declares an explicit one.

## Documenting the mocks

Expand Down
13 changes: 5 additions & 8 deletions guidelines/repository.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,11 @@
- **Java 21+**, **Maven** (multi-module, parent `com.vaadin:vaadin-parent`).
- **Vaadin 25 / Flow** as a `provided` dependency, one fixed version per
branch — see [Flow Version](flow-version.md).
- **Kotlin** for the older mock and internal layer in `shared/src/main/kotlin`.
New code is Java; the Kotlin is being ported over time.
- **JUnit 6 (Jupiter)** for the published test API and for this repository's
own tests. A few legacy Kotlin tests still use DynaTest and Karibu DSL.
own tests.
- **ClassGraph** for classpath scanning (routes, testers).
- **Spotless** with the Eclipse formatter for style; no checkstyle.
- **Dokka** for Javadoc in the mixed Java/Kotlin modules, `maven-javadoc-plugin`
elsewhere.
- **maven-javadoc-plugin** for Javadoc in every module.

## Module structure

Expand Down Expand Up @@ -44,10 +41,10 @@ modules that declare testers.
`Locator`, `Locators`, `CommercialLocators` and the `Has*Filter` mixins. The
`*Locator` classes themselves are generated into
`target/generated-sources/annotations`.
- **The mocks** live in `com.vaadin.browserless.mocks` (Kotlin):
- **The mocks** live in `com.vaadin.browserless.mocks` (Java):
`MockService`, `MockVaadinServlet`, `MockRequest`, `MockResponse`,
`MockHttpSession`, `MockedUI`.
- **Internal helpers** live in `com.vaadin.browserless.internal` (Kotlin):
- **Internal helpers** live in `com.vaadin.browserless.internal` (Java):
`MockVaadin`, `Routes`, `Locator`, `PrettyPrintTree`, `Shortcuts`.
- **Tests** live in `junit6/src/test/java`, mirroring the package of the code
they cover. See [Testing](testing.md).
Expand All @@ -73,7 +70,7 @@ Formatting is applied by `mvn spotless:apply` and validated by
`eclipse/VaadinJavaConventions.xml`, the import order in
`eclipse/flow.importorder`, the Apache 2 license header in
`eclipse/apache2-license-header.txt`, no wildcard imports, and a trailing
newline. Kotlin files get the license header check only.
newline.

## Blast radius

Expand Down
2 changes: 0 additions & 2 deletions guidelines/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,6 @@ Layout inside `junit6/src/test`:
`LocatorApiTest`, `SignalsTest`) and the shared test contracts.
- `java/com/example/…` — views and fixtures that tests navigate to, kept out of
the framework packages so route scanning stays predictable.
- `kotlin/` — the remaining DynaTest/Karibu-style tests of the Kotlin internals.
Do not add new ones; write new tests as JUnit 6 in Java.

The Spring, Quarkus and CDI integrations have their own test sources, because
each needs a different container on the classpath. `junit6-cdi-tests` exists
Expand Down
93 changes: 0 additions & 93 deletions junit6/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -22,68 +22,12 @@
</resources>

<plugins>
<!--
To compile projects that include Kotlin and Java source code, the Kotlin compiler should run before
the Java compiler.
That means that kotlin-maven-plugin definition must be placed before maven-compiler-plugin
-->
<plugin>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-plugin</artifactId>
<executions>
<execution>
<id>compile</id>
<goals>
<goal>compile</goal>
</goals>
<configuration>
<sourceDirs>
<sourceDir>${project.basedir}/src/main/kotlin</sourceDir>
<sourceDir>${project.basedir}/src/main/java</sourceDir>
</sourceDirs>
</configuration>
</execution>
<execution>
<id>test-compile</id>
<goals>
<goal>test-compile</goal>
</goals>
<configuration>
<sourceDirs>
<sourceDir>${project.basedir}/src/test/kotlin</sourceDir>
<sourceDir>${project.basedir}/src/test/java</sourceDir>
</sourceDirs>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<executions>
<!-- Replacing default-compile as it is treated specially by maven -->
<execution>
<id>default-compile</id>
<phase>none</phase>
</execution>
<!-- Replacing default-testCompile as it is treated specially by maven -->
<execution>
<id>default-testCompile</id>
<phase>none</phase>
</execution>
<execution>
<id>java-compile</id>
<phase>compile</phase>
<goals>
<goal>compile</goal>
</goals>
</execution>
<execution>
<id>java-test-compile</id>
<phase>test-compile</phase>
<goals>
<goal>testCompile</goal>
</goals>
<configuration>
<!-- End-user-style configuration: run the locator
processor on junit6's own test sources, with
Expand Down Expand Up @@ -111,24 +55,6 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<executions>
<execution>
<id>add-kotlin-sources-for-source-jar</id>
<phase>package</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<source>src/main/kotlin</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
Expand Down Expand Up @@ -170,18 +96,6 @@
<scope>provided</scope>
</dependency>

<dependency>
<groupId>com.github.mvysny.dynatest</groupId>
<artifactId>dynatest</artifactId>
<version>0.25</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.github.mvysny.karibudsl</groupId>
<artifactId>karibu-dsl</artifactId>
<version>1.0.8</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>browserless-test-shared</artifactId>
Expand All @@ -192,13 +106,6 @@
<artifactId>junit-jupiter</artifactId>
</dependency>

<dependency>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-stdlib</artifactId>
<version>${kotlin.version}</version>
</dependency>


<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
Expand Down
Loading
Loading