mockcmd

https://docs.rs/mockcmd/latest/mockcmd/
Admin
mockcmd is a lightweight mocking library for command execution in Rust that provides a drop-in...
Tokens:4,348
Snippets:64
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Mock a simple command with stdout

Source: https://docs.rs/mockcmd/latest/mockcmd/fn.mock.html

This example shows how to mock a command that produces a specific standard output. Ensure `mockcmd` is imported.

```rust
use mockcmd::mock;

// Mock a simple command with no arguments
mock("echo").with_stdout("hello world").register();
```

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

### Create a New CommandMockBuilder

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Initialize a new builder for a specific program. Use this to start defining a mock command.

```rust
pub fn new<S: Into<OsString>>(program: S) -> Self
```

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

### Create a new command mock builder

Source: https://docs.rs/mockcmd/latest/mockcmd/fn.mock.html

Use this function to start defining mocked command behavior. It initiates a builder pattern for configuring arguments, output, and exit status.

```rust
pub fn mock<S: Into<OsString>>(program: S) -> CommandMockBuilder
```

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

### Get All Executed Commands

Source: https://docs.rs/mockcmd/latest/mockcmd/fn.get_executed_commands.html

Call this function to retrieve a copy of all commands that have been executed.

```rust
pub fn get_executed_commands() -> Vec<ExecutedCommand>
```

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

### Execute Command and Get Output

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.Command.html

Executes the command and returns its standard output, standard error, and exit status. This method returns a Result which may contain an Output struct or an error.

```rust
pub fn output(&mut self) -> Result<Output>
```

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

### Execute Command and Get Status

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.Command.html

Executes the command and returns only its exit status. This method returns a Result which may contain an ExitStatus or an error.

```rust
pub fn status(&mut self) -> Result<ExitStatus>
```

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

### Define a Simple Command Mock

Source: https://docs.rs/mockcmd/latest/mockcmd/index.html

Demonstrates creating a mock for a program with specific arguments, stdout, stderr, and exit status using a builder pattern. The mock is then registered for use in tests.

```rust
use mockcmd::mock;

// Create a simple mock
mock("program")
    .with_arg("arg1")
    .with_arg("arg2")
    .with_stdout("Success output")
    .with_stderr("Error message")
    .with_status(0)  // Exit code
    .register();
```

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

### Command::new

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.Command.html

Creates a new Command instance to execute a program.

```APIDOC
## Command::new

### Description
Creates a new Command instance to execute a program.

### Signature
```rust
pub fn new<S: AsRef<OsStr>>(program: S) -> Self
```

### Parameters
* `program`: The program to execute.
```

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

### Mock Git Command Execution

Source: https://docs.rs/mockcmd/latest/mockcmd/index.html

Sets up a mock for the 'git status' command with predefined stdout and then uses the mockcmd::Command to execute it. Verifies the output and checks if the command was executed.

```rust
use mockcmd::{Command, mock, was_command_executed};

// Setup a mock for the "git" command
mock("git")
    .with_arg("status")
    .with_stdout("On branch main\nNothing to commit")
    .register();

// Use the Command just like std::process::Command
let output = Command::new("git").arg("status").output().unwrap();

// The mock is used instead of executing the real command
assert_eq!(String::from_utf8_lossy(&output.stdout), "On branch main\nNothing to commit");

// Verify that the command was executed with the correct arguments
assert!(was_command_executed(&["git", "status"]));
assert!(!was_command_executed(&["git", "push"]));
```

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

### CommandMockBuilder::new

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Creates a new builder with the specified program.

```APIDOC
## CommandMockBuilder::new

### Description
Creates a new builder with the specified program.

### Signature
```rust
pub fn new<S: Into<OsString>>(program: S) -> Self
```

### Parameters
* `program` (S): The program name or path to be executed.
```

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

### CommandMockBuilder::with_args

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Sets the command arguments, replacing any existing ones.

```APIDOC
## CommandMockBuilder::with_args

### Description
Sets the command arguments. This replaces any existing arguments with the provided ones.

### Signature
```rust
pub fn with_args<I, S>(self, args: I) -> Self
where I: IntoIterator<Item = S>, S: Into<OsString>
```

### Parameters
* `args` (I): An iterator of arguments to set for the command.
```

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

