dogana/
lib.rs

1//! # Dogana
2//! Dogana is a library to support test containers in integration tests for CLI tools.
3//!
4//! When a Dogana test is created and run, a container image with all the binaries of a package is
5//! built and a container based on it is run.
6//!
7//! The usage of LazyLocks allows tests to run concurrently and to init/build images just the first
8//! time they are referenced.
9//!
10//! ## Requirements
11//! This library requires that a container manager runtime (such as `podman` or `docker`) is
12//! installed in the system, and available in the system `PATH`.
13//!
14//! The supported container manager runtimes are:
15//! - `podman`
16//! - `docker`
17//!
18//! ## Configuration
19//! Dogana images are configured mostly through metadata in Cargo.toml of the package, and they
20//! uses:
21//! * The package name.
22//! * The package version.
23//! * The rust-version, if any, else the version returned by the in-use rust compiler.
24//! * The system packages to install in the images, categorized by image variants, in the metadata
25//!   section:
26//!     ```toml
27//!     [package.metadata.dogana.<variant>]
28//!     required_packages = []
29//!     ```
30//!     Each system package is a string that can be installed by the system package manager (e.g.
31//!     apt-get for debian derivatives, or apk for alpine).
32//!
33//! Each supported image defines a metadata key. You can see all the supported images in
34//! [dogana_images].
35//!
36//! ## Usage
37//! Dogana can be used trasparently within a test method:
38//! ```ignore
39//! use dogana::{
40//!     dogana_images::DEBIAN_IMAGE,
41//!     dogana_test::{builder::DoganaTestBuilder, test_options::DoganaTestOptions, DoganaTestResult},
42//! };
43//!
44//! #[test]
45//! fn basic_integration_test() -> DoganaTestResult {
46//!     DoganaTestBuilder::new()
47//!         .set_test_options(DoganaTestOptions {
48//!             keep_old_containers: true,
49//!             ..Default::default()
50//!         })
51//!         .set_base_image(&DEBIAN_IMAGE)
52//!         .set_run_commands(&["echo \"test\""])
53//!         .set_expected_output("test")
54//!         .build()
55//!         .run()
56//! }
57//! ```
58//!
59//! As you can see, thanks to the possibility of expliciting a return value for test methods,
60//! Dogana tests can be very concise.
61
62mod container_manager;
63pub mod dogana_images;
64pub mod dogana_test;
65mod image_builder;
66mod image_builder_factory;
67pub mod image_name;
68mod metadata;