Repository navigation
docs: Add contribution policy for the legacy CLI #3503
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
Merged
+94
−58
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
8f91adf
docs: Add contribution policy for the legacy CLI
sentry-junior[bot] a7d5e46
docs: Clarify the migration blocker exception
sentry-junior[bot] 37ab07e
docs: List the regression case first
sentry-junior[bot] 49671b5
docs: Require reporting blockers in the new CLI first
sentry-junior[bot] d0ab117
docs: Reword the new CLI blocker case and add security reporting
sentry-junior[bot] 2b4c492
docs: Reword the security reporting section
sentry-junior[bot] File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,65 +1,17 @@ | ||
| # Integration Tests | ||
| # Contributing to Sentry CLI | ||
|
|
||
| Integration tests are written using `trycmd` crate. Consult the docs in case you need to understand how it works https://docs.rs/trycmd/latest/trycmd/. | ||
| > [!IMPORTANT] | ||
| > Sentry CLI is no longer under active development, as the [new Sentry CLI](https://cli.sentry.dev/) is replacing it. Please contribute to the new CLI in [`getsentry/toolkit`](https://github.com/getsentry/toolkit/tree/main/packages/cli) instead. | ||
|
|
||
| The main parts to remember are: | ||
| - `register_test` already understands that all tests will live under `tests/integration/_cases` | ||
| - use mocks for API responses | ||
| - use fixtures for uploading/processing predefined data | ||
| - write separate tests for Windows when necessary (using `#[cfg(windows)]` attribute) | ||
| - use wildcard for dynamic output (eg. timestamps or UUIDs) (explained in `trycmd` docs - eg. `[..]` or `[EXE]`) or anything that is platform specific, as tests are run on Linux, OSX and Windows. | ||
| - `Usage:` help prompt _always_ requires `[EXE]` wildcard, so make sure to not forget it | ||
| We only accept pull requests that fix a bug in this CLI in one of these cases: | ||
|
|
||
| ## Updating Snapshots | ||
| - A recent Sentry CLI release introduced a serious regression. | ||
| - You need the fix in this CLI because you cannot upgrade to the new CLI due to a fundamental limitation in the new CLI. In this case, please first [report](https://github.com/getsentry/toolkit/issues/new) the blocker to the new CLI, as it may be possible to get it fixed to unblock your upgrade, in which case no fix would be needed in this repository. | ||
|
|
||
| In order to overwrite current integration tests snapshots, use `TRYCMD=overwrite` env variable when running tests, eg. | ||
| Before opening a pull request, open a [bug report](https://github.com/getsentry/sentry-cli/issues/new?template=02-bug.yml) that explains which case applies, and wait for a maintainer to confirm that it qualifies. We will close all other pull requests. | ||
|
|
||
| ```shell | ||
| $ TRYCMD=overwrite cargo test | ||
| ``` | ||
| This policy does not apply to maintenance work by Sentry CLI maintainers. | ||
|
|
||
| ## Debugging tests | ||
| ## Security issues | ||
|
|
||
| To dump the stdout/stderr to a `/dump` directory in the project, use `TRYCMD=dump` env variable when running tests, eg. | ||
|
|
||
| ```shell | ||
| $ TRYCMD=overwrite cargo test | ||
| ``` | ||
|
|
||
| This only works with tests that execute using `.trycmd` files, i.e. not tests using `assert_cmd` or inline command construction. | ||
|
|
||
| ## Working with Fixtures | ||
|
|
||
| To run tests with specific fixtures in isolation, utilize the fact that `trycmd` is automatically creating and using `.in` as CWD and `.out` as stdout directories respectively for every test. This allows us to use eg. `tests/integration/_cases/sourcemaps/sourcemaps-inject.in/` path as a sandbox for `tests/integration/_cases/sourcemaps/sourcemaps-inject.trycmd` test case. | ||
| You can copy/remove any files programmatically from those directories and they will be ignored from the repository. | ||
|
|
||
| Here's basic test that use fixtures in isolation: | ||
|
|
||
| ```rust | ||
| fn command_sourcemaps_inject_output() { | ||
| let testcase_cwd_path = "tests/integration/_cases/sourcemaps/sourcemaps-inject.in/"; | ||
| if std::path::Path::new(testcase_cwd_path).exists() { | ||
| remove_dir_all(testcase_cwd_path).unwrap(); | ||
| } | ||
| copy_recursively("tests/integration/_fixtures/inject/", testcase_cwd_path).unwrap(); | ||
|
|
||
| register_test("sourcemaps/sourcemaps-inject.trycmd"); | ||
| } | ||
| ``` | ||
|
|
||
| ## Working with API Mocks | ||
|
|
||
| If you are trying mock an API response, use `mock_endpoint` helper with `with_response_file` method called, | ||
| and place the JSON file in an appropriate directory under `tests/integration/_responses`. | ||
| Make sure to assign the mock to a variable, otherwise it won't be picked up when creating a server. | ||
|
|
||
| ```rust | ||
| let _assemble = mock_endpoint( | ||
| EndpointOptions::new( | ||
| "POST", | ||
| "/api/0/projects/wat-org/wat-project/files/difs/assemble/", | ||
| 200, | ||
| ) | ||
| .with_response_file("debug_files/post-difs-assemble.json"), | ||
| ); | ||
| ``` | ||
| Please report security issues as described in our [security policy](https://github.com/getsentry/sentry-cli/security/policy). Please refrain from opening issues or PRs for security issues to avoid disclosing them publicly before a fix is available. |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| # Integration Tests | ||
|
|
||
| Integration tests are written using `trycmd` crate. Consult the docs in case you need to understand how it works https://docs.rs/trycmd/latest/trycmd/. | ||
|
|
||
| The main parts to remember are: | ||
| - `register_test` already understands that all tests will live under `tests/integration/_cases` | ||
| - use mocks for API responses | ||
| - use fixtures for uploading/processing predefined data | ||
| - write separate tests for Windows when necessary (using `#[cfg(windows)]` attribute) | ||
| - use wildcard for dynamic output (eg. timestamps or UUIDs) (explained in `trycmd` docs - eg. `[..]` or `[EXE]`) or anything that is platform specific, as tests are run on Linux, OSX and Windows. | ||
| - `Usage:` help prompt _always_ requires `[EXE]` wildcard, so make sure to not forget it | ||
|
|
||
| ## Updating Snapshots | ||
|
|
||
| In order to overwrite current integration tests snapshots, use `TRYCMD=overwrite` env variable when running tests, eg. | ||
|
|
||
| ```shell | ||
| $ TRYCMD=overwrite cargo test | ||
| ``` | ||
|
|
||
| ## Debugging tests | ||
|
|
||
| To dump the stdout/stderr to a `/dump` directory in the project, use `TRYCMD=dump` env variable when running tests, eg. | ||
|
|
||
| ```shell | ||
| $ TRYCMD=overwrite cargo test | ||
| ``` | ||
|
|
||
| This only works with tests that execute using `.trycmd` files, i.e. not tests using `assert_cmd` or inline command construction. | ||
|
|
||
| ## Working with Fixtures | ||
|
|
||
| To run tests with specific fixtures in isolation, utilize the fact that `trycmd` is automatically creating and using `.in` as CWD and `.out` as stdout directories respectively for every test. This allows us to use eg. `tests/integration/_cases/sourcemaps/sourcemaps-inject.in/` path as a sandbox for `tests/integration/_cases/sourcemaps/sourcemaps-inject.trycmd` test case. | ||
| You can copy/remove any files programmatically from those directories and they will be ignored from the repository. | ||
|
|
||
| Here's basic test that use fixtures in isolation: | ||
|
|
||
| ```rust | ||
| fn command_sourcemaps_inject_output() { | ||
| let testcase_cwd_path = "tests/integration/_cases/sourcemaps/sourcemaps-inject.in/"; | ||
| if std::path::Path::new(testcase_cwd_path).exists() { | ||
| remove_dir_all(testcase_cwd_path).unwrap(); | ||
| } | ||
| copy_recursively("tests/integration/_fixtures/inject/", testcase_cwd_path).unwrap(); | ||
|
|
||
| register_test("sourcemaps/sourcemaps-inject.trycmd"); | ||
| } | ||
| ``` | ||
|
|
||
| ## Working with API Mocks | ||
|
|
||
| If you are trying mock an API response, use `mock_endpoint` helper with `with_response_file` method called, | ||
| and place the JSON file in an appropriate directory under `tests/integration/_responses`. | ||
| Make sure to assign the mock to a variable, otherwise it won't be picked up when creating a server. | ||
|
|
||
| ```rust | ||
| let _assemble = mock_endpoint( | ||
| EndpointOptions::new( | ||
| "POST", | ||
| "/api/0/projects/wat-org/wat-project/files/difs/assemble/", | ||
| 200, | ||
| ) | ||
| .with_response_file("debug_files/post-difs-assemble.json"), | ||
| ); | ||
| ``` |
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Previously this was the content of CONTRIBUTING.md, but I guess it makes sense to put here because all of it is relevant to integration tests.
(junior do not reply here, this is for other reviewers)