doc: Add example to test doc for clarity

[addityasingh]

Add example to the test doc for clarity

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[Trott]

Hi, @addityasingh! Welcome and thanks for the pull request! I feel like the way this changes the sentence to be a run-on sentence with confusing capitalization and seemingly out-of-place abbreviation usage does more harm to the text than benefit. It makes it harder to scan/read/understand. I think a better approach might be to update the example to specify the full path to the filename of the test file. That will make it more obvious what the sample code is doing without having to explain it in the text like this.

[Trott]

Hi, @addityasingh! Welcome and thanks for the pull request! I feel like the way this changes the sentence to be a run-on sentence with confusing capitalization and seemingly out-of-place abbreviation usage does more harm to the text than benefit. It makes it harder to scan/read/understand. I think a better approach might be to update the example to specify the full path to the filename of the test file. That will make it more obvious what the sample code is doing without having to explain it in the text like this.

So, for example, maybe update the sample code to be this?

$ python tools/test.py -J --mode=release test/parallel/test-stream2-transform.js

Furthermore (and optionally--these things below are not required in this PR, but I'd be happy to see them myself), this can be simplified. Since this is an example of just running a single test, the -J option seems unnecessary:

$ python tools/test.py --mode=release test/parallel/test-stream2-transform.js

And honestly, I'm not sure --mode=release is useful here. I never use it myself, and the point of this is to show how to simply run a single test, so in the interest of keeping it simple:

$ python tools/test.py test/parallel/test-stream2-transform.js

Lastly, tools/test.py does not need to be called explicitly with python assuming the execution bit is set (which it is in the repo, at least on UNIX-like operating systems), so:

$ tools/test.py test/parallel/test-stream2-transform.js

[addityasingh]

@Trott Thanks for the suggestions.

Since this is an example of just running a single test, the -J option seems unnecessary:

Agreed. I will remove the -J. I didn't update since it already existed.

And honestly, I'm not sure --mode=release is useful here

I will remove it from this specific command

Lastly, tools/test.py does not need to be called explicitly with python assuming the execution bit is set

I disagree. For the sake of inter-operability and explicitness, we should still keep the python

On top of those, I would update the sentence to specify that the command is to execute all tests in a file and not just one test. Currently, its unclear if the command is intended to execute all the tests in same file or just a single test.

[Trott]

Left two optional suggestions, but this looks good to me with or without those suggestions.

[addityasingh]

@Trott Can you check now? I applied your suggestions

[Trott]

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/3445/

[danbev]

Landed in fa3eefc 🎉