…=alexcrichton

Add --test-threads option to test binaries

This change allows parallelism of test runs to be specified by a
command line flag names --test-threads in addition to the existing
environment variable RUST_TEST_THREADS. Fixes rust-lang#25636.

Like with rust-lang#139224, this is a documentation-only deprecation for now.
Over time, we can
- warn and then remove on use of unstable environment variables
- warn on use of stable environment variables (no plan to remove due to
  compatibility)

Longer term, we expect test runners, like `cargo test`, to provide the
necessary mechanisms for environmental or persistent configuration (e.g.
using cargo config which supports `.cargo/config.toml` as well as
environment variables).

This would include:
- `RUST_TEST_THREADS`
- `RUST_TEST_NOCAPTURE`
- `RUST_TEST_SHUFFLE` (unstable)
- `RUST_TEST_SHUFFLE_SEED` (unstable)

The primary outcomes for this change are
- Reducing the scope of what is expected for custom test harnesses to
  implement
- Reduce the mechanisms that test runners, like `cargo test`, are
  expected to track when they are being bypassed to protect against
  negative interactions, e.g.  `RUST_TEST_NOCAPTURE=1` when json output
  is being read.

For testing-devex FCP, see rust-lang/testing-devex-team#10

Fixes rust-lang/testing-devex-team#10

History
-------

At each step, I could not find evidence of design discussions on whether
to support CLI, env, or both.  The first env variable seems to come from
the fact that it was being forked out of an existing env variable that
had a much wider scope.

At best, this seems like a way to offer a more persistent configuration
for these flags but environment variables hidden away in libtest is a
bit clunky and this seems like the wrong layer to handle this problem.

**Originally:** `RUST_THREADS` was respected by the Rust runtime and
libextra/test got this for free

