Escargot

https://docs.rs/escargot/0.5.15
Admin
Escargot is a Rust library providing a simple and efficient API for programmatically interacting...
Tokens:63,047
Snippets:522
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Build all examples

Source: https://docs.rs/escargot/0.5.15/src/escargot/build.rs.html

Configures the build to include all examples.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
escargot::CargoBuild::new()
    .examples()
    .manifest_path("tests/testsuite/fixtures/example/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### Build examples

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Configures the build to include all or specific examples.

```rust
escargot::CargoBuild::new()
    .examples()
    .manifest_path("tests/testsuite/fixtures/example/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

```rust
escargot::CargoBuild::new()
    .example("example_fixture")
    .manifest_path("tests/testsuite/fixtures/example/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### CargoBuild::examples()

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Configures the build to include all examples defined in the manifest.

```APIDOC
### pub fn examples(self) -> Self

#### Description
Build all examples

#### Example
```rust
escargot::CargoBuild::new()
    .examples()
    .manifest_path("tests/testsuite/fixtures/example/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```
```

--------------------------------

### CargoBuild::example()

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Configures the build to include only a specific example by name.

```APIDOC
### pub fn example<S: AsRef<OsStr>>(self, name: S) -> Self

#### Description
Build only `name` example.

#### Example
```rust
escargot::CargoBuild::new()
    .example("example_fixture")
    .manifest_path("tests/testsuite/fixtures/example/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```
```

--------------------------------

### Create CargoRun Instance

Source: https://docs.rs/escargot/0.5.15/src/escargot/run.rs.html

Use `CargoBuild::new()` to start building a `CargoRun` instance. Specify the binary or example to build, profile settings, manifest path, and target directory. The `run()` method compiles the artifact and returns a `CargoRun` object.

```rust
let run = escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap();
```

```rust
let run = escargot::CargoBuild::new()
    .example("example_fixture")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/example/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap();
```

--------------------------------

### Build a specific example

Source: https://docs.rs/escargot/0.5.15/src/escargot/build.rs.html

Configures the build to target a single named example.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
escargot::CargoBuild::new()
    .example("example_fixture")
    .manifest_path("tests/testsuite/fixtures/example/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### From Implementation Example

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.SuiteStarted.html

Shows the basic 'from' conversion where an argument is returned unchanged.

```rust
fn from(t: T) -> T
```

--------------------------------

### Into Implementation Example

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.SuiteStarted.html

Illustrates the 'into' conversion, which calls the 'From<T> for U' implementation.

```rust
fn into(self) -> U
```

--------------------------------

### Creating a CargoRun Instance

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoRun.html

Example demonstrating how to create a `CargoRun` instance using `CargoBuild::new()` and various configuration methods.

```APIDOC
## Example: Creating a CargoRun

To create a `CargoRun`:
```rust
let run = escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap();
println!("artifact={}", run.path().display());
```

See `CargoRun::path` for how to then run the newly compiled program.
```

--------------------------------

### CloneToUninit Implementation Example

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.SuiteStarted.html

Demonstrates the nightly-only experimental API for performing copy-assignment from self to a mutable pointer destination.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### Deserialize suite started event

Source: https://docs.rs/escargot/0.5.15/src/escargot/format/test.rs.html

Parses a suite started event JSON string into an Event object.

```rust
        let input = r#"{ "type": "suite", "event": "started", "test_count": 10 }"#;
        let _data: Event = serde_json::from_str(input).unwrap();
    }
```

--------------------------------

### TryFrom Implementation Example

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.SuiteStarted.html

Defines the error type for conversion failures and the 'try_from' method for attempting conversions.

```rust
type Error = Infallible
```

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

--------------------------------

### TryInto Implementation Example

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.SuiteStarted.html

Defines the error type for conversion failures and the 'try_into' method for attempting conversions.

```rust
type Error = <U as TryFrom<T>>::Error
```

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### Rust SuiteStarted Struct

Source: https://docs.rs/escargot/0.5.15/src/escargot/format/test.rs.html

Details about a test suite starting, including the total number of test cases.

```rust
/// Suite-started event.
#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct SuiteStarted {
    /// Number of test cases in the suite.
    pub test_count: usize,
}
```

--------------------------------

### Initialize Cargo Command

Source: https://docs.rs/escargot/0.5.15/src/escargot/cargo.rs.html

Creates a new top-level Cargo command. Use this as a starting point for building custom Cargo commands.

```rust
use std::env;
use std::ffi;
use std::process;
use std::str;

use crate::build::CargoBuild;

/// The current process' target triplet.
pub const CURRENT_TARGET: &str = include_str!(concat!(env!("OUT_DIR"), "/current_target.txt"));

fn cargo_bin() -> &'static ffi::OsStr {
    static CARGO_BIN: std::sync::OnceLock<ffi::OsString> = std::sync::OnceLock::new();
    CARGO_BIN.get_or_init(|| env::var_os("CARGO").unwrap_or_else(|| "cargo".into()))
}