### mock

Source: https://docs.rs/mockcmd/latest/mockcmd/fn.mock.html

Creates a new command mock builder for the specified program. This function is the entry point for defining mocked command behavior in tests. It begins a builder chain that lets you configure the expected command arguments, output, and exit status.

```APIDOC
## mock<S: Into<OsString>>(program: S) -> CommandMockBuilder

### Description
Creates a new command mock builder for the specified program. This function is the entry point for defining mocked command behavior in tests. It begins a builder chain that lets you configure the expected command arguments, output, and exit status.

### Parameters
#### Path Parameters
- **program** (S: Into<OsString>) - Required - The program to mock.

### Request Example
```rust
use mockcmd::mock;

// Mock a simple command with no arguments
mock("echo").with_stdout("hello world").register();

// Mock a command with specific arguments
mock("git")
    .with_arg("status")
    .with_stdout("On branch main\nNothing to commit")
    .register();

// Mock a command with exit status and error output
mock("grep")
    .with_arg("pattern")
    .with_arg("file.txt")
    .with_status(1)
    .with_stderr("file.txt: No such file or directory")
    .register();
```

### Note
This function only has an effect when used within `#[cfg(feature = "test")]`. In non-test code, mock definitions will be ignored.
```

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

### Mock a command with exit status and stderr

Source: https://docs.rs/mockcmd/latest/mockcmd/fn.mock.html

Set up a mock command to simulate a non-zero exit status and specific error output. This is crucial for testing error handling logic.

```rust
mock("grep")
    .with_arg("pattern")
    .with_arg("file.txt")
    .with_status(1)
    .with_stderr("file.txt: No such file or directory")
    .register();
```

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

### Generic CloneToUninit (Nightly)

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

Nightly-only experimental API for copying data to uninitialized memory.

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

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

### Migrate from std::process::Command

Source: https://docs.rs/mockcmd/latest/mockcmd/index.html

Illustrates the minimal change required to migrate from Rust's standard library Command to mockcmd's Command, involving only a change in the import statement.

```rust
- use std::process::Command;
+ use mockcmd::Command;
```

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

### Create a New Command

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.Command.html

Initializes a new Command instance with the program to be executed. The program argument can be any type that can be referenced as an OsStr.

```rust
pub fn new<S: AsRef<OsStr>>(program: S) -> Self
```

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

### Command::output

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.Command.html

Executes the command and returns its output.

```APIDOC
## Command::output

### Description
Executes the command and returns its output, capturing stdout and stderr.

### Signature
```rust
pub fn output(&mut self) -> Result<Output>
```

### Returns
A `Result` containing the `Output` of the command if successful, or an error.
```

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

### Command::args

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.Command.html

Adds multiple arguments to the command.

```APIDOC
## Command::args

### Description
Adds multiple arguments to the command.

### Signature
```rust
pub fn args<I, S>(&mut self, args: I) -> &mut Self
where I: IntoIterator<Item = S>, S: AsRef<OsStr>
```

### Parameters
* `args`: An iterator of arguments to add.
```

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

### Mock a command with specific arguments and stdout

Source: https://docs.rs/mockcmd/latest/mockcmd/fn.mock.html

Configure a mock command to expect specific arguments and return a predefined standard output. This is useful for testing command-line tools.

```rust
mock("git")
    .with_arg("status")
    .with_stdout("On branch main\nNothing to commit")
    .register();
```

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

### CommandMockBuilder::with_stdout

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Sets the expected standard output for the command.

```APIDOC
## CommandMockBuilder::with_stdout

### Description
Sets the expected stdout.

### Signature
```rust
pub fn with_stdout<S: Into<Vec<u8>>>(self, stdout: S) -> Self
```

### Parameters
* `stdout` (S): The expected standard output as a byte vector.
```

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

### CommandMockBuilder::build

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Consumes the builder and returns a MockDefinition.

```APIDOC
## CommandMockBuilder::build

### Description
Consumes the builder, returning a `MockDefinition`.

### Signature
```rust
pub fn build(self) -> MockDefinition
```

