Clarify documentation around stepMatchArgumentsLists

[mpkorstanje]

⚡️ What's your motivation?

This has confused the hell out of me for the longest time.

🏷️ What kind of change is this?

• 📖 Documentation (improvements without changing code)

📋 Checklist:

• I agree to respect and uphold the Cucumber Community Code of Conduct

[clrudolphi]

That is not at all what I understand.

For instance, in the CCK Minimal example, the TestCase message is:

{"testCase":{"id":"6","pickleId":"3","testSteps":[{"id":"7","pickleStepId":"2","stepDefinitionIds":["4"],"stepMatchArgumentsLists":[{"stepMatchArguments":[{"group":{"start":7,"value":"42","children":[]},"parameterTypeName":"int"}]}]}],"testRunStartedId":"5"}}

and in the Parameter-Types example it is:

{"testCase":{"id":"7","pickleId":"3","testSteps":[{"id":"8","pickleStepId":"2","stepDefinitionIds":["5"],"stepMatchArgumentsLists":[{"stepMatchArguments":[{"group":{"start":0,"value":"LHR-CDG","children":[{"start":0,"value":"LHR","children":[]},{"start":4,"value":"CDG","children":[]}]},"parameterTypeName":"flight"}]}]}],"testRunStartedId":"6"}}

The StepMatchArgumentsLists appear to be a list of items that describe how the arguments of the step align with the parameters of the StepDefinition method. In the example of the Parameter-Type, it provides an entry in the StepMatchArguments for each match group of the regex.

Unfortunately, the CCK has no scenarios that cover an ambiguous binding situation.

[mpkorstanje]

@clrudolphi cucumber/compatibility-kit#156

For an ambiguous step, a testcase will have test step with multiple entries in stepDefinitionIds and stepMatchArgumentsLists. The first entry in the stepMatchArgumentsLists holds the list of arguments for the first matching step definition, the second entry for the second, ect.

See comments below:

{
  "testCase": {
    "id": "7",
    "pickleId": "3",
    "testSteps": [
      {
        "id": "8",
        "pickleStepId": "2",
        "stepDefinitionIds": [
          "4", // First matching step definition
          "5"  // Second matching step definition
        ],
        "stepMatchArgumentsLists": [
          {
            "stepMatchArguments": [  // First list of arguments for the first matching step definition
              {
                "group": {
                  "start": 2,
                  "value": "step",
                  "children": []
                }
              },
              {
                "group": {
                  "start": 12,
                  "value": "",
                  "children": []
                }
              }
            ]
          },
          {
            "stepMatchArguments": [   // Second list of arguments for the second matching step definition
              {
                "group": {
                  "start": 12,
                  "value": "multiple definitions",
                  "children": []
                },
                "parameterTypeName": ""
              }
            ]
          }
        ]
      }
    ],
    "testRunStartedId": "6"
  }
}

[clrudolphi]

@mpkorstanje Thank you for the explanation.

What threw me off was the comment added by revised schema that is thrown in to the generated code that implies that consumers may look at the count of entries in the StepMatchArgumentLists array to determine whether there is ambiguity or not.

There is similar wording already on the stepDefinitionIds array, which is sufficient IMO.

The comment to be placed on the StepMatchArgumentLists array might be your explanation above:

For an ambiguous step, a testcase will have test step with multiple entries in stepDefinitionIds and stepMatchArgumentsLists. The first entry in the stepMatchArgumentsLists holds the list of arguments for the first matching step definition, the second entry for the second, etc.

[mpkorstanje]

That is a good idea! Cheers!