src/doc/rust-by-example/src/testing/integration_testing.md

   1 # Integration testing
   2
   3 [Unit tests][unit] are testing one module in isolation at a time: they're small
   4 and can test private code. Integration tests are external to your crate and use
   5 only its public interface in the same way any other code would. Their purpose is
   6 to test that many parts of your library work correctly together.
   7
   8 Cargo looks for integration tests in `tests` directory next to `src`.
   9
  10 File `src/lib.rs`:
  11
  12 ```rust,ignore
  13 // Define this in a crate called `adder`.
  14 pub fn add(a: i32, b: i32) -> i32 {
  15     a + b
  16 }
  17 ```
  18
  19 File with test: `tests/integration_test.rs`:
  20
  21 ```rust,ignore
  22 #[test]
  23 fn test_add() {
  24     assert_eq!(adder::add(3, 2), 5);
  25 }
  26 ```
  27
  28 Running tests with `cargo test` command:
  29
  30 ```shell
  31 $ cargo test
  32 running 0 tests
  33
  34 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
  35
  36      Running target/debug/deps/integration_test-bcd60824f5fbfe19
  37
  38 running 1 test
  39 test test_add ... ok
  40
  41 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
  42
  43    Doc-tests adder
  44
  45 running 0 tests
  46
  47 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
  48 ```
  49
  50 Each Rust source file in `tests` directory is compiled as a separate crate. One
  51 way of sharing some code between integration tests is making module with public
  52 functions, importing and using it within tests.
  53
  54 File `tests/common.rs`:
  55
  56 ```rust,ignore
  57 pub fn setup() {
  58     // some setup code, like creating required files/directories, starting
  59     // servers, etc.
  60 }
  61 ```
  62
  63 File with test: `tests/integration_test.rs`
  64
  65 ```rust,ignore
  66 // importing common module.
  67 mod common;
  68
  69 #[test]
  70 fn test_add() {
  71     // using common code.
  72     common::setup();
  73     assert_eq!(adder::add(3, 2), 5);
  74 }
  75 ```
  76
  77 Modules with common code follow the ordinary [modules][mod] rules, so it's ok to
  78 create common module as `tests/common/mod.rs`.
  79
  80 [unit]: unit_testing.md
  81 [mod]: ../mod.md