Skip to content

Conversation

grynspan
Copy link
Contributor

@grynspan grynspan commented Feb 25, 2025

This PR renames ExitTestArtifacts to ExitTest.Result and splits ExitCondition into two types: ExitTest.Condition which can be passed to #expect(exitsWith:) and StatusAtExit which represents the raw, possibly platform-specific status reported by the kernel when a child process terminates.

The latter type is not nested in ExitTest because it can be used independently of exit tests and we may want to use it in the future for things like multi-process parallelization, but if a platform supports spawning processes but not exit tests, nesting it in ExitTest would make it unavailable.

I considered several names for StatusAtExit:

  • ExitStatus: too easily confusable with exit codes such as EXIT_SUCCESS;
  • ProcessStatus: we don't say "process" in our API surface elsewhere;
  • Status: too generic
  • ExitReason: "status" is a more widely-used term of art for this concept.

Foundation uses terminationStatus to represent the raw integer value and Process.TerminationReason to represent whether it's an exit code or signal. We don't use "termination" in Swift Testing's API anywhere.

I settled on StatusAtExit because it was distinct and makes it clear that it represents the status of a process at exit time (as opposed to while running, e.g. enum ProcessStatus { case running; case suspended; case terminated }.

Updates to the exit tests proposal document will follow in a separate PR.

Checklist:

  • Code and documentation should follow the style of the Style Guide.
  • If public symbols are renamed or modified, DocC references should be updated.

This PR renames `ExitTestArtifacts` to `ExitTest.Result` and splits
`ExitCondition` into two types: `ExitTest.Condition` which can be passed to
`#expect(exitsWith:)` and `StatusAtExit` which represents the raw, possibly
platform-specific status reported by the kernel when a child process terminates.

The latter type is not nested in `ExitTest` because it can be used independently
of exit tests and we may want to use it in the future for things like
multi-process parallelization, but if a platform supports spawning processes but
not exit tests, nesting it in `ExitTest` would make it unavailable.

I considered several names for `StatusAtExit`:

- `ExitStatus`: too easily confusable with exit _codes_ such as `EXIT_SUCCESS`;
- `ProcessStatus`: we don't say "process" in our API surface elsewhere;
- `Status`: too generic
- `ExitReason`: "status" is a more widely-used term of art for this concept.

Foundation uses `terminationStatus` to represent the raw integer value and
`Process.TerminationReason` to represent whether it's an exit code or signal. We
don't use "termination" in Swift Testing's API anywhere.

I settled on `StatusAtExit` because it was distinct and makes it clear that it
represents the status of a process _at exit time_ (as opposed to while running,
e.g. `enum ProcessStatus { case running; case suspended; case terminated }`.

Updates to the exit tests proposal document will follow in a separate PR.
@grynspan grynspan added enhancement New feature or request public-api Affects public API exit-tests ☠️ Work related to exit tests labels Feb 25, 2025
@grynspan grynspan added this to the Swift 6.x milestone Feb 25, 2025
@grynspan grynspan self-assigned this Feb 25, 2025
@grynspan
Copy link
Contributor Author

@swift-ci test

@grynspan
Copy link
Contributor Author

@swift-ci test

Copy link
Contributor

@stmontgomery stmontgomery left a comment

Choose a reason for hiding this comment

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

Overall I like these refinements! Several specific comments

ExitTests/SpawnProcess.swift
ExitTests/StatusAtExit.swift
Copy link
Contributor

Choose a reason for hiding this comment

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

You mentioned in the PR description this type may be used independently of exit tests, so I'm wondering if the file ought to be placed in a different directory to emphasize that.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It can move, but the code is already in this directory so for now I was planning to leave it there. Do you feel strongly?

@grynspan
Copy link
Contributor Author

@swift-ci test

@grynspan grynspan merged commit 44022f4 into main Feb 28, 2025
3 checks passed
@grynspan grynspan deleted the jgrynspan/rename-exit-test-symbols branch February 28, 2025 18:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request exit-tests ☠️ Work related to exit tests public-api Affects public API
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants