Skip to content

Feature: Named Parameter Support for External CSVs in Scenario DSLΒ #743

Closed

Description

@authorjapps

Background

Currently, Zerocode's scenario DSL supports index-based parameters for CSV-driven test cases. A more readable and maintainable enhancement is to support referencing external CSV headers as named parameters, allowing references like ${PARAM.columnName} in test scenarios. This feature is not yet available as of v1.3.46.

User Story

As a scenario author,
I want to reference CSV columns by their header names in external CSV files
So that my test steps are more readable, maintainable, and less error-prone


Acceptance Criteria

AC1: When a scenario DSL uses an external CSV as a data source and the CSV includes headers, each header becomes available as a named parameter via ${PARAM.headerName} in step fields (such as URL, request, or assertions).

AC2: Column values from the CSV rows SHALL be accessible via ${PARAM.headerName} syntax in:

  • Step URLs and paths (e.g., /users/${PARAM.username})
  • Request bodies (payload)
  • Field assertions and matchers

AC3: The parsing logic MUST automatically detect the first row as headers and create the named parameter mapping.

"ignoreHeader": true must NOT be set (i.e., headers must be enabled)

AC4: Referencing an invalid or missing header name via ${PARAM.someMissingHeader} must result in an explicit error message with details on valid headers.

AC5: Backward compatibility – index-based references and inline CSVs must continue to work unbroken.

AC6: Comprehensive documentation to be created with usage, and example scenarios comparing index-based and named-parameter CSVs.


DSL – Design Proposal with Workflow

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": {
      "ignoreHeader": false,
      "csvSource": "parameterized_csv/users.csv"
   }
}

DSL Enhancement

  • Named params ${PARAM.headerName} are available from external CSVs with a header row.
  • Inline arrays (with or without explicit column headers) retain existing ${0}, ${PARAM.NAME} referencing style (see below for contrast).
  • The test runner should throw a clear error if a referenced header in the scenario JSON/YAML is not present in the CSV.

Notes

  • Maintain consistency with existing inline array param logic (e.g., ${PARAM.USERID} style)
  • Keep named external CSV param usage optional and non-breaking
  • Do not break existing inline CSV
  • Also extend this feature to inline CSV to support header-based access when headers are provided

Examples

New (Support header-based access)

"parameterized": {
    "ignoreHeader": false,
    "csvSource":[
        "USERID, USERNAME, ADDRESS, USERNO, ISADMIN",
        "octocat, The Octocat, San Francisco, 583231, false",
        "siddhagalaxy, Sidd, UK, 33847730, false"
    ]
}

Existing (Still supported)

"parameterized": {
    "csvSource":[
        "|USERID|, |USERNAME|, |ADDRESS|, |USERNO|, |ISADMIN|",
        "octocat, The Octocat, San Francisco, 583231, false",
        "siddhagalaxy, Sidd, UK, 33847730, false"
    ]
}

Note

Clarification / Current Behavior

  • "ignoreHeader" controls whether the first CSV row is treated as headers.

  • By default, Zerocode-TDD treats the first row as data, not headers:

    • Default: "ignoreHeader": true
  • To enable ${PARAM.<headerName>} (e.g., ${PARAM.username}), users must explicitly set:

    • "ignoreHeader": false

Default Behavior

  • If not specified:

    • "ignoreHeader": true (header row is ignored)

