squiid/rust
1
0
Fork 0
Code Issues Pull requests Projects Activity

Add a brief overview of rustfmt tests

Browse source
This commit is contained in:
Marcus Klaas 2015-10-22 23:51:19 +02:00
parent 58ff0d8730
commit be77f8a277
2 changed files with 45 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
Contributing.md
View file

@ -6,7 +6,8 @@ It would be really useful to have people use rustfmt on their projects and file
issues where it does something you don't expect.
A really useful thing to do that on a crate from the Rust repo. If it does
something unexpected, file an issue; if not, make a PR to the Rust repo with the reformatted code. I hope to get the whole repo consistently rustfmt'ed and to
something unexpected, file an issue; if not, make a PR to the Rust repo with the
reformatted code. We hope to get the whole repo consistently rustfmt'ed and to
replace `make tidy` with rustfmt as a medium-term goal.
### Create test cases
@ -14,6 +15,36 @@ replace `make tidy` with rustfmt as a medium-term goal.
Having a strong test suite for a tool like this is essential. It is very easy
to create regressions. Any tests you can add are very much appreciated.
The tests can be run with `cargo test`. This does a number of things:
* runs the unit tests for a number of internal functions;
* makes sure that rustfmt run on every file in `./tests/source/` is equal to its
associated file in `./tests/target/`;
* runs idempotence tests on the files in `./tests/target/`. These files should
not be changed by rustfmt;
* checks that rustfmt's code is not changed by running on itself. This ensures
that the project bootstraps.
Creating a test is as easy as creating a new file in `./tests/source/` and an
equally named one in `./tests/target/`. If it is only required that rustfmt
leaves a piece of code unformatted, it may suffice to only create a target file.
Whenever there's a discrepancy between the expected output when running tests, a
colourised diff will be printed so that the offending line(s) can quickly be
identified.
Without explicit settings, the tests will be run using rustfmt's default
configuration. It is possible to run a test using non-default settings by
including configuration parameters in comments at the top of the file. For
example: to use 3 spaces per tab, start your test with
`// rustfmt-tab_spaces: 3`. Just remember that the comment is part of the input,
so include in both the source and target files! It is also possible to
explicitly specify the name of the expected output file in the target directory.
Use `// rustfmt-target: filename.rs` for this. Finally, you can use a custom
configuration by using the `rustfmt-config` directive. Rustfmt will then use
that toml file located in `./tests/config/` for its configuration. Including
`// rustfmt-config: small_tabs.toml` will run your test with the configuration
file found at `./tests/config/small_tabs.toml`.
### Hack!
Here are some [good starting issues](https://github.com/nrc/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Aeasy).

24
README.md
View file

@ -9,9 +9,10 @@ A tool for formatting Rust code according to style guidelines.
#[rustfmt_skip]
#[cfg_attr(rustfmt, rustfmt_skip)]
```
* When you run rustfmt use a file called rustfmt.toml to override the default
settings of rustfmt.
* We create a functioning executable called `rustfmt` in the target directory
* When you run rustfmt, place a file named rustfmt.toml in target file
directory or its parents to override the default settings of rustfmt.
* After successful compilation, a `rustfmt` executable can be found in the
target directory.
## Installation
@ -36,15 +37,16 @@ First make sure you've got Rust **1.3.0** or greater available, then:
`cargo test` to run all tests.
`cargo run -- filename` to run on a file, if the file includes out of line modules,
then we reformat those too. So to run on a whole module or crate, you just need
to run on the top file.
`cargo run -- filename` to run on a file, if the file includes out of line
modules, then we reformat those too. So to run on a whole module or crate, you
just need to run on the top file.
You'll probably want to specify the write mode. Currently, there are the replace,
overwrite and display mode. The replace mode is the default and overwrites the
original files after renaming them. In overwrite mode, rustfmt does not backup
the source files. To print the output to stdout, use the display mode. The write
mode can be set by passing the `--write-mode` flag on the command line.
You'll probably want to specify the write mode. Currently, there are the
replace, overwrite, display and coverage modes. The replace mode is the default
and overwrites the original files after renaming them. In overwrite mode,
rustfmt does not backup the source files. To print the output to stdout, use the
display mode. The write mode can be set by passing the `--write-mode` flag on
the command line.
`cargo run -- filename --write-mode=display` prints the output of rustfmt to the
screen, for example.