docs: Document @nested class annotation inheritance for requirements hierarchy

Add documentation for inheriting @Epic/@Feature/@story annotations from
enclosing classes in JUnit 5 @nested tests, including examples of full
three-level hierarchies, annotation overriding, and @DisplayName fallback.

Updated in English, Spanish (es), and Brazilian Portuguese (pt-BR).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: wakaleo

docs/guide/annotation-requirements.md

@@ -282,6 +282,117 @@ abstract class BaseTest { }
 class SpecificTest extends BaseTest { }
 ```
 
+## Inheriting Annotations in JUnit 5 @Nested Classes
+
+When using JUnit 5 `@Nested` inner classes, annotations on the enclosing (outer) class are inherited by the nested class. This is a natural way to define the feature or epic once on the outer class and then define individual stories in each nested class:
+
+```java
+@ExtendWith(SerenityJUnit5Extension.class)
+@Feature("Product Catalog")
+class ProductCatalogTests {
+
+    @Nested
+    @Story("Searching by keyword")
+    class WhenSearchingByKeyword {
+
+        @Test
+        void shouldFindProductsByName() { /* ... */ }
+
+        @Test
+        void shouldReturnEmptyResultsForUnknownKeyword() { /* ... */ }
+    }
+
+    @Nested
+    @Story("Browsing by category")
+    class WhenBrowsingByCategory {
+
+        @Test
+        void shouldListProductsInCategory() { /* ... */ }
+    }
+}
+```
+
+This produces the following hierarchy in the requirements report:
+
+```
+Product Catalog (feature)
+├── Searching by keyword (story)
+│   ├── Should find products by name
+│   └── Should return empty results for unknown keyword
+└── Browsing by category (story)
+    └── Should list products in category
+```
+
+### Full Three-Level Hierarchy with Nested Classes
+
+You can combine `@Epic` and `@Feature` on the outer class with `@Story` on nested classes for the full hierarchy:
+
+```java
+@ExtendWith(SerenityJUnit5Extension.class)
+@Epic("E-Commerce Platform")
+@Feature("Shopping Cart")
+class ShoppingCartTests {
+
+    @Nested
+    @Story("Add item to cart")
+    class WhenAddingItems {
+        @Test
+        void shouldAddSingleItem() { /* ... */ }
+    }
+
+    @Nested
+    @Story("Remove item from cart")
+    class WhenRemovingItems {
+        @Test
+        void shouldRemoveSelectedItem() { /* ... */ }
+    }
+}
+```
+
+This produces:
+
+```
+E-Commerce Platform (epic)
+└── Shopping Cart (feature)
+    ├── Add item to cart (story)
+    │   └── Should add single item
+    └── Remove item from cart (story)
+        └── Should remove selected item
+```
+
+### Overriding Annotations in Nested Classes
+
+If a nested class redefines an annotation that is already present on the outer class, the nested class annotation takes precedence:
+
+```java
+@Feature("Product Catalog")
+class ProductTests {
+
+    @Nested
+    @Feature("Checkout")  // Overrides "Product Catalog"
+    @Story("Express checkout")
+    class WhenUsingExpressCheckout { /* ... */ }
+}
+```
+
+### Using @DisplayName as Story Name in Nested Classes
+
+When a nested class has no `@Story` annotation, its `@DisplayName` is used as the story name, just as it is for top-level classes:
+
+```java
+@Feature("Product Catalog")
+class ProductCatalogTests {
+
+    @Nested
+    @DisplayName("Searching by keyword")  // Used as the story name
+    class WhenSearchingByKeyword { /* ... */ }
+}
+```
+
+:::tip Nested classes vs separate test classes
+Use `@Nested` classes when you want to group related stories under a single outer class and share setup code. Use separate top-level test classes when the stories are more independent. Both approaches produce the same requirements hierarchy in the reports.
+:::
+
 ## Annotations vs Package-Based Requirements
 
 Annotation-based requirements **override** the default package-based hierarchy for the annotated test class. This means you can mix both approaches in the same project:

docs/junit5/junit5-tests.md

@@ -381,6 +381,43 @@ class AuthenticationTests {
 }
 ```
 
