budaidev commented on code in PR #5067:
URL: https://github.com/apache/fineract/pull/5067#discussion_r2391405460
##########
fineract-doc/src/docs/en/chapters/testing/cucumber.adoc:
##########
@@ -1,6 +1,553 @@
[[testing-cucumber]]
-= Cucumber
+= Cucumber E2E Tests
-TBD
+Apache Fineract's E2E test suite provides comprehensive coverage of business
functionality using Cucumber BDD (Behavior-Driven Development) framework. These
tests serve as both functional validation and living documentation of the
system's capabilities.
+
+== Overview
+
+=== Architecture
+
+* *fineract-e2e-tests-runner*: Contains all Cucumber feature files and test
scenarios
+* *fineract-e2e-tests-core*: Contains step definitions, test utilities, and
supporting code
+* *Framework*: Cucumber with Java, using Gherkin syntax for readable test
specifications
+* *Prerequisites*: Running Apache Fineract instance (typically on port 8443
with HTTPS)
+
+=== Test Organization
+
+* Feature files located in:
`fineract-e2e-tests-runner/src/test/resources/features/`
+* Step definitions in:
`fineract-e2e-tests-core/src/test/java/org/apache/fineract/test/stepdef/`
+* Tests are tagged with TestRail IDs for traceability (e.g., `@TestRailId:C16`)
+* Special tags include `@Smoke` for quick validation tests
+
+== Prerequisites
+
+=== Required Software
+
+* *Java 21*: Apache Fineract requires Java 21 (Azul Zulu JDK recommended)
+* *Database*: MariaDB 11.5.2, PostgreSQL 17.4, or MySQL 9.1
+* *Git*: For source code management
+* *Gradle 8.14.3*: Included via wrapper
+
+=== Database Setup
+
+Before running E2E tests, ensure the databases are created:
+
+[source,bash]
+----
+# Create required databases
+./gradlew createDB -PdbName=fineract_tenants
+./gradlew createDB -PdbName=fineract_default
+----
+
+== Configuration
+
+=== Connection Configuration
+
+E2E tests connect to the running Fineract instance. Default configuration in
`fineract-e2e-tests-core/src/test/resources/fineract-test-application.properties`:
+
+[source,properties]
+----
+# Connection details to running backend
+fineract-test.api.base-url=${BASE_URL:https://localhost:8443}
+fineract-test.api.username=${TEST_USERNAME:mifos}
+fineract-test.api.password=${TEST_PASSWORD:password}
+fineract-test.api.tenant-id=${TEST_TENANT_ID:default}
+----
+
+To override defaults, use environment variables:
+
+[source,bash]
+----
+export BASE_URL=http://localhost:8080
+export TEST_USERNAME=mifos
+export TEST_PASSWORD=password
+export TEST_TENANT_ID=default
+----
+
+=== Test Data Initialization
+
+IMPORTANT: Many E2E tests require pre-configured test data (loan products,
charges, configurations). This initialization is controlled by the
`fineract-test.initialization.enabled` property.
+
+*Default Behavior*:
+
+* By default, initialization is *DISABLED*
(`fineract-test.initialization.enabled=false`)
+* Without initialization, tests will fail with errors like:
+
+[source]
+----
+java.lang.IllegalArgumentException: Loan product
[LP2_ADV_CUSTOM_PMT_ALLOC_PROGRESSIVE_LOAN_SCHEDULE_HORIZONTAL] not found
+----
+
+*How to Enable Initialization*:
+
+Method 1 - Environment Variable (Recommended):
+[source,bash]
+----
+cd fineract-e2e-tests-runner
+INITIALIZATION_ENABLED=true ../gradlew cucumber
+----
+
+Method 2 - System Property:
+[source,bash]
+----
+cd fineract-e2e-tests-runner
+../gradlew cucumber -DINITIALIZATION_ENABLED=true
+----
+
+Method 3 - Modify Properties File:
+Edit
`fineract-e2e-tests-core/src/test/resources/fineract-test-application.properties`:
+[source,properties]
+----
+fineract-test.initialization.enabled=true
+----
+
+*What Initialization Creates*:
+
+* 100+ loan products with specific configurations
+* Various charge types (NSF fees, processing fees, etc.)
+* Payment allocation rules
+* Interest calculation configurations
+* Advanced payment allocation strategies
+* Progressive loan schedule configurations
+
+*When to Use Initialization*:
+
+* First-time test execution on a fresh database
+* After database reset/recreation
+* When running tests that require specific loan products
+* Testing new features that depend on pre-configured products
+
+NOTE: Initialization takes additional time (2-5 minutes) as it creates
extensive test data. Consider running it once and reusing the database for
multiple test runs.
+
+=== Business Date Configuration
+
+CRITICAL: The Business Date feature must be enabled in the database for many
E2E tests to function correctly.
+
+*Default Behavior*:
+
+* Business Date is *DISABLED* by default in fresh Fineract installations
+* Without Business Date enabled, tests fail with:
+
+[source,json]
+----
+{"errors":[{
+ "defaultUserMessage":"Business date functionality is not enabled",
+ "developerMessage":"Business date functionality is not enabled",
+ "userMessageGlobalisationCode":"business.date.is.not.enabled"
+}]}
+----
+
+*How to Enable Business Date*:
+
+Method 1 - Via SQL (Direct Database):
+[source,bash]
+----
+mysql -u root -pmysql fineract_default -e \
+ "UPDATE c_configuration SET enabled = 1 WHERE name = 'enable-business-date';"
+----
+
+Method 2 - Via API (After Fineract is Running):
+[source,bash]
+----
+curl -X PUT
https://localhost:8443/fineract-provider/api/v1/configurations/name/enable-business-date
\
+ -H "Authorization: Basic bWlmb3M6cGFzc3dvcmQ=" \
+ -H "Content-Type: application/json" \
+ -d '{"enabled": true}'
+----
+
+*Verification*:
+[source,bash]
+----
+mysql -u root -pmysql fineract_default -e \
+ "SELECT * FROM c_configuration WHERE name LIKE '%business%';"
+----
+
+== Running E2E Tests
+
+=== Complete Workflow
+
+==== Step 1: Start Fineract
+
+[source,bash]
+----
+# Start Fineract in background
+./gradlew bootRun
+----
+
+Wait for Fineract to be fully started. You can verify by checking:
+[source,bash]
+----
+curl -k https://localhost:8443/actuator/health
+----
+
+==== Step 2: Enable Business Date (if needed)
+
+[source,bash]
+----
+mysql -u root -pmysql fineract_default -e \
+ "UPDATE c_configuration SET enabled = 1 WHERE name = 'enable-business-date';"
+----
+
+==== Step 3: Run E2E Tests
+
+Navigate to the E2E tests module:
+[source,bash]
+----
+cd fineract-e2e-tests-runner
+----
+
+*Run All E2E Tests*:
+[source,bash]
+----
+# First run with initialization
+INITIALIZATION_ENABLED=true ../gradlew cucumber
+
+# Subsequent runs without initialization (faster)
+../gradlew cucumber
+----
+
+*Run Specific Feature File*:
+[source,bash]
+----
+../gradlew cucumber
-Pcucumber.features="src/test/resources/features/Loan.feature"
+----
+
+*Run Tests by Tag*:
+[source,bash]
+----
+# Run only smoke tests
+../gradlew cucumber -Pcucumber.tags="@Smoke"
+
+# Run specific TestRail test
+../gradlew cucumber -Pcucumber.tags="@TestRailId:C16"
+
+# Run multiple tags
+../gradlew cucumber -Pcucumber.tags="@Smoke and @TestRailId:C16"
+----
+
+*Run Tests with Custom Configuration*:
+[source,bash]
+----
+BASE_URL=http://localhost:8080 \
+TEST_USERNAME=admin \
+TEST_PASSWORD=admin123 \
+INITIALIZATION_ENABLED=true \
+../gradlew cucumber
+----
+
+=== Gradle Command Options
+
+==== Basic Cucumber Task
+
+[source,bash]
+----
+../gradlew cucumber
+----
+
+==== Feature File Selection
+
+[source,bash]
+----
+# Single feature
+../gradlew cucumber
-Pcucumber.features="src/test/resources/features/Client.feature"
+
+# Multiple features
+../gradlew cucumber
-Pcucumber.features="src/test/resources/features/Client.feature:src/test/resources/features/Loan.feature"
+
+# Specific scenario by line number
+../gradlew cucumber
-Pcucumber.features="src/test/resources/features/Loan.feature:45"
+----
+
+==== Tag-Based Execution
+
+[source,bash]
+----
+# Single tag
+../gradlew cucumber -Pcucumber.tags="@Smoke"
+
+# Multiple tags (AND)
+../gradlew cucumber -Pcucumber.tags="@Smoke and @TestRailId:C16"
+
+# Multiple tags (OR)
+../gradlew cucumber -Pcucumber.tags="@Smoke or @TestRailId:C16"
+
+# Exclude tags
+../gradlew cucumber -Pcucumber.tags="not @ignore"
+
+# Complex tag expression
+../gradlew cucumber -Pcucumber.tags="@Smoke and not @ignore"
+----
+
+==== Report Generation
Review Comment:
added an allure section
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