### Returns
A `MockDefinition` representing the configured mock command.
```

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

### Define a Command Mock

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Use CommandMockBuilder to define a mock command with its program name.

```rust
pub struct CommandMockBuilder { /* private fields */ }
```

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

### CommandMockBuilder::with_arg

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Adds a single argument to the command.

```APIDOC
## CommandMockBuilder::with_arg

### Description
Adds a single argument to the command.

### Signature
```rust
pub fn with_arg<S>(self, arg: S) -> Self
where S: Into<OsString>
```

### Parameters
* `arg` (S): The argument to add to the command.
```

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

### Build Mock Definition

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Consume the builder and finalize the mock command definition. This returns the constructed MockDefinition object.

```rust
pub fn build(self) -> MockDefinition
```

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

### Set Command Arguments

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Replace existing arguments with a new set of arguments for the command mock. Ensure arguments are convertible to OsString.

```rust
pub fn with_args<I, S>(self, args: I) -> Self
where I: IntoIterator<Item = S>,
      S: Into<OsString>,
```

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

### Command::arg

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.Command.html

Adds a single argument to the command.

```APIDOC
## Command::arg

### Description
Adds a single argument to the command.

### Signature
```rust
pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Self
```

### Parameters
* `arg`: The argument to add.
```

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

### Command::status

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.Command.html

Executes the command and returns its exit status.

```APIDOC
## Command::status

### Description
Executes the command and returns its exit status without capturing output.

### Signature
```rust
pub fn status(&mut self) -> Result<ExitStatus>
```

### Returns
A `Result` containing the `ExitStatus` of the command if successful, or an error.
```

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

### CommandMockBuilder::with_stderr

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Sets the expected standard error for the command.

```APIDOC
## CommandMockBuilder::with_stderr

### Description
Sets the expected stderr.

### Signature
```rust
pub fn with_stderr<S: Into<Vec<u8>>>(self, stderr: S) -> Self
```

### Parameters
* `stderr` (S): The expected standard error as a byte vector.
```

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

### Clone Implementation for MockDefinition

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

Provides methods to duplicate a MockDefinition instance.

```rust
fn clone(&self) -> MockDefinition
```

```rust
fn clone_from(&mut self, source: &Self)
```

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

### Debug Implementation for MockDefinition

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

Enables debugging by allowing MockDefinition to be formatted for output.

```rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result
```

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

### Set Expected Standard Output

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Define the expected standard output for the mock command. The output must be convertible to a Vec<u8>.

```rust
pub fn with_stdout<S: Into<Vec<u8>>>(self, stdout: S) -> Self
```

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

### Add a Single Command Argument

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Append a single argument to the command mock. The argument must be convertible to OsString.

```rust
pub fn with_arg<S>(self, arg: S) -> Self
where S: Into<OsString>,
```

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

### MockDefinition Struct Definition

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

Defines the structure for mocking a command, specifying program, arguments, exit status, and I/O streams.

```rust
pub struct MockDefinition {
    pub program: OsString,
    pub args: Vec<OsString>,
    pub exit_status: Option<i32>,
    pub stdout: Option<Vec<u8>>,
    pub stderr: Option<Vec<u8>>,
}
```

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

### was_command_executed

Source: https://docs.rs/mockcmd/latest/mockcmd/fn.was_command_executed.html

Checks if a command was executed. Panics if `pieces` is empty.

```APIDOC
## was_command_executed

### Description
Checks if a command was executed based on the provided string slices.

### Panics
Panics if `pieces` is empty.

### Signature
```rust
pub fn was_command_executed(pieces: &[&str]) -> bool
```

### Parameters
#### Path Parameters
- **pieces** (&[&str]) - A slice of string slices representing the command pieces.

### Return Value
- **bool** - Returns `true` if the command was executed, `false` otherwise.
```

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

### Generic TryFrom Implementation

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

Attempts to convert one type into another, returning a Result.

```rust
type Error = Infallible
```

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

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

### CommandMockBuilder::with_status

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Sets the expected exit status for the command.

```APIDOC
## CommandMockBuilder::with_status

### Description
Sets the expected exit status.

### Signature
```rust
pub fn with_status(self, status: i32) -> Self
```

