Skip to content

5.0.0.md

Latest commit

 

History

History
253 lines (174 loc) · 8.81 KB

5.0.0.md

File metadata and controls

253 lines (174 loc) · 8.81 KB
Raw

Serenity BDD 5.0.0 Release Notes

This is a major release with breaking changes. Please review the upgrade notes carefully.

Breaking Changes

JUnit 5 Cucumber Plugin Path Changed

The Cucumber plugin classes have been moved from io.cucumber.core.plugin to net.serenitybdd.cucumber.core.plugin to resolve Java Platform Module System (JPMS) split package violations.

Required Action for JUnit 5 Users:

Update your test suite configuration:

// BEFORE (4.x)
@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "io.cucumber.core.plugin.SerenityReporterParallel"
)

// AFTER (5.0.0)
@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel"
)

Impact: All users running Cucumber tests with JUnit 5 must update their plugin configuration.

Migration: See MIGRATION_5.0.0.md for detailed migration instructions.

Deprecations

JUnit 4 Cucumber Support Deprecated

JUnit 4 Cucumber integration is now officially deprecated and marked for removal in Serenity 6.0.0.

Affected Classes:

  • io.cucumber.junit.CucumberSerenityRunner
  • io.cucumber.junit.CucumberSerenityBaseRunner
  • net.serenitybdd.cucumber.CucumberWithSerenity

Rationale:

  • JUnit 5 was released in September 2017 (8+ years ago)
  • JUnit 4 runners must remain in io.cucumber.junit package to access package-private Cucumber classes
  • This creates split package violations incompatible with JPMS (Java Platform Module System)
  • When Cucumber migrates to Java 17+ with JPMS modules, JUnit 4 integration will stop working

Timeline:

  • Serenity 5.x: JUnit 4 support deprecated but functional (deprecation period)
  • Serenity 6.0.0: Complete removal of JUnit 4 Cucumber support

Action Required: Plan migration from JUnit 4 to JUnit 5. See the migration guide for step-by-step instructions.

Improvements

JPMS Compatibility

This release significantly improves compatibility with the Java Platform Module System (JPMS):

  • Reduced Split Packages: Migrated 12 classes out of io.cucumber.* packages into net.serenitybdd.cucumber.* packages
  • Package Structure Cleanup: Serenity classes now properly reside in Serenity-owned packages
  • Future-Proofing: Prepares for Cucumber's planned migration to Java 17+ with JPMS modules

Classes Migrated:

From io.cucumber.core.plugin → net.serenitybdd.cucumber.core.plugin:

  • FeatureFileLoader
  • ScenarioContext
  • ScenarioContextParallel
  • SerenityReporter
  • SerenityReporterParallel
  • ConfigureDriverFromTags
  • FeaturePathFormatter
  • FeatureTracker
  • LineFilters
  • ManualScenarioChecker
  • ScenarioTagProcessor
  • TaggedScenario
  • UpdateManualScenario
  • TestSourcesModel (new Serenity-owned implementation)

From io.cucumber.gherkin → net.serenitybdd.cucumber.gherkin:

  • CucumberScenarioLoader
  • ScenarioLineCountStatistics
  • IncrementingIdGenerator
  • GherkinDocumentParser (new)
  • InvalidGherkinException (new)

From cucumber.runtime → net.serenitybdd.cucumber.runtime:

  • SerenityBackend
  • SerenityObjectFactory

From io.cucumber.junit → net.serenitybdd.cucumber.util:

  • LiteralExpression
  • Utility methods from FeatureRunnerExtractors

Cucumber TestSourcesModel Independence

Created a Serenity-owned implementation of TestSourcesModel using Cucumber's public GherkinParser API, eliminating dependency on Cucumber's package-private internal class.

Benefits:

  • No longer dependent on Cucumber internals
  • Uses only public, stable Cucumber APIs
  • Reduces risk of breakage from Cucumber internal changes
  • Better separation of concerns

Enhanced Documentation

Added comprehensive migration documentation:

  • MIGRATION_5.0.0.md: Complete migration guide covering:

    • Breaking changes with before/after examples
    • Step-by-step JUnit 4 to JUnit 5 migration
    • Configuration parameter mapping reference
    • Parallel execution setup
    • Common issues and solutions

  • CUCUMBER_API_REQUIREMENTS.md: Technical documentation for Cucumber team explaining Serenity's API requirements (relevant for future Cucumber development)

