fix(requirements): RootDirectory honours serenity.test.requirements.basedir (#3733)

[GianniGiglio]

Summary

Adds a fallback in RootDirectory.featuresOrStoriesRootDirectory() so it honours serenity.test.requirements.basedir when serenity.requirements.dir is unset. This makes the existing serenity-gradle-plugin AggregateTask wiring work for multi-module Gradle builds without asking callers to configure the same path under two property names.

Fixes #3733.

Intended effect

For a multi-module Gradle project that puts its feature tree in a sub-module (e.g. <module>/src/main/resources/features/) and configures:

serenity {
    requirementsBaseDir = file("src/main/resources/features").absolutePath
    outputDirectory = "build/site/report"
}

…running ./gradlew :<module>:aggregate will now load the full requirements tree and emit the usual hierarchical HTML pages (requirement_type_theme.html, requirement_type_capability.html, requirement_type_feature.html, theme_*.html, capability_*.html) plus any narratives from per-directory narrative.md files.

Before this change, the same setup yielded a flat capabilities.html with no hierarchy and no narratives, while the aggregate log simultaneously reported "Generating test results for 47 tests" and "0 requirements loaded" — because FileSystemRequirementsTagProvider's no-arg constructor fell back to user.dir + "/src/test/resources/features" (the root project during :module:aggregate, not the sub-module). Full analysis in #3733.

How this was manually tested

On the affected downstream project:

./gradlew :<module>:aggregate --rerun-tasks --debug

Before the fix, the aggregate log shows:

0 requirements loaded after 335 ms

After the fix (with SERENITY_TEST_REQUIREMENTS_BASEDIR set by the Gradle plugin, which is already the default wiring):

54 requirements loaded after 210 ms

and the report output directory gains ~20 additional HTML files corresponding to the three requirement types and every theme/capability under the feature tree, plus rendered narratives from narrative.md.

Equivalent confirmation by setting -Dserenity.requirements.dir=<abs path> on the aggregate task on the unpatched build — same outcome — isolates the path resolution as the sole cause.

Tests

serenity-model/src/test/java/net/thucydides/model/requirements/WhenFindingTheRootDirectoryForFeatureFiles.java gains three cases, all passing:

• featuresOrStoriesRootDirectoryFallsBackToTestRequirementsBasedir — the new fallback fires when only serenity.test.requirements.basedir is set and the path exists.
• serenityRequirementsDirTakesPrecedenceOverBasedir — guards the existing contract: when both properties are set, serenity.requirements.dir still wins.
• basedirFallbackIgnoresNonExistentPaths — stale basedir values do not leak a non-existent path to callers; the classpath/working-directory scan fallback is retained.

Local run: ./mvnw -pl serenity-model -Dtest='WhenFindingTheRootDirectoryForFeatureFiles' -Dsurefire.failIfNoSpecifiedTests=false test → Tests run: 5, Failures: 0, Errors: 0, Skipped: 0.

Side effects

None expected.

• When serenity.requirements.dir is set, behaviour is unchanged (the new branch is unreachable).
• When neither property is set, behaviour is unchanged (the existing classpath/working-directory scan still runs).
• When only serenity.test.requirements.basedir is set and points at a directory that does not exist, the fallback is skipped and behaviour again matches the pre-patch code path.

The only observable change is the case the bug report targets: only serenity.test.requirements.basedir is set and points at a real directory. Previously that configuration quietly resolved to the wrong path; now it resolves correctly.

Documentation changes

No changes required. serenity.test.requirements.basedir is already documented as the companion of the Gradle plugin's requirementsBaseDir DSL field; this PR makes the runtime behaviour match that documented expectation.

Relevant tickets

• Fixes Aggregate drops the requirement hierarchy in multi-module Gradle builds (FileSystem + TestOutcome providers read the wrong directory) #3733

Checklist

• Tests added (WhenFindingTheRootDirectoryForFeatureFiles, 3 new cases)
• ./mvnw -pl serenity-model test passes locally
• git diff --check clean
• Commit message follows the <type>: <message> convention