### Parameters
* `status` (i32): The expected exit status code.
```

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

### Clone Implementation for ExecutedCommand

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.ExecutedCommand.html

Provides methods to create a duplicate of an ExecutedCommand instance or perform copy-assignment from another instance.

```rust
fn clone(&self) -> ExecutedCommand
```

```rust
fn clone_from(&mut self, source: &Self)
```

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

### Generic TryInto Implementation

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

Attempts to convert a value into another type, returning a Result.

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

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

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

### Generic From Implementation

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

A trivial conversion where a value is returned unchanged.

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

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

### find_mock Function Signature

Source: https://docs.rs/mockcmd/latest/mockcmd/fn.find_mock.html

This snippet shows the signature of the find_mock function, detailing its parameters and return type.

```APIDOC
## find_mock

### Description
Locates a mock definition based on the provided program and arguments.

### Signature
```rust
pub fn find_mock(
    program: &OsString,
    args: &[OsString],
) -> Option<MockDefinition>
```

### Parameters
* `program` (&OsString) - The program name to find a mock for.
* `args` (&[OsString]) - A slice of OsString representing the arguments passed to the program.

### Returns
* `Option<MockDefinition>` - Returns `Some(MockDefinition)` if a matching mock is found, otherwise returns `None`.
```

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

### Define Command Struct

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.Command.html

Defines the Command struct, which is used to construct and manage external command executions. It has private fields.

```rust
pub struct Command { /* private fields */ }
```

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

### get_executed_commands

Source: https://docs.rs/mockcmd/latest/mockcmd/fn.get_executed_commands.html

Retrieves a copy of all commands that have been executed.

```APIDOC
## get_executed_commands

### Description
Returns a copy of all executed commands.

### Signature
```rust
pub fn get_executed_commands() -> Vec<ExecutedCommand>
```
```

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

### ExecutedCommand Struct Definition

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.ExecutedCommand.html

Defines the structure of an executed command, including the program and its arguments.

```APIDOC
## Struct ExecutedCommand

### Summary
```
pub struct ExecutedCommand {
    pub program: OsString,
    pub args: Vec<OsString>,
}
```

### Description
A record of an executed command.

### Fields
- `program`: OsString - The name of the program that was executed.
- `args`: Vec<OsString> - A vector of arguments passed to the command.
```

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

### Set Expected Exit Status

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Configure the mock command to return a specific integer exit status.

```rust
pub fn with_status(self, status: i32) -> Self
```

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

### ExecutedCommand Struct Definition

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.ExecutedCommand.html

Defines the structure for an executed command, holding the program name and its arguments as OsString types.

```rust
pub struct ExecutedCommand {
    pub program: OsString,
    pub args: Vec<OsString>,
}
```

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

### Add Multiple Arguments to Command

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.Command.html

Appends multiple arguments to the command from an iterator. This method is chainable and returns a mutable reference to the Command.

```rust
pub fn args<I, S>(&mut self, args: I) -> &mut Self
where I: IntoIterator<Item = S>, S: AsRef<OsStr>
```

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

### Generic Into Implementation

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

Converts a value into another type if a From implementation exists.

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

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

### Generic ToOwned Implementation

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

Provides methods for creating owned data from borrowed data.

```rust
type Owned = T
```

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

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

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

### Add a Single Argument to Command

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.Command.html

Appends a single argument to the command. This method is chainable and returns a mutable reference to the Command itself.

```rust
pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Self
```

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

### Set Expected Standard Error

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.CommandMockBuilder.html

Define the expected standard error output for the mock command. The error must be convertible to a Vec<u8>.

```rust
pub fn with_stderr<S: Into<Vec<u8>>>(self, stderr: S) -> Self
```

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

### Generic BorrowMut Implementation

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

Allows mutable borrowing of a value of the same type.

```rust
fn borrow_mut(&mut self) -> &mut T
```

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

### Generic Borrow Implementation

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

Allows immutable borrowing of a value of the same type.

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

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

### Generic TypeId Implementation

Source: https://docs.rs/mockcmd/latest/mockcmd/struct.MockDefinition.html

Retrieves the unique type identifier for any type that implements 'static.

```rust
fn type_id(&self) -> TypeId
```
Tokens:
Raw