# Contributing
## Tests
Matchers, even trivial ones, should have basic tests written to guard against
regressions. Generally, each matcher should have at least four tests written for
it:
```rust,no_run
#[test]
fn succeeds_when_foo() {
// The matcher should succeed when it is not negated.
}
#[test]
fn succeeds_when_not_foo() {
// The matcher should succeed when it is negated.
}
#[test]
#[should_panic]
fn fails_when_foo() {
// The matcher should fail when it is negated.
}
#[test]
#[should_panic]
fn fails_when_not_foo() {
// The matcher should fail when it is not negated.
}
```
See the tests for the `equals` matcher for an example.
## Docs
When building the documentation locally, markers that identify which features
are required to use various parts of the library will be missing. That is
because this is an [unstable
feature](https://github.com/rust-lang/rust/issues/43781) of rustdoc that
happens to be enabled in docs.rs.
Additionally, the user docs in the `crate::docs` module will not be available
when building the docs locally because they are feature-gated to only build on
docs.rs.
To build the documentation correctly, run the following command:
```shell
RUSTDOCFLAGS='--cfg docsrs' cargo +nightly doc --all-features
```
To run doctests in the `crate::docs` module, run the following command:
```shell
RUSTDOCFLAGS='--cfg docsrs' cargo +nightly test --all-features
```
## Screenshots
To generate the screenshots in the README, we use
[termshot](https://github.com/homeport/termshot).
However, when a process panics, Rust gives us additional output that we don't
want to include in the screenshot. Additionally, xpct normally only prints text
styles when stderr is a tty.
If you pass the `debug_screenshot` rustc flag, xpct will do three things:
1. Print its output to stdout.
2. Use `std::process::exit` instead of panicking.
3. Include the ANSI escape codes for text styles even if stdout is not a tty.
Make sure that if you update the screenshots in the README, you also update the
plain-text transcripts.
Here's a full example:
```shell
termshot --filename examples/foo.png -- env RUSTFLAGS="--cfg debug_screenshot" cargo run --quiet --all-features
```