/// Top-level command.
#[derive(Debug)]
pub struct Cargo {
    cmd: process::Command,
}

impl Cargo {
    /// Create a top-level command.
    pub fn new() -> Self {
        Self {
            cmd: process::Command::new(cargo_bin()),
        }
    }

    /// Manually pass an argument that is unsupported.
    ///
    /// Caution: Passing in a sub-command or `--` can throw off the API.
    pub fn arg<S: AsRef<ffi::OsStr>>(mut self, arg: S) -> Self {
        self.cmd.arg(arg);
        self
    }

    /// Manually pass arguments that are unsupported.
    ///
    /// Caution: Passing in a sub-command or `--` can throw off the API.
    pub fn args<I: IntoIterator<Item = S>, S: AsRef<ffi::OsStr>>(mut self, args: I) -> Self {
        self.cmd.args(args);
        self
    }

    /// Run the `build` subcommand.
    pub fn build(self) -> CargoBuild {
        self.build_with("build")
    }

    /// Run a custom `build` subcommand.
    pub fn build_with<S: AsRef<ffi::OsStr>>(mut self, name: S) -> CargoBuild {
        self.cmd.arg(name).arg("--message-format=json");
        CargoBuild::with_command(self.cmd)
    }

    /// Return the underlying [`process::Command`]
    pub fn into_command(self) -> process::Command {
        self.cmd
    }
}

impl Default for Cargo {
    fn default() -> Self {
        Self::new()
    }
}
```

--------------------------------

### Handling File Metadata Operations

Source: https://docs.rs/escargot/0.5.15/escargot/error/type.CargoResult.html

Illustrates using `and_then` for operations that might fail, such as retrieving file metadata. This example shows how to handle potential `NotFound` errors.

```APIDOC
## GET /api/users/{id}

### Description
Retrieves the details of a specific user based on their unique identifier.

### Method
GET

### Endpoint
/api/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the user to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the user.
- **username** (string) - The username of the user.
- **email** (string) - The email address of the user.

#### Response Example
```json
{
  "id": "user-12345",
  "username": "johndoe",
  "email": "john.doe@example.com"
}
```
```

--------------------------------

### TestStarted Struct

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.TestStarted.html

Represents a test case start event. Available only with the 'test_unstable' feature flag.

```APIDOC
## Struct TestStarted

### Description
Case-started event.

### Available On
Crate feature `test_unstable` only.

### Fields
This struct is marked as non-exhaustive, meaning additional fields may be added in the future. Non-exhaustive structs cannot be constructed using the traditional `Struct { .. }` syntax, matched against without a wildcard `..`, or used with struct update syntax.

- **name** (String) - Required - Test case name.
```

--------------------------------

### Rust TestStarted Struct

Source: https://docs.rs/escargot/0.5.15/src/escargot/format/test.rs.html

Represents the start of a test case, including its name.

```rust
/// Case-started event.
#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct TestStarted {
    /// Test case name.
    pub name: String,
}
```

--------------------------------

### Verify test count

Source: https://docs.rs/escargot/0.5.15/src/escargot/test.rs.html

Example of verifying the number of test artifacts produced by a build.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
let run: Vec<_> = escargot::CargoBuild::new()
    .tests()
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/test/Cargo.toml")
    .target_dir(target_dir.path())
    .run_tests()
    .unwrap()
    .collect();
assert_eq!(run.len(), 3);
```

--------------------------------

### Rust Test Module

Source: https://docs.rs/escargot/0.5.15/src/escargot/format/test.rs.html

