Struct unimock::Unimock

pub struct Unimock { /* private fields */ }

A type whose purpose is to provide mocked behaviour for the traits that it implements.

All traits implemented by Unimock can be considered mock implementations, except marker traits, Clone and Drop.

The mock configuration is specified up front, as a constructor argument in the form of a simple or compound Clause. After instantiation, the unimock configuration is immutable.

Unimock implements Send and Sync, and is therefore thread safe.

Unimock is meant to be used as a testing utility. Using it for other purposes is not recommended.

Clone semantics

Calling clone on unimock creates a derived object which shares internal state with the original.

Unimock runs post-test verifications automatically upon drop (it is a RAII utility). Interaction verifications should be performed only after all expected interactions have completed. Because of this, only the original instance will run any verifications upon being dropped, and when dropping the original instance, it is an error if there are derived objects still alive. In a typical testing context, this scenario usually means that a spawned thread (that owns a derived Unimock) has escaped the test. Unimock will panic with an appropriate message if this is detected.

This detection is usually reliable. Unimock will also induce a panic if the original instance gets dropped in a thread that does not equal the creator thread. Therefore, Unimock should always be cloned before sending off to another thread.

Implementations

impl Unimock

pub fn new(setup: impl Clause) -> Self

Construct a unimock instance which strictly adheres to the description in the passed Clause.

Every call hitting the instance must be declared in advance as a clause, or else panic will ensue.

Example

#[unimock(api=TraitMock)]
trait Trait {
    fn foo(&self) -> &'static str;
}

let mocked = Unimock::new(TraitMock::foo.some_call(matching!()).returns("mocked"));

assert_eq!("mocked", mocked.foo());

pub fn new_partial(setup: impl Clause) -> Self

Construct a unimock instance using partial mocking.

In a partially mocked environment, every clause acts as an override over the default behaviour, which is to hit “real world” code. Trait methods which support the unmock feature get this behaviour automatically in a partial mock, unless explicitly overridden in the passed Clause.

Methods that cannot be unmocked still need to be explicitly mocked with a clause.

Example

#[unimock(api=TraitMock, unmock_with=[real_foo])]
trait Trait {
    fn foo(&self) -> &'static str;
}

fn real_foo(_: &impl std::any::Any) -> &'static str {
    "real thing"
}

// A partial mock with no overrides:
assert_eq!("real thing", Unimock::new_partial(()).foo());

// A partial mock that overrides the behaviour of `Trait::foo`:
let clause = TraitMock::foo.next_call(matching!()).returns("mocked");
assert_eq!("mocked", Unimock::new_partial(clause).foo());

pub fn no_verify_in_drop(self) -> Self

Turn off auto-verification within Drop::drop.

The current use case for this is [no_std]. In [no_std] there is no thread API, and therefore no way to check if the current thread is already panicking.

Leaving verify-in-drop on in such circumstances (in the context of panicking unit tests) easily leads to double panics, which are quite hard to debug.

pub fn verify(self)

Explicitly verify this unimock instance.

There is no need to do this explicitly unless Self::no_verify_in_drop has been called.

pub fn make_ref<T: Send + Sync + 'static>(&self, value: T) -> &T

Convert the given value into a reference.

This can be useful when returning references from answers functions.

pub fn make_mut<T: Send + Sync + 'static>(&mut self, value: T) -> &mut T

Convert the given value into a mutable reference.

This can be useful when returning mutable references from answers functions.

impl Unimock

pub fn make_fragile_ref<T: 'static>(&self, value: T) -> &T

Available on crate feature fragile only.

Convert the given value into a reference.

The value does not need to implement Send. Unimock will panic/abort if the instance is sent to another thread after calling this.

pub fn make_fragile_mut<T: 'static>(&mut self, value: T) -> &mut T

Available on crate feature fragile only.

Convert the given value into a mutable reference.

The value does not need to implement Send. Unimock will panic/abort if the instance is sent to another thread after calling this.

Trait Implementations

impl AsyncBufRead for Unimock

Available on crate feature mock-futures-io-0-3 only.

Mocked implementation. Mock API is available at AsyncBufReadMock.