**2013:** rust-lang#7335 suggested splitting `RUST_TEST_TASKS` out
of `RUST_THREADS`.  In that issue and the implementation
(rust-lang#8823).

**2014:** rust-lang#13374 ask for support to disable capturing of
stdout/stderr.  `--nocapture` and `RUST_TEST_NOCAPTURE` were added
together.

**2015:** rust-lang#23525 renamed `RUST_TEST_TASKS` to
`RUST_TEST_THREADS`

**2016:** rust-lang#25636 asked to configure `RUST_TEST_THREADS`
via `--test-threads` which was implemented in rust-lang#35414

**2021:** rust-lang#85440 asked for test randomization which was
implemented in rust-lang#89082, adding `--shuffle` /
RUST_TEST_SHUFFLE` and `--shuffle-seed SEED` / `RUST_TEST_SHUFFLE_SEED`

Potentially relevant issues
---------------------------

- rust-lang#74845

Deprecate RUST_TEST_* env variables

Like with rust-lang#139224, this is a documentation-only deprecation for now. Over time, we can
- warn and then remove on use of unstable environment variables
- warn on use of stable environment variables (no plan to remove due to compatibility)

Longer term, we expect test runners, like `cargo test`, to provide the necessary mechanisms for environmental or persistent configuration (e.g. using cargo config which supports `.cargo/config.toml` as well as environment variables).

This would include:
- `RUST_TEST_THREADS`
- `RUST_TEST_NOCAPTURE`
- `RUST_TEST_SHUFFLE` (unstable)
- `RUST_TEST_SHUFFLE_SEED` (unstable)

The primary outcomes for this change are
- Reducing the scope of what is expected for custom test harnesses to implement
- Reduce the mechanisms that test runners, like `cargo test`, are expected to track when they are being bypassed to protect against negative interactions, e.g.  `RUST_TEST_NOCAPTURE=1` when json output is being read.

For testing-devex FCP, see rust-lang/testing-devex-team#10

Fixes rust-lang/testing-devex-team#10

History
-------

At each step, I could not find evidence of design discussions on whether to support CLI, env, or both.  The first env variable seems to come from the fact that it was being forked out of an existing env variable that had a much wider scope.

At best, this seems like a way to offer a more persistent configuration for these flags but environment variables hidden away in libtest is a bit clunky and this seems like the wrong layer to handle this problem.

**Originally:** `RUST_THREADS` was respected by the Rust runtime and libextra/test got this for free

**2013:** rust-lang#7335 suggested splitting `RUST_TEST_TASKS` out of `RUST_THREADS`.  In that issue and the implementation (rust-lang#8823).

**2014:** rust-lang#13374 ask for support to disable capturing of stdout/stderr.  `--nocapture` and `RUST_TEST_NOCAPTURE` were added together.

**2015:** rust-lang#23525 renamed `RUST_TEST_TASKS` to `RUST_TEST_THREADS`

**2016:** rust-lang#25636 asked to configure `RUST_TEST_THREADS` via `--test-threads` which was implemented in rust-lang#35414

**2021:** rust-lang#85440 asked for test randomization which was implemented in rust-lang#89082, adding `--shuffle` / RUST_TEST_SHUFFLE` and `--shuffle-seed SEED` / `RUST_TEST_SHUFFLE_SEED`

Potentially relevant issues
---------------------------

- rust-lang#74845

Deprecate RUST_TEST_* env variables

Like with rust-lang#139224, this is a documentation-only deprecation for now. Over time, we can
- warn and then remove on use of unstable environment variables
- warn on use of stable environment variables (no plan to remove due to compatibility)

Longer term, we expect test runners, like `cargo test`, to provide the necessary mechanisms for environmental or persistent configuration (e.g. using cargo config which supports `.cargo/config.toml` as well as environment variables).

This would include:
- `RUST_TEST_THREADS`
- `RUST_TEST_NOCAPTURE`
- `RUST_TEST_SHUFFLE` (unstable)
- `RUST_TEST_SHUFFLE_SEED` (unstable)

The primary outcomes for this change are
- Reducing the scope of what is expected for custom test harnesses to implement
- Reduce the mechanisms that test runners, like `cargo test`, are expected to track when they are being bypassed to protect against negative interactions, e.g.  `RUST_TEST_NOCAPTURE=1` when json output is being read.

For testing-devex FCP, see rust-lang/testing-devex-team#10

Fixes rust-lang/testing-devex-team#10

History
-------

At each step, I could not find evidence of design discussions on whether to support CLI, env, or both.  The first env variable seems to come from the fact that it was being forked out of an existing env variable that had a much wider scope.

At best, this seems like a way to offer a more persistent configuration for these flags but environment variables hidden away in libtest is a bit clunky and this seems like the wrong layer to handle this problem.

**Originally:** `RUST_THREADS` was respected by the Rust runtime and libextra/test got this for free

**2013:** rust-lang#7335 suggested splitting `RUST_TEST_TASKS` out of `RUST_THREADS`.  In that issue and the implementation (rust-lang#8823).

**2014:** rust-lang#13374 ask for support to disable capturing of stdout/stderr.  `--nocapture` and `RUST_TEST_NOCAPTURE` were added together.

**2015:** rust-lang#23525 renamed `RUST_TEST_TASKS` to `RUST_TEST_THREADS`

**2016:** rust-lang#25636 asked to configure `RUST_TEST_THREADS` via `--test-threads` which was implemented in rust-lang#35414

**2021:** rust-lang#85440 asked for test randomization which was implemented in rust-lang#89082, adding `--shuffle` / RUST_TEST_SHUFFLE` and `--shuffle-seed SEED` / `RUST_TEST_SHUFFLE_SEED`

Potentially relevant issues
---------------------------

- rust-lang#74845

Deprecate RUST_TEST_* env variables

Like with rust-lang#139224, this is a documentation-only deprecation for now. Over time, we can
- warn and then remove on use of unstable environment variables
- warn on use of stable environment variables (no plan to remove due to compatibility)

Longer term, we expect test runners, like `cargo test`, to provide the necessary mechanisms for environmental or persistent configuration (e.g. using cargo config which supports `.cargo/config.toml` as well as environment variables).

This would include:
- `RUST_TEST_THREADS`
- `RUST_TEST_NOCAPTURE`
- `RUST_TEST_SHUFFLE` (unstable)
- `RUST_TEST_SHUFFLE_SEED` (unstable)

The primary outcomes for this change are
- Reducing the scope of what is expected for custom test harnesses to implement
- Reduce the mechanisms that test runners, like `cargo test`, are expected to track when they are being bypassed to protect against negative interactions, e.g.  `RUST_TEST_NOCAPTURE=1` when json output is being read.

For testing-devex FCP, see rust-lang/testing-devex-team#10

Fixes rust-lang/testing-devex-team#10

History
-------

At each step, I could not find evidence of design discussions on whether to support CLI, env, or both.  The first env variable seems to come from the fact that it was being forked out of an existing env variable that had a much wider scope.

At best, this seems like a way to offer a more persistent configuration for these flags but environment variables hidden away in libtest is a bit clunky and this seems like the wrong layer to handle this problem.

**Originally:** `RUST_THREADS` was respected by the Rust runtime and libextra/test got this for free

**2013:** rust-lang#7335 suggested splitting `RUST_TEST_TASKS` out of `RUST_THREADS`.  In that issue and the implementation (rust-lang#8823).

**2014:** rust-lang#13374 ask for support to disable capturing of stdout/stderr.  `--nocapture` and `RUST_TEST_NOCAPTURE` were added together.

**2015:** rust-lang#23525 renamed `RUST_TEST_TASKS` to `RUST_TEST_THREADS`

**2016:** rust-lang#25636 asked to configure `RUST_TEST_THREADS` via `--test-threads` which was implemented in rust-lang#35414

**2021:** rust-lang#85440 asked for test randomization which was implemented in rust-lang#89082, adding `--shuffle` / RUST_TEST_SHUFFLE` and `--shuffle-seed SEED` / `RUST_TEST_SHUFFLE_SEED`

Potentially relevant issues
---------------------------

- rust-lang#74845

Deprecate RUST_TEST_* env variables

Like with rust-lang#139224, this is a documentation-only deprecation for now. Over time, we can
- warn and then remove on use of unstable environment variables
- warn on use of stable environment variables (no plan to remove due to compatibility)

Longer term, we expect test runners, like `cargo test`, to provide the necessary mechanisms for environmental or persistent configuration (e.g. using cargo config which supports `.cargo/config.toml` as well as environment variables).

This would include:
- `RUST_TEST_THREADS`
- `RUST_TEST_NOCAPTURE`
- `RUST_TEST_SHUFFLE` (unstable)
- `RUST_TEST_SHUFFLE_SEED` (unstable)

The primary outcomes for this change are
- Reducing the scope of what is expected for custom test harnesses to implement
- Reduce the mechanisms that test runners, like `cargo test`, are expected to track when they are being bypassed to protect against negative interactions, e.g.  `RUST_TEST_NOCAPTURE=1` when json output is being read.

For testing-devex FCP, see rust-lang/testing-devex-team#10

Fixes rust-lang/testing-devex-team#10

History
-------

At each step, I could not find evidence of design discussions on whether to support CLI, env, or both.  The first env variable seems to come from the fact that it was being forked out of an existing env variable that had a much wider scope.

At best, this seems like a way to offer a more persistent configuration for these flags but environment variables hidden away in libtest is a bit clunky and this seems like the wrong layer to handle this problem.

**Originally:** `RUST_THREADS` was respected by the Rust runtime and libextra/test got this for free

**2013:** rust-lang#7335 suggested splitting `RUST_TEST_TASKS` out of `RUST_THREADS`.  In that issue and the implementation (rust-lang#8823).

**2014:** rust-lang#13374 ask for support to disable capturing of stdout/stderr.  `--nocapture` and `RUST_TEST_NOCAPTURE` were added together.

**2015:** rust-lang#23525 renamed `RUST_TEST_TASKS` to `RUST_TEST_THREADS`

**2016:** rust-lang#25636 asked to configure `RUST_TEST_THREADS` via `--test-threads` which was implemented in rust-lang#35414

**2021:** rust-lang#85440 asked for test randomization which was implemented in rust-lang#89082, adding `--shuffle` / RUST_TEST_SHUFFLE` and `--shuffle-seed SEED` / `RUST_TEST_SHUFFLE_SEED`

Potentially relevant issues
---------------------------

- rust-lang#74845

Deprecate RUST_TEST_* env variables

Like with rust-lang#139224, this is a documentation-only deprecation for now. Over time, we can
- warn and then remove on use of unstable environment variables
- warn on use of stable environment variables (no plan to remove due to compatibility)

Longer term, we expect test runners, like `cargo test`, to provide the necessary mechanisms for environmental or persistent configuration (e.g. using cargo config which supports `.cargo/config.toml` as well as environment variables).

This would include:
- `RUST_TEST_THREADS`
- `RUST_TEST_NOCAPTURE`
- `RUST_TEST_SHUFFLE` (unstable)
- `RUST_TEST_SHUFFLE_SEED` (unstable)

The primary outcomes for this change are
- Reducing the scope of what is expected for custom test harnesses to implement
- Reduce the mechanisms that test runners, like `cargo test`, are expected to track when they are being bypassed to protect against negative interactions, e.g.  `RUST_TEST_NOCAPTURE=1` when json output is being read.

For testing-devex FCP, see rust-lang/testing-devex-team#10

Fixes rust-lang/testing-devex-team#10

History
-------

At each step, I could not find evidence of design discussions on whether to support CLI, env, or both.  The first env variable seems to come from the fact that it was being forked out of an existing env variable that had a much wider scope.

At best, this seems like a way to offer a more persistent configuration for these flags but environment variables hidden away in libtest is a bit clunky and this seems like the wrong layer to handle this problem.

**Originally:** `RUST_THREADS` was respected by the Rust runtime and libextra/test got this for free

**2013:** rust-lang#7335 suggested splitting `RUST_TEST_TASKS` out of `RUST_THREADS`.  In that issue and the implementation (rust-lang#8823).

**2014:** rust-lang#13374 ask for support to disable capturing of stdout/stderr.  `--nocapture` and `RUST_TEST_NOCAPTURE` were added together.

**2015:** rust-lang#23525 renamed `RUST_TEST_TASKS` to `RUST_TEST_THREADS`

**2016:** rust-lang#25636 asked to configure `RUST_TEST_THREADS` via `--test-threads` which was implemented in rust-lang#35414

**2021:** rust-lang#85440 asked for test randomization which was implemented in rust-lang#89082, adding `--shuffle` / RUST_TEST_SHUFFLE` and `--shuffle-seed SEED` / `RUST_TEST_SHUFFLE_SEED`

Potentially relevant issues
---------------------------

- rust-lang#74845

Rollup merge of #145269 - epage:test-env, r=jhpratt

Deprecate RUST_TEST_* env variables

Like with #139224, this is a documentation-only deprecation for now. Over time, we can
- warn and then remove on use of unstable environment variables
- warn on use of stable environment variables (no plan to remove due to compatibility)

Longer term, we expect test runners, like `cargo test`, to provide the necessary mechanisms for environmental or persistent configuration (e.g. using cargo config which supports `.cargo/config.toml` as well as environment variables).

This would include:
- `RUST_TEST_THREADS`
- `RUST_TEST_NOCAPTURE`
- `RUST_TEST_SHUFFLE` (unstable)
- `RUST_TEST_SHUFFLE_SEED` (unstable)

The primary outcomes for this change are
- Reducing the scope of what is expected for custom test harnesses to implement
- Reduce the mechanisms that test runners, like `cargo test`, are expected to track when they are being bypassed to protect against negative interactions, e.g.  `RUST_TEST_NOCAPTURE=1` when json output is being read.

For testing-devex FCP, see rust-lang/testing-devex-team#10

Fixes rust-lang/testing-devex-team#10

History
-------

At each step, I could not find evidence of design discussions on whether to support CLI, env, or both.  The first env variable seems to come from the fact that it was being forked out of an existing env variable that had a much wider scope.

At best, this seems like a way to offer a more persistent configuration for these flags but environment variables hidden away in libtest is a bit clunky and this seems like the wrong layer to handle this problem.

**Originally:** `RUST_THREADS` was respected by the Rust runtime and libextra/test got this for free

**2013:** #7335 suggested splitting `RUST_TEST_TASKS` out of `RUST_THREADS`.  In that issue and the implementation (#8823).

**2014:** #13374 ask for support to disable capturing of stdout/stderr.  `--nocapture` and `RUST_TEST_NOCAPTURE` were added together.

**2015:** #23525 renamed `RUST_TEST_TASKS` to `RUST_TEST_THREADS`

**2016:** #25636 asked to configure `RUST_TEST_THREADS` via `--test-threads` which was implemented in #35414

**2021:** #85440 asked for test randomization which was implemented in #89082, adding `--shuffle` / RUST_TEST_SHUFFLE` and `--shuffle-seed SEED` / `RUST_TEST_SHUFFLE_SEED`

Potentially relevant issues
---------------------------

- #74845

Deprecate RUST_TEST_* env variables

Like with rust-lang#139224, this is a documentation-only deprecation for now. Over time, we can
- warn and then remove on use of unstable environment variables
- warn on use of stable environment variables (no plan to remove due to compatibility)

Longer term, we expect test runners, like `cargo test`, to provide the necessary mechanisms for environmental or persistent configuration (e.g. using cargo config which supports `.cargo/config.toml` as well as environment variables).

This would include:
- `RUST_TEST_THREADS`
- `RUST_TEST_NOCAPTURE`
- `RUST_TEST_SHUFFLE` (unstable)
- `RUST_TEST_SHUFFLE_SEED` (unstable)

The primary outcomes for this change are
- Reducing the scope of what is expected for custom test harnesses to implement
- Reduce the mechanisms that test runners, like `cargo test`, are expected to track when they are being bypassed to protect against negative interactions, e.g.  `RUST_TEST_NOCAPTURE=1` when json output is being read.

For testing-devex FCP, see rust-lang/testing-devex-team#10

Fixes rust-lang/testing-devex-team#10

History
-------

At each step, I could not find evidence of design discussions on whether to support CLI, env, or both.  The first env variable seems to come from the fact that it was being forked out of an existing env variable that had a much wider scope.

At best, this seems like a way to offer a more persistent configuration for these flags but environment variables hidden away in libtest is a bit clunky and this seems like the wrong layer to handle this problem.

**Originally:** `RUST_THREADS` was respected by the Rust runtime and libextra/test got this for free

**2013:** rust-lang#7335 suggested splitting `RUST_TEST_TASKS` out of `RUST_THREADS`.  In that issue and the implementation (rust-lang#8823).

**2014:** rust-lang#13374 ask for support to disable capturing of stdout/stderr.  `--nocapture` and `RUST_TEST_NOCAPTURE` were added together.

**2015:** rust-lang#23525 renamed `RUST_TEST_TASKS` to `RUST_TEST_THREADS`

**2016:** rust-lang#25636 asked to configure `RUST_TEST_THREADS` via `--test-threads` which was implemented in rust-lang#35414

**2021:** rust-lang#85440 asked for test randomization which was implemented in rust-lang#89082, adding `--shuffle` / RUST_TEST_SHUFFLE` and `--shuffle-seed SEED` / `RUST_TEST_SHUFFLE_SEED`

Potentially relevant issues
---------------------------

- rust-lang#74845