+#### Nested Classes and Requirements Annotations
+
+`@Nested` classes inherit `@Epic`, `@Feature`, and `@Story` annotations from their enclosing class. This lets you define the feature once on the outer class and assign individual stories to each nested class:
+
+```java
+@ExtendWith(SerenityJUnit5Extension.class)
+@Feature("User Authentication")
+class AuthenticationTests {
+
+    @Nested
+    @Story("Login")
+    class WhenLoggingIn {
+        @Test
+        void shouldSucceedWithValidCredentials() { /* ... */ }
+    }
+
+    @Nested
+    @Story("Logout")
+    class WhenLoggingOut {
+        @Test
+        void shouldClearSession() { /* ... */ }
+    }
+}
+```
+
+This produces the requirements hierarchy:
+
+```
+User Authentication (feature)
+├── Login (story)
+│   └── Should succeed with valid credentials
+└── Logout (story)
+    └── Should clear session
+```
+
+See [Annotation-Based Requirements](/docs/guide/annotation-requirements#inheriting-annotations-in-junit-5-nested-classes) for the full details on annotation inheritance with nested classes.
+
 ## Parameterized Tests
 
 ### Simple Parameterized Tests

i18n/es/docusaurus-plugin-content-docs/current/guide/annotation-requirements.md

@@ -282,6 +282,117 @@ abstract class BaseTest { }
 class SpecificTest extends BaseTest { }
 ```
 
+## Heredando Anotaciones en Clases @Nested de JUnit 5
+
+Al usar clases internas `@Nested` de JUnit 5, las anotaciones de la clase contenedora (externa) son heredadas por la clase anidada. Esta es una forma natural de definir la funcionalidad o épica una sola vez en la clase externa y luego definir historias individuales en cada clase anidada:
+
+```java
+@ExtendWith(SerenityJUnit5Extension.class)
+@Feature("Product Catalog")
+class ProductCatalogTests {
+
+    @Nested
+    @Story("Searching by keyword")
+    class WhenSearchingByKeyword {
+
+        @Test
+        void shouldFindProductsByName() { /* ... */ }
+
+        @Test
+        void shouldReturnEmptyResultsForUnknownKeyword() { /* ... */ }
+    }
+
+    @Nested
+    @Story("Browsing by category")
+    class WhenBrowsingByCategory {
+
+        @Test
+        void shouldListProductsInCategory() { /* ... */ }
+    }
+}
+```
+
+Esto produce la siguiente jerarquía en el informe de requisitos:
+
+```
+Product Catalog (feature)
+├── Searching by keyword (story)
+│   ├── Should find products by name
+│   └── Should return empty results for unknown keyword
+└── Browsing by category (story)
+    └── Should list products in category
+```
+
+### Jerarquía Completa de Tres Niveles con Clases Anidadas
+
+Puedes combinar `@Epic` y `@Feature` en la clase externa con `@Story` en las clases anidadas para la jerarquía completa:
+
+```java
+@ExtendWith(SerenityJUnit5Extension.class)
+@Epic("E-Commerce Platform")
+@Feature("Shopping Cart")
+class ShoppingCartTests {
+
+    @Nested
+    @Story("Add item to cart")
+    class WhenAddingItems {
+        @Test
+        void shouldAddSingleItem() { /* ... */ }
+    }
+
+    @Nested
+    @Story("Remove item from cart")
+    class WhenRemovingItems {
+        @Test
+        void shouldRemoveSelectedItem() { /* ... */ }
+    }
+}
+```
+
+Esto produce:
+
+```
+E-Commerce Platform (epic)
+└── Shopping Cart (feature)
+    ├── Add item to cart (story)
+    │   └── Should add single item
+    └── Remove item from cart (story)
+        └── Should remove selected item
+```
+
+### Sobrescribiendo Anotaciones en Clases Anidadas
+
+Si una clase anidada redefine una anotación que ya está presente en la clase externa, la anotación de la clase anidada tiene prioridad:
+
+```java
+@Feature("Product Catalog")
+class ProductTests {
+
+    @Nested
+    @Feature("Checkout")  // Sobrescribe "Product Catalog"
+    @Story("Express checkout")
+    class WhenUsingExpressCheckout { /* ... */ }
+}
+```
+
+### Usando @DisplayName como Nombre de Historia en Clases Anidadas
+
+Cuando una clase anidada no tiene anotación `@Story`, su `@DisplayName` se usa como nombre de historia, igual que para las clases de nivel superior:
+
+```java
+@Feature("Product Catalog")
+class ProductCatalogTests {
+
+    @Nested
+    @DisplayName("Searching by keyword")  // Se usa como nombre de historia
+    class WhenSearchingByKeyword { /* ... */ }
+}
+```
+
+:::tip Clases anidadas vs clases de prueba separadas
+Usa clases `@Nested` cuando quieras agrupar historias relacionadas bajo una sola clase externa y compartir código de configuración. Usa clases de prueba separadas de nivel superior cuando las historias sean más independientes. Ambos enfoques producen la misma jerarquía de requisitos en los informes.
+:::
+
 ## Anotaciones vs Requisitos Basados en Paquetes
 
 Los requisitos basados en anotaciones **sobrescriben** la jerarquía basada en paquetes por defecto para la clase de prueba anotada. Esto significa que puedes mezclar ambos enfoques en el mismo proyecto:

i18n/es/docusaurus-plugin-content-docs/current/junit5/junit5-tests.md

@@ -381,6 +381,43 @@ class AuthenticationTests {
 }
 ```
 
+#### Clases Anidadas y Anotaciones de Requisitos
+
+Las clases `@Nested` heredan las anotaciones `@Epic`, `@Feature` y `@Story` de su clase contenedora. Esto te permite definir la funcionalidad una vez en la clase externa y asignar historias individuales a cada clase anidada:
+
+```java
+@ExtendWith(SerenityJUnit5Extension.class)
+@Feature("User Authentication")
+class AuthenticationTests {
+
+    @Nested
+    @Story("Login")
+    class WhenLoggingIn {
+        @Test
+        void shouldSucceedWithValidCredentials() { /* ... */ }
+    }
+
+    @Nested
+    @Story("Logout")
+    class WhenLoggingOut {
+        @Test
+        void shouldClearSession() { /* ... */ }
+    }
+}
+```
+
+Esto produce la jerarquía de requisitos:
+
+```
+User Authentication (feature)
+├── Login (story)
+│   └── Should succeed with valid credentials
+└── Logout (story)
+    └── Should clear session
+```
+
+Consulta [Requisitos Basados en Anotaciones](/docs/guide/annotation-requirements#heredando-anotaciones-en-clases-nested-de-junit-5) para los detalles completos sobre la herencia de anotaciones con clases anidadas.
+
 ## Pruebas parametrizadas
 
 ### Pruebas parametrizadas simples