Activity

  1. IgnatiosSar commented on Feb 22, 2026

    @IgnatiosSar
    Collaborator

    Hi @authorjapps,

    I am a student and I would like to contribute to this feature as part of a university project. I've reviewed the requirements (AC1-AC6) and the design proposal, and I find this enhancement very interesting and well-documented.
    Could you please assign this issue to me?

    Thank you!

  2. authorjapps commented on Feb 23, 2026

    @authorjapps
    OwnerAuthor

    Hi @authorjapps,

    I am a student and I would like to contribute to this feature as part of a university project. I've reviewed the requirements (AC1-AC6) and the design proposal, and I find this enhancement very interesting and well-documented. Could you please assign this issue to me?

    Thank you!

    @IgnatiosSar ,
    Done. Assigned.

    Can you please put high level implementation logic/pseudocode here, before implementing?
    (max 4 to 5 lines please just for everyone to have a visibility, keep it high level plan/approach, don't put too much details)
    Example: which all classes/methods you will change.
    Thanks for understanding 🀝 .

  3. singhshivansh244 commented on Mar 5, 2026

    @singhshivansh244

    Hi @authorjapps ,
    Is this issue still open? I would like to contribute to the project by working on this issue

  4. IgnatiosSar commented on Mar 5, 2026

    @IgnatiosSar
    Collaborator

    Hello again, @authorjapps
    Here is my proposed implementation logic:

    Parameterized class (domain): Add withHeaders field and areHeadersEnabled method to manage the inverse logic between withHeaders and ignoreHeader.

    Parameterized class (domain): Alignment Fix: Update ignoreHeader default to true (from false) to match issue requirements/notes.

    Parameterized class (domain): Update readCsvSourceFromExternalCsvFile to ensure the header row is preserved in the stream when headers are enabled.

    ZeroCodeParameterizedProcessorImpl class (preprocessor): Update resolveParamsCsv method to fetch the areHeadersEnabled() status and pass it to retrieveCsvHeaders method .

    ZeroCodeParameterizedProcessorImpl class (preprocessor): Modify retrieveCsvHeaders method to support standard headers when the flag is true, while maintaining full backward compatibility for the legacy pipe format (|header|).
    Should i proceed?

  5. authorjapps commented on Mar 6, 2026

    @authorjapps
    OwnerAuthor

    Hello again, @authorjapps Here is my proposed implementation logic:

    Parameterized class (domain): Add withHeaders field and areHeadersEnabled method to manage the inverse logic
    ...

    Thanks @IgnatiosSar , please proceed.
    Also, will you be taking care of the bellow as well?

    From the Issue Summary:

    Naming / UX / Ease-of-Usage suggestion

    Introducing "withHeaders": true is more intuitive for users who want to reference CSV headers, but it should behave exactly the same as "ignoreHeader": false.
    If neither option is provided, the default should be treated as:
    "withHeaders": false (equivalently, "ignoreHeader": true)

  6. IgnatiosSar commented on Mar 6, 2026

    @IgnatiosSar
    Collaborator

    @authorjapps Yes, absolutely. I will update the default values and make sure that areHeadersEnabled method handles the inverse logic, so "withHeaders" and "ignoreHeaders" behave the same.

  7. Sakshui commented on Mar 17, 2026

    @Sakshui

    Hi @authorjapps

    I would love to work on this issue. It seems like a good opportunity for me to understand the project and contribute. If no one else is currently working on it, could you please assign it to me?

    Thanks!

  8. IgnatiosSar commented on Mar 17, 2026

    @IgnatiosSar
    Collaborator

    Hello, @authorjapps
    While working on the issue, I identified a logic gap between the existing ignoreHeader functionality and the proposed withHeaders attribute.
    Currently, ignoreHeader defaults to false (which differs from what is stated in the Notes of the issue). If we treat withHeaders as a strictly inverse equivalent pair, we run into issues with the default behavior:

    Scenario A: We keep the old defaults (withHeaders would default to true).
    Issue Example:

    octocat,The Octocat,San Francisco,583231
    siddhagalaxy,Sidd,UK,33847730
    

    In this example because the default for the ignoreHeader is false we will not skip the first line but later on, because withHeaders is True, it will treat the first line as a header and filter it out.

    Scenario B: We change the defaults to match the ones in the Notes ("withHeaders": false (equivalently, "ignoreHeader": true))
    Issue Example:

    "parameterized": {
            "csvSource":[
                "|USERID|,     |USERNAME|,  |ADDRESS|,     |USERNO|,        |ISADMIN|",
                "octocat,      The Octocat, San Francisco, 583231,          false",
                "siddhagalaxy, Sidd,        UK,            33847730,        false"
            ]
        }
    

    In this case, because ignoreHeader is now true, the first row (the headers) will be skipped entirely, making it impossible to reference them.

    Scenario C: We change the defaults and we don't skip the first line of the CSV in the Parameterized class if ignoreHeader is true (the header row is also checked in the ZeroCodeParameterizedProcessorImpl class, so it could be a possible solution).

    In this scenario the main issue is that we break existing unit tests in the Parameterized class.

    My suggestion is not to treat withHeaders and ignoreHeader as strictly inverse/equivalent pairs.
    ignoreHeader: Indicates the intent to skip the first line during processing. Default: false.
    withHeaders: Indicates that the CSV source contains a header row (whether it uses the |PIPES| syntax or not). Default: false
    This way, if a user wants to indicate that his CSV contains headers he can by either using the pipes (old method), or by using withHeaders: True (with or without the pipes).

  9. authorjapps commented on Mar 18, 2026

    @authorjapps
    OwnerAuthor

    ...withHeaders...

    Looks like you're proposing not to implement or support "withHeaders" at all.
    This way we can use the existing "ignoreHeader" feature and that makes everything easy.

    Sounds good to me and logical. πŸ‘

    I agree, it may create confusion and maintaining two inverse properties will be nightmare. Let's not go that way.

    Please proceed with "ignoreHeader" only πŸš€

    ( removed the "withHeaders" lines from the Issue description)

  10. IgnatiosSar commented on Mar 29, 2026

    @IgnatiosSar
    Collaborator

    @authorjapps
    Alright, i will proceed with "IgnoreHeader" only. The main issue is that "ignoreHeader" in the existing code, defaults to False and its only job is to filter out the first row (when it's True) using .skip(1) in the Parameterized class. Do you want me to modify "ignoreHeader" so its job is to control whether the first CSV row is treated as headers and defaults to True?

  11. authorjapps commented on Mar 30, 2026

    @authorjapps
    OwnerAuthor

    @authorjapps Alright, i will proceed with "IgnoreHeader" only...

    Thanks

    Do you want me to modify "ignoreHeader" so its job is to control whether the first CSV row is treated as headers

    Do you mean rename it to something more meaningful? Please suggest the new name here.

  12. 3 remaining items

  13. authorjapps commented on Mar 31, 2026

    @authorjapps
    OwnerAuthor

    @IgnatiosSar , thanks for explaining.
    Understood your thoughts, sounds great actually.
    However I've got a suggestion on the similar lines of yours:

    • We should keep only flag, that's "withHeaders"
    • Rename the "ignoreHeader" -> "withHeaders"
    • Make default value as false. So when someone wants to use ||, they will explicitly set withHeaders=true. This will be the only major breaking change. So we can give notice for 2 weeks for users to migrate to 'withHeaders', later merge the PR.
    • Anywhere else(e.g. reading from a external CSV file etc), users will control via setting true or false . Default/absence will be treated as false as discussed.
    • Anywhere else for users, then can search and replace and inverse the value. But there won't be many occurances

    Let me know if you're fine or see any problems, and you're happy to go ahead ?

    Breaking change fix example:

    "parameterized": {
            "withHeaders": true, <----- That's it
            "csvSource":[
                "|USERID|,     |USERNAME|,  |ADDRESS|,     |USERNO|,        |ISADMIN|",
                "octocat,      The Octocat, San Francisco, 583231,          false",
                "siddhagalaxy, Sidd,        UK,            33847730,        false"
            ]
        }

    Other places to fix(if any):

    "ignoreHeader": true --> Remove this line
    
    and
    
    "ignoreHeader": false ---> Replace with "withHeaders": true
    
    
  14. IgnatiosSar commented on Mar 31, 2026

    @IgnatiosSar
    Collaborator

    @authorjapps
    That's great and I'm happy to work on that. I just have 2 more questions.

    1. If withHeaders=false (or absent) should we treat all CSV as data, to allow users to have a CSV with no headers (only data)?
      For example
    "parameterized": {
            "csvSource":[
                "octocat,      The Octocat, San Francisco, 583231,          false",
                "siddhagalaxy, Sidd,        UK,            33847730,        false"
            ]
        }
    
    1. Should we consider, treating the first row as headers even if it doesn't have || in the headers?
      This way we still allow this
      2.1)
    "parameterized": {
            "withHeaders": true, 
            "csvSource":[
                "|USERID|,     |USERNAME|,  |ADDRESS|,     |USERNO|,        |ISADMIN|",
                "octocat,      The Octocat, San Francisco, 583231,          false",
                "siddhagalaxy, Sidd,        UK,            33847730,        false"
            ]
        }
    

    2.2)
    But, we also allow this

    "parameterized": {
            "withHeaders": true, 
            "csvSource":[
                "USERID,     USERNAME,  ADDRESS,     USERNO,        ISADMIN",
                "octocat,      The Octocat, San Francisco, 583231,          false",
                "siddhagalaxy, Sidd,        UK,            33847730,        false"
            ]
        }
    

    By doing this, we maintain backward compatibility for existing users and make it easier for users to write new scenarios.
    What do you think?

  15. authorjapps commented on Mar 31, 2026

    @authorjapps
    OwnerAuthor

    @IgnatiosSar, great questions and good catches! πŸ‘
    Here are a few things worth considering as we trying to make things simpler:

    • No. 1 : Yes
    • No. 2 : Once you implement No. 2.2, then No. 2.1 will be redundant(no very useful). Later(or in the same PR) you can get rid of(delete/remove) the code supporting || (piped headers).

    This way the feature becomes simpler to use and consistent across test scenarios.

  16. IgnatiosSar commented on Mar 31, 2026

    @IgnatiosSar
    Collaborator

    @authorjapps
    Thank you! I completely agree with your goal to make the feature simpler and more consistent.

    To achieve this without immediately breaking existing tests that rely on the || (piped) syntax, what do you think about taking a deprecation approach?

    For this PR: I will implement No. 2.2 (standard headers) so users can start using them. I will leave the || logic intact for now, but we can officially mark it as deprecated in the documentation (and code).

    For a future release: We can safely remove the || support entirely, giving users time to update their tests.

    How does this sound to you?

  17. authorjapps commented on Mar 31, 2026

    @authorjapps
    OwnerAuthor

    I will leave the || logic intact for now...

    For a future release: We can safely remove the || support entirely, giving users time to update their tests.

    Yep, this sounds much safer. Please go ahead .

    In the log, clearly print something like this(or better) with WARN level:
    "Stop using the deprecated feature || in the header and start using withHeaders field instead. Visit documentation."

  18. IgnatiosSar commented on Apr 6, 2026

    @IgnatiosSar
    Collaborator

    Hello, @authorjapps
    My implementation is ready, but before submitting the PR for review I wanted to check in on two things.

    1. Regarding the 2-week notice for replacing ignoreHeader with withHeaders, should I submit my PR now for review, so you can create the notice and merge it later on?
    2. Do you want me to include examples in my PR, so you can add them in the documentation?
      Let me know!
  19. authorjapps commented on Apr 6, 2026

    @authorjapps
    OwnerAuthor

    @IgnatiosSar , thanks for the update. Great news !

    1. Yes, I'm happy to create the notice
    2. Yes please. This will be very helpful to the existing users during migration.
  20. authorjapps commented on Apr 12, 2026

    @authorjapps
    OwnerAuthor

    Notice created here, will add to landing page soon:

    @IgnatiosSar , Feel free to amend anything or add any examples if you find useful

  21. IgnatiosSar commented on Apr 13, 2026

    @IgnatiosSar
    Collaborator

    @authorjapps Just to clarify two points regarding my PR:

    1. Syntax Changes & Deprecation

    In the PR, I have completely removed ignoreHeader. The deprecation applies specifically to the piped syntax for headers. Here is how it works now:
    ❌ Will NOT work anymore (Removed):

    "parameterized": {
        "ignoreHeader": true, 
        "csvSource":[
            "USERID,     USERNAME,    ADDRESS,       USERNO,        ISADMIN",
            "octocat,    The Octocat, San Francisco, 583231,        false"
        ]
    }

    ⚠️ Deprecated (Will work, but not recommended): Using the piped | | syntax.

    "parameterized": {
        "withHeaders": true, 
        "csvSource":[
            "|USERID|,   |USERNAME|,  |ADDRESS|,     |USERNO|,      |ISADMIN|",
            "octocat,    The Octocat, San Francisco, 583231,        false"
        ]
    }

    βœ… The New Standard (The easy way):

    "parameterized": {
        "withHeaders": true, 
        "csvSource":[
            "USERID,     USERNAME,    ADDRESS,       USERNO,        ISADMIN",
            "octocat,    The Octocat, San Francisco, 583231,        false"
        ]
    }

    2. Migration Path

    Previously, if a CSV had headers without the | | syntax, users had to use ignoreHeader: true just to skip the first line. Now, they simply need to replace ignoreHeader: true with withHeaders: true.
    For example:
    The current tests look like this (unable to reference headers)

    "parameterized": {
        "ignoreHeader": true, 
        "csvSource":[
            "USERID,     USERNAME,    ADDRESS,       USERNO,        ISADMIN",
            "octocat,    The Octocat, San Francisco, 583231,        false"
        ]
    }

    After the PR is merged they should look like this (able to reference headers)

    "parameterized": {
        "withHeaders": true, 
        "csvSource":[
            "USERID,     USERNAME,    ADDRESS,       USERNO,        ISADMIN",
            "octocat,    The Octocat, San Francisco, 583231,        false"
        ]
    }
  22. authorjapps commented on Apr 13, 2026

    @authorjapps
    OwnerAuthor

    @authorjapps Just to clarify two points regarding my PR:

    got you @IgnatiosSar . Only the notice instruction will change in this Wiki page, not a problem.
    Fee free to update here (do not update the subject line/page-title as this is referenced from other pages).

  23. IgnatiosSar commented on Apr 14, 2026

    @IgnatiosSar
    Collaborator

    Fee free to update here (do not update the subject line/page-title as this is referenced from other pages).

    @authorjapps Thanks for the heads-up! It seems I don't have the "Edit" button on my end, likely because Wiki edits are restricted to repository collaborators by default.
    Since you'll have to make the update, could we make sure to clearly state that ignoreHeader is being completely removed with this PR? The deprecation only applies to the | | piped syntax.

    Adding the 'Before/After' examples I provided in my previous comment would be a great way to make this distinction clear for the users.

  24. authorjapps commented on Apr 14, 2026

    @authorjapps
    OwnerAuthor

    @IgnatiosSar , added you now. Once you accept here you'll have edit permission. Let me know how it goes.
    (I can, but I may miss some points again, it's better you do it so)
    I created the template, so it's easy now for you to add/amend the content :)

  25. IgnatiosSar commented on Apr 15, 2026

    @IgnatiosSar
    Collaborator

    @authorjapps Thank you for the template, it was really helpful! I just finished and saved my changes. The migration guide now covers all possible cases and explains the changes in detail. I also added examples for clarity. Let me know what you think!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions