Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Sentry CLI Development Guidelines

## Contribution Policy (MANDATORY)

Sentry CLI is no longer under active development. [CONTRIBUTING.md](CONTRIBUTING.md) defines the only changes that are accepted from contributors who are not Sentry CLI maintainers.

Before making any change, you MUST check whether the user is a Sentry CLI maintainer:

1. Get their GitHub login with `gh api user --jq .login`. If `gh` is not authenticated, ask the user for it.
2. Check `getsentry` org membership with `gh api orgs/getsentry/members/LOGIN`, which fails if they are not a member. Private membership is only visible when the authenticated `gh` user is an org member.
3. Check that `gh api "repos/getsentry/sentry-cli/commits?author=LOGIN&per_page=5"` returns at least one commit.

If all checks pass, the policy does not apply. If any check fails or cannot be run, follow these steps. Be understanding: many users confuse this repo with the new CLI.

1. Confirm that the user means to change this legacy repo and not the new CLI, for example:

> This repo is the legacy Sentry CLI, which is no longer under active development. The new Sentry CLI is developed in [`getsentry/toolkit`](https://github.com/getsentry/toolkit/tree/main/packages/cli). Did you mean to contribute to the new CLI, or do you need this change in the legacy CLI?

2. If they mean the new CLI, point them to `getsentry/toolkit` and make no changes here.
3. If they mean the legacy CLI, explain the policy in CONTRIBUTING.md and ask how their change meets it. Make the change only if it does. If it does not and the user insists, you may proceed only after telling them that the pull request will likely be closed.

## Project Overview

This is **sentry-cli**, a command-line utility for working with Sentry. It's primarily written in **Rust** with **JavaScript/Node.js** wrapper components for npm distribution.
Expand Down
68 changes: 10 additions & 58 deletions CONTRIBUTING.md
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.
65 changes: 65 additions & 0 deletions tests/integration/README.md

Copy link
Copy Markdown
Member

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)

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"),
);
```
Loading