DEBUG-2334 fix running documentation with scenario

[p-datadog]

Motivation

Current documentation mixes upper and lower case for scenario name in the instructions for running a single file with a scenario.

Changes

Change the instructions to use +S option to pass the actual scenario name as specified in the test file (in lower case). Now the instructions can be followed as written.

Workflow

1. ⚠️ Create your PR as draft ⚠️
2. Work on you PR until the CI passes (if something not related to your task is failing, you can ignore it)
3. Mark it as ready for review
   • Test logic is modified? -> Get a review from RFC owner. We're working on refining the codeowners file quickly.
   • Framework is modified, or non obvious usage of it -> get a review from R&P team

🚀 Once your PR is reviewed, you can merge it!

🛟 #apm-shared-testing 🛟

Reviewer checklist

• If PR title starts with [<language>], double-check that only <language> is impacted by the change
• No system-tests internal is modified. Otherwise, I have the approval from R&P team
• CI is green, or failing jobs are not related to this change (and you are 100% sure about this statement)
• A docker base image is modified?
  • the relevant build-XXX-image label is present
• A scenario is added (or removed)?
  • Get a review from R&P team

[cbeauchesne]

Scenario names are in upper case in bash commands, and lowecase in python.

Furthermore, the first argument is interpreted as the senario if it's in uppercase (that the prupose to keep it uppercase), in order to avoid to write the +S.

[p-datadog]

I get that the usage of uppercase might make some operations more convenient for those developers that use system tests all the time. However, since it is not possible to know which case to use when (you need to somehow have this knowledge already), using two different cases hampers discoverability and creates problems when searching (since both cases need to be checked).

The instructions, as written, say that scenario name is the value in the decorator in the test code. They do not mention the required transformation to upper case in order to use the scenario name in (some? all?) shell commands.

This PR proposes using the same case everywhere. This is already supported by the code and is easy to understand for newcomers to the project - the target audience, one would assume, for the instructions in question.

Alternatively, we could add the text of your comment to the instructions, but 1) the instructions would get much longer, 2) they would also take more time to understand, 3) it would still be impossible to copy-paste scenario name from a test source file to the terminal and have the test be correctly executed.

[cbeauchesne]

Ok, I understand.

This PR proposes using the same case everywhere.

So this PR is not only a doc improvment, but a suggestion to change an usage.

I tend agree with your rationals. But the fact we use an uppercase identifier as scenario name without the need of +S is already known by all users. I actually presume, that almost nobodies knows +S. Changing that needs a proper communication, and verify that it's something users will be confortable with.

The starting point for that is to initiate the discussion in #apm-shared-testing channel. If they're ok, we'll keep the possibility of ./run.sh UPPERCASE as it's compatible. So the question you can ask can be something like :

I propose to change the doc to only mention ./run.sh +S lowercase as the official way to run a system-tests scenario because <---your rationnals--->.
Though, using ./run.sh UPPERCASE will always be possible to keep backward compabitility.

If we receive positive feedback, all good !