Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: edit writing-tests.md #10585

Closed
wants to merge 2 commits into from
Closed

doc: edit writing-tests.md #10585

wants to merge 2 commits into from

Conversation

Trott
Copy link
Member

@Trott Trott commented Jan 3, 2017

  • Remove passive voice
  • Remove unneeded modifiers
  • Minor comma change
Checklist
  • documentation is changed or added
  • commit message follows commit guidelines
Affected core subsystem(s)

doc test

@Trott Trott added doc Issues and PRs related to the documentations. test Issues and PRs related to the tests. labels Jan 3, 2017
@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Jan 3, 2017
by `common` are used, it can be included without assigning it to an identifier:
Even if a test uses no functions or other properties exported by `common`,
the test should still include the `common` module. This is because the `common`
module includes code that will cause tests to fail if there are variables leaked
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the passive->active change here? Is this a general rule we follow? I find if there are variables leaked into the global space less clear than if variables are leaked into the global space.

Copy link
Member Author

@Trott Trott Jan 8, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about if the test leaks variables into the global space?

The passive->active change is just following a general writing recommendation for increased clarity, but of course we should stick to passive voice if changing to active does not increase clarity. :-D

Copy link
Member

@gibfahn gibfahn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with nit

depending on the platform. For example:

```javascript
const timer = setTimeout(fail, common.platformTimeout(4000));
```

will create a 4-seconds timeout, except for some platforms where the delay will
be multiplied for some factor.
will create a 4-seconds timeout on most platforms but a longer timeout on slower
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

4-seconds->4-second

the global space. In situations where no functions or other properties exported
by `common` are used, it can be included without assigning it to an identifier:
Even if a test uses no functions or other properties exported by `common`,
the test should still include the `common` module. This is because the `common`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"include the common module, as the first executable statement" maybe?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or maybe to be really clear just say that the first two lines of the test must be:

'use strict';
const common = require('../common');

or

'use strict';
require('../common');

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally, this holds good. But in some tests we have comments at the beginning (I mean before common) and that is also acceptable.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason we couldn't just standardise on what's in this guide?

'use strict';
require('../common');

// Comments after this

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we did that we could lint for it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lets see what @Trott thinks about it.

Copy link
Member Author

@Trott Trott Jan 11, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about include the common module before any other modules. as a reasonable concise compromise that we can expand on later if it is found to be inadequate?

@jasnell
Copy link
Member

jasnell commented Jan 6, 2017

Ping @Trott

@Trott
Copy link
Member Author

Trott commented Jan 11, 2017

Nits addressed, I think.

* Remove passive voice
* Remove unneeded modifiers
* Minor comma change
Trott added a commit to Trott/io.js that referenced this pull request Jan 12, 2017
* Remove passive voice
* Remove unneeded modifiers
* Minor comma change

PR-URL: nodejs#10585
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Italo A. Casas <me@italoacasas.com>
@Trott
Copy link
Member Author

Trott commented Jan 12, 2017

Landed in 0674789

@Trott Trott closed this Jan 12, 2017
italoacasas pushed a commit to italoacasas/node that referenced this pull request Jan 18, 2017
* Remove passive voice
* Remove unneeded modifiers
* Minor comma change

PR-URL: nodejs#10585
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Italo A. Casas <me@italoacasas.com>
italoacasas pushed a commit to italoacasas/node that referenced this pull request Jan 23, 2017
* Remove passive voice
* Remove unneeded modifiers
* Minor comma change

PR-URL: nodejs#10585
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Italo A. Casas <me@italoacasas.com>
italoacasas pushed a commit to italoacasas/node that referenced this pull request Jan 24, 2017
* Remove passive voice
* Remove unneeded modifiers
* Minor comma change

PR-URL: nodejs#10585
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Italo A. Casas <me@italoacasas.com>
italoacasas pushed a commit to italoacasas/node that referenced this pull request Jan 27, 2017
* Remove passive voice
* Remove unneeded modifiers
* Minor comma change

PR-URL: nodejs#10585
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Italo A. Casas <me@italoacasas.com>
@italoacasas italoacasas mentioned this pull request Jan 29, 2017
MylesBorins pushed a commit that referenced this pull request Mar 7, 2017
* Remove passive voice
* Remove unneeded modifiers
* Minor comma change

PR-URL: #10585
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Italo A. Casas <me@italoacasas.com>
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
* Remove passive voice
* Remove unneeded modifiers
* Minor comma change

PR-URL: #10585
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Italo A. Casas <me@italoacasas.com>
@MylesBorins MylesBorins mentioned this pull request Mar 9, 2017
@Trott Trott deleted the writing-tests branch January 13, 2022 22:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. test Issues and PRs related to the tests.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants