doc: recommend writing tests in new files and including comments - #57028
Merged
nodejs-github-bot merged 1 commit intoFeb 15, 2025
Merged
doc: recommend writing tests in new files and including comments#57028nodejs-github-bot merged 1 commit into
nodejs-github-bot merged 1 commit into
Conversation
Copy link
Copy Markdown
Member
Sorry, something went wrong.
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails.
Copy link
Copy Markdown
Collaborator
|
Review requested:
|
Sorry, something went wrong.
Copy link
Copy Markdown
Member
Author
|
cc @jasnell @nodejs/tsc since we discussed this in the TSC meeting before. In recent code reviews I noticed that many are still appending new test cases this way, which is probably guided by the doc, so I think we need to update the docs to have a ground to ask for changes when people do this in the PR. |
Sorry, something went wrong.
jasnell
approved these changes
Feb 13, 2025
richardlau
approved these changes
Feb 13, 2025
targos
approved these changes
Feb 13, 2025
UlisesGascon
approved these changes
Feb 13, 2025
lpinca
approved these changes
Feb 13, 2025
jakecastelli
approved these changes
Feb 14, 2025
Copy link
Copy Markdown
Member
|
I personally found naming a test (file name) is also hard, do we have any convention or guide for it? |
Sorry, something went wrong.
Copy link
Copy Markdown
Member
Author
|
I usually start with writing the comment and then take keywords from my comment to create the name. Not sure if that counts as guides. |
Sorry, something went wrong.
legendecas
approved these changes
Feb 14, 2025
bnb
approved these changes
Feb 14, 2025
targos
pushed a commit
that referenced
this pull request
Feb 17, 2025
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails. PR-URL: #57028 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im>
acidiney
pushed a commit
to acidiney/node
that referenced
this pull request
Feb 23, 2025
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails. PR-URL: nodejs#57028 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im>
aduh95
pushed a commit
that referenced
this pull request
Apr 2, 2025
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails. PR-URL: #57028 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im>
aduh95
pushed a commit
that referenced
this pull request
Apr 3, 2025
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails. PR-URL: #57028 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im>
RafaelGSS
pushed a commit
that referenced
this pull request
Apr 16, 2025
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails. PR-URL: #57028 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im>
RafaelGSS
pushed a commit
that referenced
this pull request
Apr 17, 2025
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails. PR-URL: #57028 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im>
marco-ippolito
pushed a commit
that referenced
this pull request
Aug 18, 2025
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails. PR-URL: #57028 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im>
marco-ippolito
pushed a commit
that referenced
this pull request
Aug 20, 2025
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails. PR-URL: #57028 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im>
marco-ippolito
pushed a commit
that referenced
this pull request
Aug 25, 2025
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails. PR-URL: #57028 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im>
marco-ippolito
pushed a commit
that referenced
this pull request
Aug 25, 2025
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails. PR-URL: #57028 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im>
marco-ippolito
pushed a commit
that referenced
this pull request
Aug 27, 2025
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test. This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails. PR-URL: #57028 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Reviewers
10 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The previous phrasing encouraged or did not discourage appending new test cases to existing files - a practice that can reduce the debuggability of the tests over time as they get bigger and bigger, some times thousands of lines long with hundreds of test cases, and make the CI output increasingly difficult to read when one of the test cases fail in a very long test.
This patch updates the guideline to explicitly discourage appending test cases this way. Also recommend including an opening comment to describe what the test does to optimize the test towards the scenario when it fails.
For some concrete examples:
To avoid losing git history I would not recommend splitting existing tests unless there's a ongoing motivation to do so (e.g. it's flaking in the CI). But I think we should at least discourage new tests to be written in a way that exacerbate the problem.