fn poll_fill_buf( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Result<&[u8], Error>>

Attempt to return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(self: Pin<&mut Self>, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to poll_read.

impl AsyncBufRead for Unimock

Available on crate feature mock-tokio-1 only.

Mocked implementation. Mock API is available at AsyncBufReadMock.

fn poll_fill_buf( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Result<&[u8]>>

Attempts to return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(self: Pin<&mut Self>, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to poll_read.

impl AsyncRead for Unimock

Available on crate feature mock-tokio-1 only.

Mocked implementation. Mock API is available at AsyncReadMock.

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_> ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl AsyncRead for Unimock

Available on crate feature mock-futures-io-0-3 only.

Mocked implementation. Mock API is available at AsyncReadMock.

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8] ) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>] ) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncSeek for Unimock

Available on crate feature mock-tokio-1 only.

Mocked implementation. Mock API is available at AsyncSeekMock.

fn start_seek(self: Pin<&mut Self>, position: SeekFrom) -> Result<()>

Attempts to seek to an offset, in bytes, in a stream.

fn poll_complete( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Result<u64>>

Waits for a seek operation to complete.

impl AsyncSeek for Unimock

Available on crate feature mock-futures-io-0-3 only.

Mocked implementation. Mock API is available at AsyncSeekMock.

fn poll_seek( self: Pin<&mut Self>, cx: &mut Context<'_>, pos: SeekFrom ) -> Poll<Result<u64, Error>>

Attempt to seek to an offset, in bytes, in a stream.

impl AsyncWrite for Unimock

Available on crate feature mock-futures-io-0-3 only.

Mocked implementation. Mock API is available at AsyncWriteMock.

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8] ) -> Poll<Result<usize, Error>>

Attempt to write bytes from buf into the object.

fn poll_flush( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Result<(), Error>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Result<(), Error>>

Attempt to close the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>] ) -> Poll<Result<usize, Error>>

Attempt to write bytes from bufs into the object using vectored IO operations.

impl AsyncWrite for Unimock

Available on crate feature mock-tokio-1 only.

Mocked implementation. Mock API is available at AsyncWriteMock.

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8] ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>] ) -> Poll<Result<usize>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl BufRead for Unimock

Available on crate feature mock-std only.

Mocked implementation. Mock API is available at BufReadMock.

fn fill_buf(&mut self) -> Result<&[u8]>

