docs(test): Expand documentation of cargo-test-support #14272

epage · 2024-07-19T19:16:48Z

What does this PR try to resolve?

In wanting to document #14039, I felt it would be good to put that documentation in cargo-test-support. To do so, I wanted a baseline of existing documentation for it to build on top of.

I was tempted to move more of "Writing tests" contrib documentation here, as its more about using cargo-test-support but I decided to hold off for now as most of that was long-form documentation and this is mostly focused on reference documentation.

How should we test and review this PR?

Additional information

This will make them more easily discovered and make it easier to remember to update them.

rustbot · 2024-07-19T19:16:53Z

r? @weihanglo

rustbot has assigned @weihanglo.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

weihanglo · 2024-07-19T22:34:18Z

crates/cargo-test-macro/src/lib.rs

+///   The SSH tests also assume that you have OpenSSH installed.
+///   These should work on Linux, macOS, and Windows where possible.
+///   Unfortunately these tests are not run in CI for macOS or Windows (no Docker on macOS, and Windows does not support Linux images).
+///   See [`crates/cargo-test-support/src/containers.rs`](https://github.com/rust-lang/cargo/blob/master/crates/cargo-test-support/src/containers.rs) for more on writing these tests.


Link to rustdoc instead of code?

I pointed to the nightly docs because I figured that was the most likely one for users to be looking at.

Its not used anywhere

I'm intentionally being light as I want to pull in a lot of "lessons learned" from the port to snapbox into the docs and want that as a dedicated PR to make it easier for the contributors to that effort to review it.

I considered hiding `init_root` as an implementation detail of `#[cargo_test]` but decided to be conservative about that for now.

weihanglo · 2024-07-22T14:40:42Z

Thanks!

@bors r+

bors · 2024-07-22T14:40:44Z

📌 Commit 83cbca0 has been approved by weihanglo

It is now in the queue for this repository.

bors · 2024-07-22T15:10:10Z

⌛ Testing commit 83cbca0 with merge ea14e86...

bors · 2024-07-22T15:38:11Z

☀️ Test successful - checks-actions
Approved by: weihanglo
Pushing ea14e86 to master...

Update cargo 14 commits in 5f6b9a92201d78af75dc24f14662c3e2dacbbbe1..b5d44db1daf0469b227a6211b987162a39a54730 2024-07-19 18:09:17 +0000 to 2024-07-26 21:27:12 +0000 - Package workspaces (rust-lang/cargo#13947) - test: migrate messages to snapbox (rust-lang/cargo#14242) - chore: Update dependencies (rust-lang/cargo#14299) - fix: remove rustc probe for `--check-cfg` support (rust-lang/cargo#14302) - Misc test clean up (rust-lang/cargo#14297) - Don't downgrade on prerelease `VersionReq` when update with --breaking. (rust-lang/cargo#14250) - test: Migrate some json tests to snapbox (rust-lang/cargo#14293) - Revert "fix: Ensure dep/feature activates the dependency on 2024" (rust-lang/cargo#14295) - chore: bump cargo-test-support to 0.4.0 (rust-lang/cargo#14286) - Bump to 0.83.0; update changelog (rust-lang/cargo#14285) - Improved error message when `update --breaking` invalid spec. (rust-lang/cargo#14279) - docs(test): Expand documentation of cargo-test-support (rust-lang/cargo#14272) - test: Fix some test based on rustc version (rust-lang/cargo#14282) - Use `Rc` instead of `Arc` for storing rustflags (rust-lang/cargo#14273) r? ghost

epage added 3 commits July 19, 2024 12:04

docs(contrib): Update functional/ui comparison

742defb

docs(contrib): Update functional example

ba94d70

docs(test): Migrate cargo_test docs from contrib to API reference

f05eba0

This will make them more easily discovered and make it easier to remember to update them.

rustbot assigned weihanglo Jul 19, 2024

rustbot added A-documenting-cargo-itself Area: Cargo's documentation A-testing-cargo-itself Area: cargo's tests S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 19, 2024

weihanglo approved these changes Jul 19, 2024

View reviewed changes

epage added 21 commits July 22, 2024 08:58

docs(test): Point to docs, rather than source

83d1c14

I pointed to the nightly docs because I figured that was the most likely one for users to be looking at.

docs(test): Link to two different docs builds

8e524ae

docs(test): Verify they work

ad6abb5

docs(test): Add high level example

ca9fc47

docs(test): Document t!

86945a2

docs(test): Document cargo_process

504d377

docs(test): Document git_process

fa0e66e

docs(test): Document cargo_exe

7762d1f

docs(test): Pull RawOutput from API

f42ae4c

Its not used anywhere

docs(test): Organize docs for Execs

4674f2b

docs(test): Document Execs

1fe8ae6

I'm intentionally being light as I want to pull in a lot of "lessons learned" from the port to snapbox into the docs and want that as a dedicated PR to make it easier for the contributors to that effort to review it.

docs(test): Document basic_*manifest functions

b4b56d4

docs(test): Document 'process'

1707566

docs(test): Document main_file function

c9dddd2

docs(test): Document panic_error function

e53f2af

docs(test): Document project* functions

3dff0ec

docs(test): Expand docs for Project

45f61cc

docs(test): Expand docs for ProjectBuilder

cb52840

docs(test): Expand 'compare' documentation

8f88a8a

docs(test): Expose git documentation

97ccb65

docs(test): Expand 'git' documentation

64a62ff

epage added 4 commits July 22, 2024 08:58

docs(test): Expand 'install' documentation

062652c

refactor(test): Document 'paths' mod

6d0eea0

I considered hiding `init_root` as an implementation detail of `#[cargo_test]` but decided to be conservative about that for now.

refactor(test): Document 'publish' mod

b931d98

refactor(test): Document 'registry' mod

83cbca0

epage force-pushed the test-docs branch from 5b56376 to 83cbca0 Compare July 22, 2024 13:59

weihanglo approved these changes Jul 22, 2024

View reviewed changes

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 22, 2024

bors merged commit ea14e86 into rust-lang:master Jul 22, 2024
15 of 24 checks passed

This was referenced Jul 23, 2024

Port from bespoke assertions of snapbox #14039

Closed

support generic target tables and env variables #9603

Closed

epage deleted the test-docs branch July 23, 2024 19:16

weihanglo mentioned this pull request Jul 27, 2024

Update cargo rust-lang/rust#128270

Merged

rustbot added this to the 1.82.0 milestone Jul 28, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(test): Expand documentation of cargo-test-support #14272

docs(test): Expand documentation of cargo-test-support #14272

epage commented Jul 19, 2024 •

edited

Loading

rustbot commented Jul 19, 2024

weihanglo Jul 19, 2024

weihanglo commented Jul 22, 2024

bors commented Jul 22, 2024

bors commented Jul 22, 2024

bors commented Jul 22, 2024

docs(test): Expand documentation of cargo-test-support #14272

docs(test): Expand documentation of cargo-test-support #14272

Conversation

epage commented Jul 19, 2024 • edited Loading

What does this PR try to resolve?

How should we test and review this PR?

Additional information

rustbot commented Jul 19, 2024

weihanglo Jul 19, 2024

Choose a reason for hiding this comment

weihanglo commented Jul 22, 2024

bors commented Jul 22, 2024

bors commented Jul 22, 2024

bors commented Jul 22, 2024

epage commented Jul 19, 2024 •

edited

Loading