doco-derive 0.2.3

A framework and runner for end-to-end tests for web applications
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

# 🦕 Doco

Doco is a framework and runner for end-to-end tests of web applications. It is
designed to be framework-agnostic and easy to use, both locally and in CI/CD
pipelines.

Tests are run in isolated, ephemeral environments using Docker containers. Doco
hides the complexities of setting up the test environment, configuring Selenium,
and managing the lifecycle of the containers.

## Usage

Doco looks and feels mostly like any other test framework in Rust. It provides
two macros, `#[doco::test]` and `#[doco::main]`, to define tests and configure
the test runner.

Start by adding Doco to your `Cargo.toml` as a custom test harness:

```toml
[[test]]
name = "e2e"
path = "e2e/main.rs"
harness = false
```

Then go ahead and create the `e2e` directory in the same directory as your
`Cargo.toml` and add a `main.rs` file. In this file, add the following snippet
and customize the server with your own Docker `image` and `tag` and the right
`port`:

```rust
use doco::{Doco, Server};

#[doco::main]
async fn main() -> Doco {
    let server = Server::builder()
        .image("image")
        .tag("tag")
        .port(3000)
        .build();

    Doco::builder().server(server).build()
}
```

Now you can write your first test. Either in a new file or in `main.rs`, add an
asynchronous function that takes a `Client` as its argument and returns a
`Result<()>`.

```rust
use doco::{Client, Result};

#[doco::test]
async fn reads_from_database(client: Client) -> Result<()> {
    client.goto("/").await?;

    let body = client.source().await?;

    assert!(body.contains("hello world from Doco"));

    Ok(())
}
```

Make sure to read the [API documentation](https://docs.rs/doco) for more
information, and check out the [examples](examples) directory for more examples.

## Limitations

Doco is still in an early stage of development and has some known limitations.
These will be addressed in future releases.

- Rust is the only supported language for writing tests.
- Each test must have a globally unique name.
- Errors from Docker are not reported properly yet.

## Test runner flags

Doco uses [libtest-mimic] under the hood, so it supports the standard test
runner flags you're used to:

- `<FILTER>` — only run tests whose name contains this string
- `--exact` — match test names exactly instead of by substring
- `--skip <FILTER>` — skip tests whose name contains this string
- `--ignored` — run only ignored tests
- `--include-ignored` — run both ignored and non-ignored tests
- `--list` — list all tests without running them
- `--quiet` / `-q` — display one character per test instead of one line
- `--test-threads <N>` — number of parallel test threads

[libtest-mimic]: https://crates.io/crates/libtest-mimic

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
  <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or
  <http://opensource.org/licenses/MIT>)

at your option.

## Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.