Repository navigation
Description
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": truemust 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,112233Sample 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
- Default:
-
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
IgnatiosSar commentedon Feb 22, 2026
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!
authorjapps commentedon Feb 23, 2026
@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 π€ .
singhshivansh244 commentedon Mar 5, 2026
Hi @authorjapps ,
Is this issue still open? I would like to contribute to the project by working on this issue
IgnatiosSar commentedon Mar 5, 2026
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?
authorjapps commentedon Mar 6, 2026
Thanks @IgnatiosSar , please proceed.
Also, will you be taking care of the bellow as well?
IgnatiosSar commentedon Mar 6, 2026
@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.
Sakshui commentedon Mar 17, 2026
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!
IgnatiosSar commentedon Mar 17, 2026
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:
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:
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).
authorjapps commentedon Mar 18, 2026
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)
IgnatiosSar commentedon Mar 29, 2026
@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?
authorjapps commentedon Mar 30, 2026
Thanks
Do you mean rename it to something more meaningful? Please suggest the new name here.
3 remaining items
authorjapps commentedon Mar 31, 2026
@IgnatiosSar , thanks for explaining.
Understood your thoughts, sounds great actually.
However I've got a suggestion on the similar lines of yours:
false. So when someone wants to use ||, they will explicitly setwithHeaders=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.trueorfalse. Default/absence will be treated as false as discussed.Let me know if you're fine or see any problems, and you're happy to go ahead ?
Breaking change fix example:
Other places to fix(if any):
IgnatiosSar commentedon Mar 31, 2026
@authorjapps
That's great and I'm happy to work on that. I just have 2 more questions.
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
This way we still allow this
2.1)
2.2)
But, we also allow this
By doing this, we maintain backward compatibility for existing users and make it easier for users to write new scenarios.
What do you think?
authorjapps commentedon Mar 31, 2026
@IgnatiosSar, great questions and good catches! π
Here are a few things worth considering as we trying to make things simpler:
No. 2.2, thenNo. 2.1will 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.
IgnatiosSar commentedon Mar 31, 2026
@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?
authorjapps commentedon Mar 31, 2026
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 usingwithHeadersfield instead. Visit documentation."IgnatiosSar commentedon Apr 6, 2026
Hello, @authorjapps
My implementation is ready, but before submitting the PR for review I wanted to check in on two things.
ignoreHeaderwithwithHeaders, should I submit my PR now for review, so you can create the notice and merge it later on?Let me know!
authorjapps commentedon Apr 6, 2026
@IgnatiosSar , thanks for the update. Great news !
authorjapps commentedon Apr 12, 2026
Notice created here, will add to landing page soon:
@IgnatiosSar , Feel free to amend anything or add any examples if you find useful
IgnatiosSar commentedon Apr 13, 2026
@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):
β The New Standard (The easy way):
2. Migration Path
Previously, if a CSV had headers without the | | syntax, users had to use
ignoreHeader: truejust to skip the first line. Now, they simply need to replaceignoreHeader: truewithwithHeaders: true.For example:
The current tests look like this (unable to reference headers)
After the PR is merged they should look like this (able to reference headers)
authorjapps commentedon Apr 13, 2026
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-titleas this is referenced from other pages).IgnatiosSar commentedon Apr 14, 2026
@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.
authorjapps commentedon Apr 14, 2026
@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 :)
IgnatiosSar commentedon Apr 15, 2026
@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!