Returns the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(&mut self, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to read.

fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize>

Read all bytes into buf until the delimiter byte or EOF is reached.

fn read_line(&mut self, buf: &mut String) -> Result<usize>

Read all bytes until a newline (the 0xA byte) is reached, and append them to the provided String buffer.

fn has_data_left(&mut self) -> Result<bool, Error>

🔬This is a nightly-only experimental API. (buf_read_has_data_left)

Check if the underlying Read has any data left to be read.

fn skip_until(&mut self, byte: u8) -> Result<usize, Error>

🔬This is a nightly-only experimental API. (bufread_skip_until)

Skip all bytes until the delimiter byte or EOF is reached.

fn split(self, byte: u8) -> Split<Self>

where Self: Sized,

Returns an iterator over the contents of this reader split on the byte byte.

fn lines(self) -> Lines<Self>

where Self: Sized,

Returns an iterator over the lines of this reader.

impl Clone for Unimock

fn clone(&self) -> Unimock

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Unimock

Available on crate feature mock-core only.

Mocked implementation. Mock API is available at DebugMock.

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

Formats the value using the given formatter.

impl DelayNs for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at DelayNsMock.

fn delay_ns(&mut self, ns: u32)

Pauses execution for at minimum ns nanoseconds. Pause can be longer if the implementation requires it due to precision/timing issues.

fn delay_us(&mut self, us: u32)

Pauses execution for at minimum us microseconds. Pause can be longer if the implementation requires it due to precision/timing issues.

fn delay_ms(&mut self, ms: u32)

Pauses execution for at minimum ms milliseconds. Pause can be longer if the implementation requires it due to precision/timing issues.

impl Display for Unimock

Available on crate feature mock-core only.

Mocked implementation. Mock API is available at DisplayMock.

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

Formats the value using the given formatter.

impl Drop for Unimock

fn drop(&mut self)

Executes the destructor for this type.

impl Error for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at ErrorMock.

fn kind(&self) -> ErrorKind

Convert error to a generic error kind

impl Error for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at ErrorMock.

fn kind(&self) -> ErrorKind

Convert error to a generic I2C error kind.

impl Error for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at ErrorMock.

fn kind(&self) -> ErrorKind

Convert error to a generic SPI error kind.

impl Error for Unimock

Available on crate feature mock-std only.

Mocked implementation. Mock API is available at ErrorMock.

fn source(&self) -> Option<&(dyn Error + 'static)>

The lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type based access to context intended for error reports.

impl Error for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at ErrorMock.

fn kind(&self) -> ErrorKind

Convert error to a generic error kind.

impl ErrorType for Unimock

Available on crate feature mock-embedded-hal-1 only.

type Error = Unimock

Error type.

impl ErrorType for Unimock

Available on crate feature mock-embedded-hal-1 only.

type Error = Unimock

Error type

impl ErrorType for Unimock

Available on crate feature mock-embedded-hal-1 only.

type Error = Unimock

Error type

impl ErrorType for Unimock

Available on crate feature mock-embedded-hal-1 only.

type Error = Unimock

Error type

impl Hasher for Unimock

Available on crate feature mock-core only.

Mocked implementation. Mock API is available at HasherMock.

fn finish(&self) -> u64

Returns the hash value for the values written so far.

fn write(&mut self, bytes: &[u8])

Writes some data into this Hasher.

fn write_u8(&mut self, i: u8)

Writes a single u8 into this hasher.

fn write_u16(&mut self, i: u16)

Writes a single u16 into this hasher.

fn write_u32(&mut self, i: u32)

Writes a single u32 into this hasher.

fn write_u64(&mut self, i: u64)

Writes a single u64 into this hasher.

fn write_u128(&mut self, i: u128)

Writes a single u128 into this hasher.

fn write_usize(&mut self, i: usize)

Writes a single usize into this hasher.

fn write_i8(&mut self, i: i8)

Writes a single i8 into this hasher.

fn write_i16(&mut self, i: i16)

Writes a single i16 into this hasher.

fn write_i32(&mut self, i: i32)

Writes a single i32 into this hasher.

fn write_i64(&mut self, i: i64)

Writes a single i64 into this hasher.

fn write_i128(&mut self, i: i128)

Writes a single i128 into this hasher.

fn write_isize(&mut self, i: isize)

Writes a single isize into this hasher.

fn write_length_prefix(&mut self, len: usize)

🔬This is a nightly-only experimental API. (hasher_prefixfree_extras)

Writes a length prefix into this hasher, as part of being prefix-free.

fn write_str(&mut self, s: &str)

🔬This is a nightly-only experimental API. (hasher_prefixfree_extras)

Writes a single str into this hasher.

impl<A: AddressMode + 'static> I2c<A> for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at I2cMock.

fn transaction( &mut self, address: A, operations: &mut [Operation<'_>] ) -> Result<(), <Self as ErrorType>::Error>

Execute the provided operations on the I2C bus.

fn read( &mut self, address: A, read: &mut [u8] ) -> Result<(), <Self as ErrorType>::Error>

Reads enough bytes from slave with address to fill read.

fn write( &mut self, address: A, write: &[u8] ) -> Result<(), <Self as ErrorType>::Error>

Writes bytes to slave with address address.

fn write_read( &mut self, address: A, write: &[u8], read: &mut [u8] ) -> Result<(), <Self as ErrorType>::Error>

Writes bytes to slave with address address and then reads enough bytes to fill read in a single transaction.

impl InputPin for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at InputPinMock.

fn is_high(&mut self) -> Result<bool, <Self as ErrorType>::Error>

Is the input pin high?

fn is_low(&mut self) -> Result<bool, <Self as ErrorType>::Error>

Is the input pin low?

impl OutputPin for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at OutputPinMock.

fn set_low(&mut self) -> Result<(), <Self as ErrorType>::Error>

Drives the pin low.

fn set_high(&mut self) -> Result<(), <Self as ErrorType>::Error>

Drives the pin high.

fn set_state( &mut self, state: PinState ) -> Result<(), <Self as ErrorType>::Error>

Drives the pin high or low depending on the provided value.

impl Read for Unimock

Available on crate feature mock-std only.

Mocked implementation. Mock API is available at ReadMock.

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Like read, except that it reads into a slice of buffers.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>

Read the exact number of bytes required to fill buf.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl Seek for Unimock

Available on crate feature mock-std only.

Mocked implementation. Mock API is available at SeekMock.

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

fn rewind(&mut self) -> Result<()>

Rewind to the beginning of a stream.

fn stream_position(&mut self) -> Result<u64>

Returns the current seek position from the start of the stream.

fn stream_len(&mut self) -> Result<u64, Error>

🔬This is a nightly-only experimental API. (seek_stream_len)

Returns the length of this stream (in bytes).

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

🔬This is a nightly-only experimental API. (seek_seek_relative)

Seeks relative to the current position.

impl SetDutyCycle for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at SetDutyCycleMock.

fn max_duty_cycle(&self) -> u16

Get the maximum duty cycle value.

fn set_duty_cycle( &mut self, duty: u16 ) -> Result<(), <Self as ErrorType>::Error>

Set the duty cycle to duty / max_duty.

fn set_duty_cycle_fully_off(&mut self) -> Result<(), <Self as ErrorType>::Error>

Set the duty cycle to 0%, or always inactive.

fn set_duty_cycle_fully_on(&mut self) -> Result<(), <Self as ErrorType>::Error>

Set the duty cycle to 100%, or always active.

fn set_duty_cycle_fraction( &mut self, num: u16, denom: u16 ) -> Result<(), <Self as ErrorType>::Error>

Set the duty cycle to num / denom.

fn set_duty_cycle_percent( &mut self, percent: u8 ) -> Result<(), <Self as ErrorType>::Error>

Set the duty cycle to percent / 100

impl<Word: Copy + 'static> SpiBus<Word> for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at SpiBusMock.

fn read(&mut self, words: &mut [Word]) -> Result<(), <Self as ErrorType>::Error>

Read words from the slave.

fn write(&mut self, words: &[Word]) -> Result<(), <Self as ErrorType>::Error>

Write words to the slave, ignoring all the incoming words.

fn transfer( &mut self, read: &mut [Word], write: &[Word] ) -> Result<(), <Self as ErrorType>::Error>

Write and read simultaneously. write is written to the slave on MOSI and words received on MISO are stored in read.

fn transfer_in_place( &mut self, words: &mut [Word] ) -> Result<(), <Self as ErrorType>::Error>

Write and read simultaneously. The contents of words are written to the slave, and the received words are stored into the same words buffer, overwriting it.

fn flush(&mut self) -> Result<(), <Self as ErrorType>::Error>

Wait until all operations have completed and the bus is idle.

impl<Word: Copy + 'static> SpiDevice<Word> for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at SpiDeviceMock.

fn transaction( &mut self, operations: &mut [Operation<'_, Word>] ) -> Result<(), <Self as ErrorType>::Error>

Perform a transaction against the device.

fn read(&mut self, buf: &mut [Word]) -> Result<(), <Self as ErrorType>::Error>

Do a read within a transaction.

fn write(&mut self, buf: &[Word]) -> Result<(), <Self as ErrorType>::Error>

Do a write within a transaction.

fn transfer( &mut self, read: &mut [Word], write: &[Word] ) -> Result<(), <Self as ErrorType>::Error>

Do a transfer within a transaction.

fn transfer_in_place( &mut self, buf: &mut [Word] ) -> Result<(), <Self as ErrorType>::Error>

Do an in-place transfer within a transaction.

impl StatefulOutputPin for Unimock

Available on crate feature mock-embedded-hal-1 only.

Mocked implementation. Mock API is available at StatefulOutputPinMock.

fn is_set_high(&mut self) -> Result<bool, <Self as ErrorType>::Error>

Is the pin in drive high mode?

fn is_set_low(&mut self) -> Result<bool, <Self as ErrorType>::Error>

Is the pin in drive low mode?

fn toggle(&mut self) -> Result<(), <Self as ErrorType>::Error>

Toggle pin output.

impl Termination for Unimock

Available on crate feature std only.

This implementation of Termination may be used for returning a Unimock instance as the result of a test:

#[test]
fn test() -> Unimock {
    Unimock::new(())
}

This enables a more functional test style, instead of relying on panic-in-drop.

Calling report prevents unimock from panicking later (in drop) on failed verifications, so use with care.

Mocking

The mock-std feature also enables mocking of this trait through mock::std::process::TerminationMock. This trait mock is partial by default: Unless explicitly mocked, it behaves as specified above.

fn report(self) -> ExitCode

Is called to get the representation of the value as status code. This status code is returned to the operating system.

impl Write for Unimock

Available on crate feature mock-std only.

Mocked implementation. Mock API is available at WriteMock.

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

Like write, except that it writes from a slice of buffers.

fn write_all(&mut self, buf: &[u8]) -> Result<()>

Attempts to write an entire buffer into this writer.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl RefUnwindSafe for Unimock

impl UnwindSafe for Unimock