Home Explore Blog CI



rustc

2nd chunk of `src/tests/adding.md`
354b8186df0aaadce0d478f78491f849fd6afae8d86e52b0000000010000096f
- The top should start with a short comment that [explains what the test is
  for](#explanatory_comment).
- The `//@ edition:2018` comment is called a [directive](directives.md) which
  provides instructions to compiletest on how to build the test. Here we need to
  set the edition for `async` to work (the default is edition 2015).
- Following that is the source of the test. Try to keep it succinct and to the
  point. This may require some effort if you are trying to minimize an example
  from a bug report.
- We end this test with an empty `fn main` function. This is because the default
  for UI tests is a `bin` crate-type, and we don't want the "main not found"
  error in our test. Alternatively, you could add `#![crate_type="lib"]`.

### Step 2: Generate the expected output

The next step is to create the expected output snapshots from the compiler. This
can be done with the `--bless` option:

```sh
./x test tests/ui/async-await/await-without-async.rs --bless
```

This will build the compiler (if it hasn't already been built), compile the
test, and place the output of the compiler in a file called
`tests/ui/async-await/await-without-async.stderr`.

However, this step will fail! You should see an error message, something like
this:

> error: /rust/tests/ui/async-await/await-without-async.rs:7: unexpected
> error: '7:10: 7:16: `await` is only allowed inside `async` functions and
> blocks E0728'

This is because the stderr contains errors which were not matched by error
annotations in the source file.

### Step 3: Add error annotations

Every error needs to be annotated with a comment in the source with the text of
the error. In this case, we can add the following comment to our test file:

```rust,ignore
fn bar() {
    foo().await
    //~^ ERROR `await` is only allowed inside `async` functions and blocks
}
```

The `//~^` squiggle caret comment tells compiletest that the error belongs to
the *previous* line (more on this in the [Error
annotations](ui.md#error-annotations) section).

Save that, and run the test again:

```sh
./x test tests/ui/async-await/await-without-async.rs
```

It should now pass, yay!

### Step 4: Review the output

Somewhat hand-in-hand with the previous step, you should inspect the `.stderr`
file that was created to see if it looks like how you expect. If you are adding
a new diagnostic message, now would be a good time to also consider how readable

Title: Generating Expected Output and Adding Error Annotations in UI Tests
Summary
This section details the process of generating expected output snapshots for UI tests using the `--bless` option. It explains that the initial output generation may fail due to unmatched errors in the source file, necessitating the addition of error annotations. The use of squiggle caret comments (e.g., `//~^`) to associate errors with specific lines of code is demonstrated. After adding annotations, re-running the test should result in a pass. Finally, it emphasizes the importance of reviewing the generated `.stderr` file to ensure it matches expectations, particularly for new diagnostic messages.