Skip to content

Commit 6d1929c

Browse files
josecelanojosecelano
committed
Merge #291: Crate docs for test-helpers package
9e6e608 docs: [#280] crate docs for test-helpers package (Jose Celano) Pull request description: Documentation for the `test-helpers` package (`./package/test-helpers`). Top commit has no ACKs. Tree-SHA512: f7ed751101028aea3941274506d5ebb7e8a9491ca784dcb59841605c38afdca8c448fd0403db0b79bc4035eaead1738afb985a17d1594dab04f62f0aa90ea15b
2 parents bcf7f69 + 9e6e608 commit 6d1929c

3 files changed

Lines changed: 27 additions & 2 deletions

File tree

‎packages/test-helpers/src/configuration.rs‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
//! Tracker configuration factories for testing.
12
use std::env;
23
use std::net::IpAddr;
34

@@ -6,8 +7,17 @@ use torrust_tracker_primitives::TrackerMode;
67

78
use crate::random;
89

9-
/// This configuration is used for testing. It generates random config values so they do not collide
10-
/// if you run more than one tracker at the same time.
10+
/// This configuration is used for testing. It generates random config values
11+
/// so they do not collide if you run more than one tracker at the same time.
12+
///
13+
/// > **NOTICE**: This configuration is not meant to be used in production.
14+
///
15+
/// > **NOTICE**: Port 0 is used for ephemeral ports, which means that the OS
16+
/// will assign a random free port for the tracker to use.
17+
///
18+
/// > **NOTICE**: You can change the log level to `debug` to see the logs of the
19+
/// tracker while running the tests. That can be particularly useful when
20+
/// debugging tests.
1121
///
1222
/// # Panics
1323
///
@@ -46,6 +56,7 @@ pub fn ephemeral() -> Configuration {
4656
config
4757
}
4858

59+
/// Ephemeral configuration with reverse proxy enabled.
4960
#[must_use]
5061
pub fn ephemeral_with_reverse_proxy() -> Configuration {
5162
let mut cfg = ephemeral();
@@ -55,6 +66,7 @@ pub fn ephemeral_with_reverse_proxy() -> Configuration {
5566
cfg
5667
}
5768

69+
/// Ephemeral configuration with reverse proxy disabled.
5870
#[must_use]
5971
pub fn ephemeral_without_reverse_proxy() -> Configuration {
6072
let mut cfg = ephemeral();
@@ -64,6 +76,7 @@ pub fn ephemeral_without_reverse_proxy() -> Configuration {
6476
cfg
6577
}
6678

79+
/// Ephemeral configuration with `public` mode.
6780
#[must_use]
6881
pub fn ephemeral_mode_public() -> Configuration {
6982
let mut cfg = ephemeral();
@@ -73,6 +86,7 @@ pub fn ephemeral_mode_public() -> Configuration {
7386
cfg
7487
}
7588

89+
/// Ephemeral configuration with `private` mode.
7690
#[must_use]
7791
pub fn ephemeral_mode_private() -> Configuration {
7892
let mut cfg = ephemeral();
@@ -82,6 +96,7 @@ pub fn ephemeral_mode_private() -> Configuration {
8296
cfg
8397
}
8498

99+
/// Ephemeral configuration with `listed` mode.
85100
#[must_use]
86101
pub fn ephemeral_mode_whitelisted() -> Configuration {
87102
let mut cfg = ephemeral();
@@ -91,6 +106,7 @@ pub fn ephemeral_mode_whitelisted() -> Configuration {
91106
cfg
92107
}
93108

109+
/// Ephemeral configuration with `private_listed` mode.
94110
#[must_use]
95111
pub fn ephemeral_mode_private_whitelisted() -> Configuration {
96112
let mut cfg = ephemeral();
@@ -100,6 +116,7 @@ pub fn ephemeral_mode_private_whitelisted() -> Configuration {
100116
cfg
101117
}
102118

119+
/// Ephemeral configuration with a custom external (public) IP for the tracker.
103120
#[must_use]
104121
pub fn ephemeral_with_external_ip(ip: IpAddr) -> Configuration {
105122
let mut cfg = ephemeral();
@@ -109,6 +126,8 @@ pub fn ephemeral_with_external_ip(ip: IpAddr) -> Configuration {
109126
cfg
110127
}
111128

129+
/// Ephemeral configuration using a wildcard IPv6 for the UDP, HTTP and API
130+
/// services.
112131
#[must_use]
113132
pub fn ephemeral_ipv6() -> Configuration {
114133
let mut cfg = ephemeral();

‎packages/test-helpers/src/lib.rs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,5 @@
1+
//! Testing helpers for [Torrust Tracker](https://docs.rs/torrust-tracker).
2+
//!
3+
//! A collection of functions and types to help with testing the tracker server.
14
pub mod configuration;
25
pub mod random;

‎packages/test-helpers/src/random.rs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
1+
//! Random data generators for testing.
12
use rand::distributions::Alphanumeric;
23
use rand::{thread_rng, Rng};
34

45
/// Returns a random alphanumeric string of a certain size.
6+
///
7+
/// It is useful for generating random names, IDs, etc for testing.
58
pub fn string(size: usize) -> String {
69
thread_rng().sample_iter(&Alphanumeric).take(size).map(char::from).collect()
710
}

0 commit comments

Comments
 (0)