Bug Fixes

Fixed screenshot viewer always opening at index 0 (#3685)

Resolved issue where the screenshot viewer in reports would always open at the first screenshot (index 0) regardless of which screenshot thumbnail was clicked.

Issue: #3685

Fixed report sorting by test outcome (#3700)

Fixed an issue where sorting test results by outcome (passed, failed, etc.) was not working correctly.

Issue: #3700

Dependency Updates

Updated Groovy for JDK 25 Compatibility

  • Groovy: 4.0.23 → 4.0.29
    • Adds support for JDK 25
    • Resolves "Unsupported class file major version 69" error

Technical Improvements

Internal Refactoring

  • Created CucumberInternalUtils class to replace package-private Cucumber utility methods with public API equivalents
  • Simplified duplicate utility code that was only 5-10 lines
  • Improved code maintainability and reduced coupling with Cucumber internals

Upgrade Notes

For All Users

Version Update: Update your pom.xml or build.gradle:

<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-core</artifactId>
    <version>5.0.0</version>
</dependency>

For JUnit 5 Cucumber Users (BREAKING CHANGE)

Required: Update plugin configuration in all test suite classes:

Find and Replace:

  • io.cucumber.core.plugin.SerenityReporter → net.serenitybdd.cucumber.core.plugin.SerenityReporter
  • io.cucumber.core.plugin.SerenityReporterParallel → net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel

Example:

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel"  // Updated path
)
public class CucumberTestSuite {}

For JUnit 4 Cucumber Users

No immediate action required, but plan for migration:

  1. JUnit 4 Cucumber support is deprecated and will be removed in version 6.0.0
  2. You will see deprecation warnings when compiling
  3. Tests will continue to work in version 5.x
  4. Review the migration guide and plan transition to JUnit 5

Migration Resources:

  • MIGRATION_5.0.0.md - Complete step-by-step guide
  • JUnit 5 offers better parallel execution and modern features
  • JUnit 5 has been stable since 2017

For Users with Custom Cucumber Plugins

If you have custom code that references moved classes, update package imports:

// OLD
import io.cucumber.core.plugin.FeatureFileLoader;
import io.cucumber.gherkin.ScenarioLineCountStatistics;

// NEW
import net.serenitybdd.cucumber.core.plugin.FeatureFileLoader;
import net.serenitybdd.cucumber.gherkin.ScenarioLineCountStatistics;

Known Issues

JUnit 4 Runners in Split Package

The JUnit 4 runners (CucumberSerenityRunner, CucumberSerenityBaseRunner) must remain in the io.cucumber.junit package to access package-private Cucumber classes. This creates a split package violation that will prevent JPMS compatibility when Cucumber migrates to Java 17+ modules.

Resolution: Migrate to JUnit 5 (see migration guide). JUnit 4 support will be removed in Serenity 6.0.0.

Migration Support

Resources

  1. Migration Guide: MIGRATION_5.0.0.md
  2. GitHub Discussions: serenity-bdd/serenity-core/discussions
  3. GitHub Issues: serenity-bdd/serenity-core/issues

Common Questions

Q: Do I need to update if I'm not using Cucumber? A: No, if you're not using Cucumber integration, this release has no breaking changes for you.

Q: Can I continue using JUnit 4 with Cucumber in 5.0.0? A: Yes, but it's deprecated. It will be removed in 6.0.0. We recommend migrating to JUnit 5.

Q: Will my existing tests break? A: Only if you're using JUnit 4 with Cucumber. You need to update the plugin path in your test suite configuration.

Q: How long do I have to migrate from JUnit 4? A: You have the entire 5.x release cycle (anywhere between 3 and 12 months) before JUnit 4 support is removed in 6.0.0.

Contributors

This release represents a significant architectural improvement to prepare Serenity BDD for the future of Java modules and evolving Cucumber integration requirements.

Special thanks to the Cucumber team for their collaboration on the API requirements discussion.

Full Changelog: https://github.com/serenity-bdd/serenity-core/compare/v4.3.4...v5.0.0