Contains tests for the event formats, including a test for the suite started event.

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn suite_started() {

```

--------------------------------

### ToOwned Implementation Example

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.SuiteStarted.html

Provides methods for creating owned data from borrowed data, typically by cloning, and for replacing owned data with borrowed data.

```rust
type Owned = T
```

```rust
fn to_owned(&self) -> T
```

```rust
fn clone_into(&self, target: &mut T)
```

--------------------------------

### CargoRun Struct and Methods

Source: https://docs.rs/escargot/0.5.15/src/escargot/run.rs.html

Details on the CargoRun struct, which represents a compiled Rust binary or example, and its methods for accessing the artifact path and creating a command to execute it.

```APIDOC
## CargoRun

### Description
Represents a compiled Rust binary or example, providing access to its path and the ability to spawn a command to run it.

### Methods

#### `path(&self) -> &path::Path`

- **Description**: Returns the absolute path to the compiled binary artifact.
- **Example**:
```rust
# let target_dir = tempfile::TempDir::new().unwrap();
let run = escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap();
println!("artifact={}", run.path().display());
```

#### `command(&self) -> process::Command`

- **Description**: Creates a `std::process::Command` that can be used to execute the compiled binary.
- **Example**:
```rust,no_run
# let target_dir = tempfile::TempDir::new().unwrap();
let run = escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap()
    .command()
    .arg("--help")
    .status()
    .unwrap();
```
```

--------------------------------

### Deserialize test started event

Source: https://docs.rs/escargot/0.5.15/src/escargot/format/test.rs.html

Parses a test started event JSON string into an Event object.

```rust
    #[test]
    fn test_started() {
        let input = r#"{ "type": "test", "event": "started", "name": "foo" }"#;
        let _data: Event = serde_json::from_str(input).unwrap();
    }
```

--------------------------------

### Run a built binary

Source: https://docs.rs/escargot/0.5.15/src/escargot/build.rs.html

Shows how to build and run a binary target using the run method.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
let run = escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap();
println!("artifact={}", run.path().display());
```

--------------------------------

### Execute a Cargo Build

Source: https://docs.rs/escargot/0.5.15/src/escargot/build.rs.html

Demonstrates building a specific binary with release and target configurations.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### Build all binaries

Source: https://docs.rs/escargot/0.5.15/src/escargot/build.rs.html

Configures the build to include all binaries defined in the manifest.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
escargot::CargoBuild::new()
    .bins()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### CargoBuild::run()

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Executes the configured Cargo build command and provides a proxy for running the built target.

```APIDOC
### pub fn run(self) -> CargoResult<CargoRun>

#### Description
Provide a proxy for running the built target.

#### Example
```rust
let run = escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap();
println!("artifact={}", run.path().display());
```
```

--------------------------------

### Struct Target

Source: https://docs.rs/escargot/0.5.15/escargot/format/struct.Target.html

Represents a single target (lib, bin, example, etc.) provided by a Rust crate.

```APIDOC
## Struct Target

### Description
A single target (lib, bin, example, …) provided by a crate.

### Fields (Non-exhaustive)
This struct is marked as non-exhaustive, meaning additional fields may be added in future versions.

- **name** (Cow<'a, str>) - Name as given in the `Cargo.toml` or generated from the file name.
- **kind** (Vec<Cow<'a, str>>) - Kind of target ("bin", "example", "test", "bench", "lib").
- **crate_types** (Vec<Cow<'a, str>>) - Similar to `kind`, but includes specifics like `rlib` and `dylib` when an example is a library.
- **doctest** (Option<bool>) - Whether this target is a doctest.
- **doc** (Option<bool>) - Whether this target is documentation.
- **test** (bool) - Whether this target is a test file.
- **required_features** (Vec<Cow<'a, str>>) - Features that must be enabled for this target to be built (does not apply to `lib` targets).
- **src_path** (Cow<'a, str>) - Path to the main source file of the target.
- **edition** (Cow<'a, str>) - Rust edition for this target.

### Trait Implementations

- **Clone**: Provides methods for cloning `Target` instances.
  - `clone(&self) -> Target<'a>`: Returns a duplicate of the value.
  - `clone_from(&mut self, source: &Self)`: Performs copy-assignment from `source`.
- **Debug**: Allows formatting `Target` for debugging.
  - `fmt(&self, f: &mut Formatter<'_>) -> Result`: Formats the value using the given formatter.
- **Deserialize**: Enables deserialization of `Target` from Serde data formats.
  - `deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>`: Deserializes this value from the given Serde deserializer.
- **PartialEq**: Enables comparison of `Target` instances for equality.
  - `eq(&self, other: &Target<'a>) -> bool`: Tests for equality.
  - `ne(&self, other: &Rhs) -> bool`: Tests for inequality.
- **Serialize**: Enables serialization of `Target` to Serde data formats.
  - `serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>`: Serializes this value into the given Serde serializer.
- **Eq**: Marker trait indicating total equality.

### Auto Trait Implementations

- **Freeze**, **RefUnwindSafe**, **Send**, **Sync**, **Unpin**, **UnwindSafe**
```

--------------------------------

### CargoBuild::run()

Source: https://docs.rs/escargot/0.5.15/src/escargot/run.rs.html

Initiates the build process for a Rust project and returns a CargoRun instance if successful.

```APIDOC
## POST /build/run

### Description
Builds a Rust project's binary or example and returns a `CargoRun` object. This method is part of the `CargoBuild` struct and is used to compile and prepare an artifact for execution.

### Method
`CargoBuild::run()`

### Parameters
This method is called on a `CargoBuild` instance which is configured with various options such as:
- `.bin(name: &str)`: Specifies the binary to build.
- `.example(name: &str)`: Specifies the example to build.
- `.current_release()`: Configures the build for release mode.
- `.current_target()`: Configures the build for the current target triple.
- `.manifest_path(path: &str)`: Sets the path to the Cargo.toml file.
- `.target_dir(path: &path::Path)`: Specifies the directory for build artifacts.

### Request Example
```rust
# let target_dir = tempfile::TempDir::new().unwrap();
let run = escargot::CargoBuild::new()
    .bin("my_binary")
    .manifest_path("path/to/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap();
```

### Response
#### Success Response (200)
- **CargoRun** (`CargoRun`) - An instance of `CargoRun` representing the compiled artifact.

#### Response Example
```rust
# let target_dir = tempfile::TempDir::new().unwrap();
let run = escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap();
println!("artifact={}", run.path().display());
```
```

--------------------------------

### Build binaries

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Configures the build to include all or specific binaries.

```rust
escargot::CargoBuild::new()
    .bins()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

```rust
escargot::CargoBuild::new()
    .bin("bin")
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### Run tests with CargoBuild

Source: https://docs.rs/escargot/0.5.15/src/escargot/test.rs.html

Demonstrates how to initiate a test run using CargoBuild and access the resulting artifact path.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
let run = escargot::CargoBuild::new()
    .test("test")
    .manifest_path("tests/testsuite/fixtures/test/Cargo.toml")
    .target_dir(target_dir.path())
    .run_tests().unwrap()
    .next().unwrap().unwrap();
println!("artifact={}", run.path().display());
```

--------------------------------

### run_tests Method

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Provides a proxy for running the built target. This method is available on the `test_unstable` crate feature only and requires the `test_unstable` feature due to parsing unstable formats.

```APIDOC
## POST /run_tests

### Description
Provides a proxy for running the built target.

### Method
POST

### Endpoint
/run_tests

### Parameters
#### Query Parameters
- **feature** (string) - Optional - Specifies the crate feature to use, e.g., `test_unstable`.

### Request Body
This method does not require a request body.

### Response
#### Success Response (200)
- **Iterator<Item = CargoResult<CargoTest>>** - An iterator yielding results of test executions.

#### Response Example
```json
{
  "artifact": "/path/to/test/artifact"
}
```

### Example
```rust
let run = escargot::CargoBuild::new()
    .test("test")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/test/Cargo.toml")
    .target_dir(target_dir.path())
    .run_tests().unwrap()
    .next().unwrap().unwrap();
println!("artifact={}", run.path().display());
```
```

--------------------------------

### CargoBuild Configuration and Execution

Source: https://docs.rs/escargot/0.5.15/src/escargot/build.rs.html

This section details the methods for configuring and executing Cargo build commands, including setting the target, manifest path, and build profile.

```APIDOC
## POST /api/build

### Description
Configures and executes a Cargo build command.

### Method
POST

### Endpoint
/api/build

### Parameters
#### Query Parameters
- **manifest_path** (string) - Optional - Path to the Cargo.toml file.
- **target_dir** (string) - Optional - Directory for build artifacts.
- **release** (boolean) - Optional - Build in release mode.
- **features** (string) - Optional - Space-separated list of features to activate.
- **all_features** (boolean) - Optional - Activate all available features.
- **no_default_features** (boolean) - Optional - Do not activate the default feature.
- **target** (string) - Optional - Build for the specified target triplet.

### Request Body
```json
{
  "bin": "string",
  "example": "string",
  "test": "string",
  "args": ["string"]
}
```

### Response
#### Success Response (200)
- **CommandMessages** (object) - Compiler messages from the build process.

#### Response Example
```json
{
  "messages": [
    {
      "reason": "compiler-message",
      "package_id": "my_package 0.1.0",
      "compiler": "rustc 1.50.0",
      "message": {
        "message": "cannot find function `foobar` in crate `my_crate`",
        "code": {
          "code": "E0599",
          "explanation": null
        },
        "level": "error",
        "spans": [
          {
            "file_name": "src/main.rs",
            "byte_start": 10,
            "byte_end": 16,
            "line_start": 5,
            "line_end": 5,
            "is_primary": true,
            "text": [
              {
                "text": "foobar()",
                "highlight_start": 10,
                "highlight_end": 16
              }
            ],
            "label": null,
            "suggested_replacement": null,
            "suggestion_applicability": null,
            "expansion": null
          }
        ],
        "rendered": null
      },
      "links": null
    }
  ]
}
```
```

--------------------------------

### Unwrap Result Value

Source: https://docs.rs/escargot/0.5.15/escargot/error/type.CargoResult.html

Use `unwrap` to get the contained `Ok` value. Panics if the `Result` is `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.unwrap(); // panics with `emergency failure`
```

--------------------------------

### Get Nth Iterator Element

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CommandMessages.html

Returns the nth element of the iterator. Note that this consumes elements up to n.

```rust
fn nth(&mut self, n: usize) -> Option<Self::Item>
```

--------------------------------

### CargoBuild::all_features()

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Activates all available features for the build.

```APIDOC
### pub fn all_features(self) -> Self

#### Description
Activate all available features
```

--------------------------------

### Get Last Iterator Element

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CommandMessages.html

Consumes the iterator and returns the last element, or None if the iterator was empty.

```rust
fn last(self) -> Option<Self::Item>
where Self: Sized,
```

--------------------------------

### Create a CargoBuild instance

Source: https://docs.rs/escargot/0.5.15/src/escargot/build.rs.html

Initializes a new CargoBuild builder instance.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
escargot::CargoBuild::new()
    .bin("bin")
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### Execute build artifact with command

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoRun.html

Use the command method to obtain a Command object for executing the build artifact.

```rust
let run = escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap()
    .command()
    .arg("--help")
    .status()
    .unwrap();
```

```rust
let run = escargot::CargoBuild::new()
    .example("example_fixture")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/example/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap()
    .command()
    .arg("--help")
    .status()
    .unwrap();
```

--------------------------------

### CargoBuild::into_command()

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Converts the CargoBuild configuration into a standard `process::Command`.

```APIDOC
### pub fn into_command(self) -> Command

#### Description
Return the underlying `process::Command`.
```

--------------------------------

### Advance Iterator and Get Next Value

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CommandMessages.html

Advances the iterator and returns the next value. Returns None if the iterator is exhausted.

```rust
fn next(&mut self) -> Option<CargoResult<Message>>
```

--------------------------------

### fn try_into

Source: https://docs.rs/escargot/0.5.15/escargot/format/diagnostic/struct.Diagnostic.html

Documentation for the try_into conversion method.

```APIDOC
## fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

### Description
Performs the conversion from the current type to the target type U.

### Returns
- Result<U, <U as TryFrom<T>>::Error> - The result of the conversion.
```

--------------------------------

### Build all tests

Source: https://docs.rs/escargot/0.5.15/src/escargot/build.rs.html

Configures the build to include all tests.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
escargot::CargoBuild::new()
    .tests()
    .manifest_path("tests/testsuite/fixtures/test/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### Into Err Value (Nightly)

Source: https://docs.rs/escargot/0.5.15/escargot/error/type.CargoResult.html

Use `into_err` to get the contained `Err` value. This method is guaranteed not to panic and can be used as a compile-time safeguard.

```rust
fn only_bad_news() -> Result<!, String> {
    Err("Oops, it failed".into())
}

let error: String = only_bad_news().into_err();
println!("{error}");
```

--------------------------------

### CargoBuild::new()

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Creates a new instance of the CargoBuild struct, initializing the `build` subcommand.

```APIDOC
### pub fn new() -> Self

#### Description
Shortcut to create a `build` subcommand.
See also `Cargo`.

#### Example
```rust
escargot::CargoBuild::new()
    .bin("bin")
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```
```

--------------------------------

### Into Ok Value (Nightly)

Source: https://docs.rs/escargot/0.5.15/escargot/error/type.CargoResult.html

Use `into_ok` to get the contained `Ok` value. This method is guaranteed not to panic and can be used as a compile-time safeguard.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### Execute a cargo build

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Configures and executes a build command using the fluent API.

```rust
escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

```rust
escargot::CargoBuild::new()
    .bin("bin")
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### Get Iterator Size Hint

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CommandMessages.html

Returns the lower and upper bounds of the remaining elements in the iterator. The upper bound is None if it is not known.

```rust
fn size_hint(&self) -> (usize, Option<usize>)
```

--------------------------------

### Create a CargoRun instance

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoRun.html

Initialize a CargoRun instance using CargoBuild to configure and run the build process.

```rust
let run = escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap();
println!("artifact={}", run.path().display());
```

--------------------------------

### Retrieve binary path from CargoRun

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoRun.html

Use the path method to get the location of the compiled binary, supporting alternative execution methods.

```rust
let run = escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap();
println!("artifact={}", run.path().display());
```

```rust
let run = escargot::CargoBuild::new()
    .example("example_fixture")
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/example/Cargo.toml")
    .target_dir(target_dir.path())
    .run()
    .unwrap();
println!("artifact={}", run.path().display());
```

--------------------------------

### Unwrap or Default Value

Source: https://docs.rs/escargot/0.5.15/escargot/error/type.CargoResult.html

Use `unwrap_or_default` to get the contained `Ok` value or a default value if `Err`. Requires the type to implement `Default`.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

--------------------------------

### Run tests with CargoTest

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoTest.html

Demonstrates initializing a test run using CargoBuild and accessing the resulting artifact path.

```rust
let run = escargot::CargoBuild::new()
    .test("test")
    .manifest_path("tests/testsuite/fixtures/test/Cargo.toml")
    .target_dir(target_dir.path())
    .run_tests().unwrap()
    .next().unwrap().unwrap();
println!("artifact={}", run.path().display());
```

--------------------------------

### Any Trait Implementation

Source: https://docs.rs/escargot/0.5.15/escargot/format/struct.Target.html

Provides the ability to get the TypeId of a value, useful for dynamic type checking. This is a blanket implementation for any type T that is 'static and sized.

```rust
impl<T> Any for T
where T: 'static + ?Sized,

fn type_id(&self) -> TypeId
```

--------------------------------

### Implement CloneToUninit (Nightly)

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.TestIgnored.html

Nightly-only experimental API for performing copy-assignment from `self` to an uninitialized destination. Requires `T: Clone`.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8) {
    // ...
}

```

--------------------------------

### Execute a Cargo test build

Source: https://docs.rs/escargot/0.5.15/src/escargot/build.rs.html

Demonstrates configuring and executing a test build using the CargoBuild builder.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
escargot::CargoBuild::new()
    .test("test")
    .manifest_path("tests/testsuite/fixtures/test/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### Unwrap Error Value

Source: https://docs.rs/escargot/0.5.15/escargot/error/type.CargoResult.html

Use `unwrap_err` to get the contained `Err` value. Panics if the `Result` is `Ok`, using the `Ok` value in the panic message.

```rust
let x: Result<u32, &str> = Ok(2);
x.unwrap_err(); // panics with `2`
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(x.unwrap_err(), "emergency failure");
```

--------------------------------

### CargoBuild::exec()

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Executes the configured Cargo build command and returns compiler messages.

```APIDOC
### pub fn exec(self) -> CargoResult<CommandMessages>

#### Description
Build the configured target, returning compiler messages.
```

--------------------------------

### Expect Error Value

Source: https://docs.rs/escargot/0.5.15/escargot/error/type.CargoResult.html

Use `expect_err` to get the contained `Err` value. Panics if the `Result` is `Ok`, including the `Ok` value in the panic message.

```rust
let x: Result<u32, &str> = Ok(10);
x.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`
```

--------------------------------

### Implement PartialEq for BuildScript

Source: https://docs.rs/escargot/0.5.15/escargot/format/struct.BuildScript.html

Enables equality comparison between two BuildScript instances. This allows checking if two build script outputs are identical.

```rust
impl<'a> PartialEq for BuildScript<'a>
Source
fn eq(&self, other: &BuildScript<'a>) -> bool
Tests for `self` and `other` values to be equal, and is used by `==`.
1.0.0 · Source
fn ne(&self, other: &Rhs) -> bool
Tests for `!=`. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source
```

--------------------------------

### Advance Iterator and Get Next N Values (Nightly)

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CommandMessages.html

This is a nightly-only experimental API. It advances the iterator and returns an array containing the next N values.

```rust
fn next_chunk<const N: usize>( &mut self, ) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>
where Self: Sized,
```

--------------------------------

### CargoBuild::bins()

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Configures the build to include all binaries defined in the manifest.

```APIDOC
### pub fn bins(self) -> Self

#### Description
Build all binaries.

#### Example
```rust
escargot::CargoBuild::new()
    .bins()
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```
```

--------------------------------

### Implement CloneToUninit for T (Nightly)

Source: https://docs.rs/escargot/0.5.15/escargot/format/struct.BuildFinished.html

An experimental nightly-only API for performing copy-assignment from self to an uninitialized memory location.

```rust
impl<T> CloneToUninit for T
where T: Clone,
Source
#### unsafe fn clone_to_uninit(&self, dest: *mut u8)
🔬This is a nightly-only experimental API. (`clone_to_uninit`)
Performs copy-assignment from `self` to `dest`. Read more
```

--------------------------------

### Get Compiled Artifact Path

Source: https://docs.rs/escargot/0.5.15/src/escargot/run.rs.html

The `path()` method on a `CargoRun` object returns a reference to the compiled binary's path. This is useful for inspecting the artifact or passing its path to other processes.

```rust
println!("artifact={}", run.path().display());
```

--------------------------------

### Target Struct Definition

Source: https://docs.rs/escargot/0.5.15/escargot/format/struct.Target.html

Defines a single target (lib, bin, example, etc.) provided by a crate. This struct is non-exhaustive, meaning additional fields may be added in future versions.

```rust
#[non_exhaustive]
pub struct Target<'a> {
    pub name: Cow<'a, str>,
    pub kind: Vec<Cow<'a, str>>,
    pub crate_types: Vec<Cow<'a, str>>,
    pub doctest: Option<bool>,
    pub doc: Option<bool>,
    pub test: bool,
    pub required_features: Vec<Cow<'a, str>>,
    pub src_path: Cow<'a, Path>,
    pub edition: Cow<'a, str>,
}

```

--------------------------------

### Execute Cargo Build

Source: https://docs.rs/escargot/0.5.15/escargot/index.html

Use this snippet to execute a Cargo build command. Configure the binary, release, target, manifest path, and target directory before execution. Ensure the manifest path and target directory are correctly set.

```rust
escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### Implement PartialEq for BuildFinished

Source: https://docs.rs/escargot/0.5.15/escargot/format/struct.BuildFinished.html

Enables comparison of two BuildFinished instances for equality.

```rust
impl PartialEq for BuildFinished
Source
#### fn eq(&self, other: &BuildFinished) -> bool
Tests for `self` and `other` values to be equal, and is used by `==`.
1.0.0 · Source
```

--------------------------------

### Rust Test Event Enum

Source: https://docs.rs/escargot/0.5.15/src/escargot/format/test.rs.html

Defines the various events related to individual test cases. Use this to handle specific test outcomes like Started, Ok, Failed, Ignored, AllowedFailure, and Timeout.

```rust
/// Test case event.
#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq)]
#[serde(rename_all = "snake_case")]
#[serde(tag = "event")]
pub enum Test {
    /// Case-started event.
    Started(TestStarted),
    /// Case-finished successfully event.
    Ok(TestOk),
    /// Case-finished with failure event.
    Failed(TestFailed),
    /// Case-ignored event.
    Ignored(TestIgnored),
    /// Case-allowed-failure event.
    AllowedFailure(TestAllowedFailure),
    /// Case-timeout event.
    Timeout(TestTimeout),
    #[cfg(not(feature = "strict_unstable"))]
    #[doc(hidden)]
    #[serde(other)]
    Unknown,
}
```

--------------------------------

### Implement CloneToUninit for T (Nightly)

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.TestAllowedFailure.html

Nightly-only experimental API. Implements `CloneToUninit` for types `T` that implement `Clone`, allowing unsafe copying to uninitialized memory.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)

```

--------------------------------

### Implement Clone for BuildFinished

Source: https://docs.rs/escargot/0.5.15/escargot/format/struct.BuildFinished.html

Provides functionality to create a duplicate of a BuildFinished instance.

```rust
impl Clone for BuildFinished
Source
#### fn clone(&self) -> BuildFinished
Returns a duplicate of the value. Read more
1.0.0 · Source
```

--------------------------------

### CargoBuild::manifest_path()

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Sets the path to the Cargo.toml file for the build.

```APIDOC
### pub fn manifest_path<S: AsRef<OsStr>>(self, path: S) -> Self

#### Description
Path to Cargo.toml
```

--------------------------------

### BuildScript Structure

Source: https://docs.rs/escargot/0.5.15/src/escargot/format/mod.rs.html

Details the output of a build script execution, including linked libraries, paths, environment variables, and the output directory.

```rust
pub struct BuildScript<'a> {
    /// The workspace member this build script execution belongs to
    #[serde(borrow)]
    pub package_id: WorkspaceMember<'a>,
    /// The outdir used.
    #[serde(borrow)]
    #[serde(default)]
    pub out_dir: Option<CowPath<'a>>,
    /// The libs to link
    #[serde(borrow)]
    pub linked_libs: Vec<CowStr<'a>>,
    /// The paths to search when resolving libs
    #[serde(borrow)]
    pub linked_paths: Vec<CowPath<'a>>,
    /// The paths to search when resolving libs
    #[serde(borrow)]
    pub cfgs: Vec<CowPath<'a>>,
    /// The environment variables to add to the compilation
    #[serde(borrow)]
    pub env: Vec<(CowStr<'a>, CowStr<'a>) >,
}
```

--------------------------------

### PartialEq Implementation for SuiteStarted

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.SuiteStarted.html

Provides methods for comparing SuiteStarted instances for equality.

```rust
fn eq(&self, other: &SuiteStarted) -> bool
```

```rust
fn ne(&self, other: &Rhs) -> bool
```

--------------------------------

### Build specific package

Source: https://docs.rs/escargot/0.5.15/escargot/struct.CargoBuild.html

Builds a specific package within a workspace.

```rust
escargot::CargoBuild::new()
    .package("bin")
    .bin("bin")
    .manifest_path("tests/testsuite/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### Retrieve test kinds

Source: https://docs.rs/escargot/0.5.15/src/escargot/test.rs.html

Demonstrates how to identify the types of tests (e.g., bin, lib, test) found in a project.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
let run: Result<Vec<_>, _> = escargot::CargoBuild::new()
    .tests()
    .current_release()
    .current_target()
    .manifest_path("tests/testsuite/fixtures/test/Cargo.toml")
    .target_dir(target_dir.path())
    .run_tests()
    .unwrap()
    .collect();
let run = run.unwrap();
let mut kinds: Vec<_> = run.iter().map(|r| r.kind()).collect();
kinds.sort_unstable();
assert_eq!(kinds, ["bin", "lib", "test"]);
```

--------------------------------

### Using `or` to Provide a Default Result

Source: https://docs.rs/escargot/0.5.15/escargot/error/type.CargoResult.html

Demonstrates the `or` method, which returns the `Ok` value of `self` if it is `Ok`, otherwise returns the provided `res`ult. Note that arguments are eagerly evaluated.

```APIDOC
## PUT /api/users/{id}

### Description
Updates an existing user's information. Requires the user's ID in the path and the fields to update in the request body.

### Method
PUT

### Endpoint
/api/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the user to update.

#### Request Body
- **email** (string) - Optional - The new email address for the user.
- **password** (string) - Optional - The new password for the user.

### Request Example
```json
{
  "email": "john.doe.updated@example.com"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the user.
- **username** (string) - The username of the user.
- **email** (string) - The updated email address of the user.

#### Response Example
```json
{
  "id": "user-12345",
  "username": "johndoe",
  "email": "john.doe.updated@example.com"
}
```
```

--------------------------------

### Initialize CommandMessages with a Command

Source: https://docs.rs/escargot/0.5.15/src/escargot/msg.rs.html

Use `with_command` to run a cargo sub-command and capture its stdout and stderr. This method pipes stdout and stderr to allow for reading messages.

```rust
pub fn with_command(mut cmd: process::Command) -> CargoResult<Self> {
        let mut child = cmd
            .stdout(process::Stdio::piped())
            .stderr(process::Stdio::piped())
            .spawn()
            .map_err(|e| CargoError::new(ErrorKind::InvalidCommand).set_cause(e))?;
        let stdout = child.stdout.take().expect("piped above");
        let stdout = io::BufReader::new(stdout);
        let stderr = child.stderr.take().expect("piped above");
        let stderr = io::BufReader::new(stderr);
        let msgs = InnerCommandMessages {
            done: false,
            child,
            stdout,
            stderr,
        };
        Ok(CommandMessages(msgs))
    }
```

--------------------------------

### Build a binary with Escargot

Source: https://docs.rs/escargot/0.5.15/src/escargot/lib.rs.html

Configures and executes a Cargo build process using the CargoBuild builder pattern.

```rust
# let target_dir = tempfile::TempDir::new().unwrap();
escargot::CargoBuild::new()
    .bin("bin")
    .current_release()
    .current_target()
    .manifest_path("tests/fixtures/bin/Cargo.toml")
    .target_dir(target_dir.path())
    .exec()
    .unwrap();
```

--------------------------------

### Serialize Implementation for SuiteStarted

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.SuiteStarted.html

Enables SuiteStarted instances to be serialized into a Serde serializer.

```rust
fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer,

```

--------------------------------

### SuiteStarted Trait Implementations

Source: https://docs.rs/escargot/0.5.15/escargot/format/test/struct.SuiteStarted.html

Overview of the trait implementations for the SuiteStarted struct.

```APIDOC
## Trait Implementations for SuiteStarted

### `Clone`
- `clone(&self) -> SuiteStarted`: Returns a duplicate of the value.
- `clone_from(&mut self, source: &Self)`: Performs copy-assignment from `source`.

### `Debug`
- `fmt(&self, f: &mut Formatter<'_>) -> Result`: Formats the value using the given formatter.

### `Deserialize`
- `deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>`: Deserialize this value from the given Serde deserializer.

### `PartialEq`
- `eq(&self, other: &SuiteStarted) -> bool`: Tests for `self` and `other` values to be equal.
- `ne(&self, other: &Rhs) -> bool`: Tests for `!=`.

### `Serialize`
- `serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>`: Serialize this value into the given Serde serializer.

### `Eq`

### `StructuralPartialEq`
```

--------------------------------

### Implement Serialize for BuildFinished

Source: https://docs.rs/escargot/0.5.15/escargot/format/struct.BuildFinished.html

Allows the BuildFinished struct to be serialized into a Serde serializer.

```rust
impl Serialize for BuildFinished
Source
#### fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer,
Serialize this value into the given Serde serializer. Read more
```

--------------------------------

### Implement Clone for BuildScript

Source: https://docs.rs/escargot/0.5.15/escargot/format/struct.BuildScript.html

Provides functionality to duplicate a BuildScript instance. This allows for creating a copy of the build script's output information.

```rust
impl<'a> Clone for BuildScript<'a>
Source
fn clone(&self) -> BuildScript<'a>
Returns a duplicate of the value. Read more
1.0.0 · Source
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from `source`. Read more
Source
```
Tokens:
Raw