ISSUE-743 # Support external CSV header referencing and add withHeaders

[IgnatiosSar]

Support external CSV header referencing and replace ignoreHeader with withHeaders

Fixed Which Issue?

• Which issue or ticket was(will be) fixed by this PR? (capture the issue link here)
  Fixes Feature: Named Parameter Support for External CSVs in Scenario DSL #743
  PR Branch
  https://github.com/IgnatiosSar/zerocode/tree/feature/743

Motivation and Context

This PR addresses Issue #743 by introducing native support for CSV headers in parameterized tests, enabling referencing those headers using ${PARAM.columnName} syntax and replacing the old ignoreHeader logic.

About the issue & Error Handling:
I discovered that referencing headers in external CSVs was already partially implemented, so I created the required tests to prove and ensure that it works. To make it robust, I added a regex validation. If a user tries to reference a header that doesn't exist in the CSV file, it now throws a clear RuntimeException explicitly listing the invalid column and the available valid headers.

Replacing ignoreHeader with withHeaders:

• I added the withHeaders field, which completely replaces and removes ignoreHeader. (Note: This is a breaking change for existing users using the old flag).
• If the CSV that the user is using in their scenario (either internal or external) has headers, they should explicitly declare it by adding "withHeaders": true. The absence of this flag means that the CSV only contains raw data.
• Additionally, withHeaders currently supports both piped (| |) and standard header syntax (no pipes), but the piped syntax is deprecated and should be removed in later versions.

Testing:
For everything I’ve changed, I created or fixed the corresponding unit and integration tests to prove and ensure that the feature works. I also fixed some other tests that broke due to these changes (e.g., the removal of ignoreHeader).

Checklist:

• 1. New Unit tests were added

  • 1.1 Covered in existing Unit tests

• 2. Integration tests were added

  • 2.1 Covered in existing Integration tests

• 3. Test names are meaningful

• 3.1 Feature manually tested and outcome is successful

• 4. PR doesn't break any of the earlier features for end users

  • 4.1 WARNING! This might break one or more earlier earlier features, hence left a comment tagging all reviewrs.
    Note: As agreed, the old ignoreHeader field has been removed and replaced by withHeaders. Existing user scenarios using the old flag will need to be updated.

• 5. PR doesn't break the HTML report features directly

  • 5.1 Yes! I've manually run it locally and seen the HTML reports are generated perfectly fine
  • 5.2 Yes! I've opened the generated HTML reports from the /target folder and they look fine

• 6. PR doesn't break any HTML report features indirectly

  • 6.1 I have not added or amended any dependencies in this PR
  • 6.2 I have double checked, the new dependency added or removed has not affected the report generation indirectly
  • 6.3 Yes! I've seen the Sample report screenshots here, and HTML report of the current PR looks simillar.

• 7. Branch build passed in CI

• 8. No 'package.*' in the imports

• 9. Relevant Documentation page added or updated with clear instructions and examples for the end user

  • 9.1 Not applicable. This was only a code refactor change, no functional or behaviourial changes were introduced

• 10. Http test added to http-testing-examples module(if applicable) ?

  • 10.1 Not applicable. The changes did not affect HTTP automation flow

• 11. Kafka test added to kafka-testing-examples module(if applicable) ?

  • 11.1 Not applicable. The changes did not affect Kafka automation flow

  Documentation

  CSV Headers

  If a CSV has headers, you must explicitly set withHeaders:true in the parameterized section.

Example

    "parameterized": {
        "withHeaders": true,
        "csvSource": [
        "userId, userName",
        "1,      octocat",
        "2,      googlebot"
        ]
    }

Referencing Headers in external CSVs

You can reference external CSV columns by their header names in your scenarios using ${PARAM.columnName}.

Example: External CSV users.csv

username,fullname,location,userid
octocat,The Octocat,San Francisco,583231
foo,Foo Is My Name,Bar City,112233

Sample Scenario DSL

{
   "scenarioName": "Test with named CSV parameters",
   "steps": [
      {
         "name": "get_user_details",
         "url": "/users/${PARAM.username}",
         "operation": "GET",
         "request": {},
         "assertions": {
            "status": 200,
            "body": {
               "login": "${PARAM.username}",
               "name": "${PARAM.fullname}",
               "location": "${PARAM.location}",
               "id": "(int)${PARAM.userid}"
            }
         }
      }
   ],
   "parameterized": {
      "withHeaders": true,
      "csvSource": "parameterized_csv/users.csv"
   }
}

Important Notes for the documentation

1. withHeaders:true should also be added in any other test that is using CSV with headers as an example
2. ignoreHeader should be removed from any existing documentation
3. Piped syntax for headers (| |) should be stated as deprecated in the documentation

[IgnatiosSar]

Hello, @authorjapps
Just a heads-up regarding the breaking change.
As discussed in Issue #743, I have completely removed the ignoreHeader field and replaced it with withHeaders.
Users should be noticed, so those who use ignoreHeader can migrate to withHeaders. Also, users who use CSV with headers (even in the existing tests with | | syntax for headers) should explicitly set withHeaders:true.
Tagging you for visibility on these changes!

[authorjapps]

👍

[authorjapps]

👍

[authorjapps]

Once this PR is merged, also merge the next PR #756 with notice.