unit_test_stream.c File Reference

Unit tests implementation for the stream port. More...

#include "stream/borrowers/stream.h"
#include "stream/lifecycle/stream_lifecycle.h"
#include "stream/adapters/stream_adapters_api.h"
#include "stream/cr/stream_cr_api.h"
#include "osal/mem/osal_mem.h"
#include "osal/mem/test/osal_mem_fake_provider.h"
#include "policy/lexleo_cstd_types.h"
#include "policy/lexleo_cstd_lib.h"
#include "policy/lexleo_cstd_jmp.h"
#include "lexleo_cmocka.h"

Include dependency graph for unit_test_stream.c:

Go to the source code of this file.

Enumerations
enum	stream_lifecycle_scenario_t {   STREAM_LIFECYCLE_SCENARIO_OK = 0 , STREAM_LIFECYCLE_SCENARIO_OUT_NULL , STREAM_LIFECYCLE_SCENARIO_VTBL_NULL , STREAM_LIFECYCLE_SCENARIO_ENV_NULL ,   STREAM_LIFECYCLE_SCENARIO_ENV_MEM_NULL , STREAM_LIFECYCLE_SCENARIO_OOM , STREAM_LIFECYCLE_SCENARIO_DESTROY_IDEMPOTENT , STREAM_LIFECYCLE_SCENARIO_VTBL_READ_NULL }
	Scenarios for stream_create() / stream_destroy(). More...
enum	stream_read_scenario_t {   STREAM_READ_SCENARIO_N_ZERO = 0 , STREAM_READ_SCENARIO_N_ZERO_ST_NULL , STREAM_READ_SCENARIO_S_NULL , STREAM_READ_SCENARIO_S_NULL_ST_NULL ,   STREAM_READ_SCENARIO_BUF_NULL , STREAM_READ_SCENARIO_BUF_NULL_ST_NULL , STREAM_READ_SCENARIO_BACKEND_NULL , STREAM_READ_SCENARIO_BACKEND_NULL_ST_NULL ,   STREAM_READ_SCENARIO_NOMINAL_OK , STREAM_READ_SCENARIO_NOMINAL_EOF , STREAM_READ_SCENARIO_NOMINAL_ST_NULL }
	Scenarios for stream_read(). More...
enum	stream_write_scenario_t {   STREAM_WRITE_SCENARIO_N_ZERO = 0 , STREAM_WRITE_SCENARIO_N_ZERO_ST_NULL , STREAM_WRITE_SCENARIO_S_NULL , STREAM_WRITE_SCENARIO_S_NULL_ST_NULL ,   STREAM_WRITE_SCENARIO_BUF_NULL , STREAM_WRITE_SCENARIO_BUF_NULL_ST_NULL , STREAM_WRITE_SCENARIO_BACKEND_NULL , STREAM_WRITE_SCENARIO_BACKEND_NULL_ST_NULL ,   STREAM_WRITE_SCENARIO_NOMINAL_OK , STREAM_WRITE_SCENARIO_NOMINAL_IO_ERROR , STREAM_WRITE_SCENARIO_NOMINAL_ST_NULL }
	Scenarios for stream_write(). More...
enum	stream_flush_scenario_t { STREAM_FLUSH_SCENARIO_S_NULL = 0 , STREAM_FLUSH_SCENARIO_BACKEND_NULL , STREAM_FLUSH_SCENARIO_NOMINAL_OK , STREAM_FLUSH_SCENARIO_NOMINAL_IO_ERROR }
	Scenarios for stream_flush(). More...

Functions
static void	test_stream_default_ops (void **state)
	Test stream_default_ops().
static void	test_stream_default_env (void **state)
	Test stream_default_env().

Detailed Description

This file implements the unit-level validation of the stream port contracts.

Covered surfaces:

• CR helpers: stream_default_ops(), stream_default_env()
• lifecycle: stream_create(), stream_destroy()
• borrower API: stream_read(), stream_write(), stream_flush()

Test strategy:

• parametric scenario-based testing
• explicit validation of argument checking and forwarding behavior
• allocator fault injection through fake_memory
• spy/fake backend verification through fake_stream_backend_t

See also:

• stream unit tests page
• stream specifications

Definition in file unit_test_stream.c.

Enumeration Type Documentation

stream_flush_scenario_t

enum stream_flush_scenario_t

stream_status_t stream_flush(stream_t *s);

Precondition:

• If s != NULL, s has been created by stream_create() with fake_stream_vtbl and fake_stream_backend.

Doubles:

• fake_stream_backend_t, fake_stream_vtbl

See also:

• stream_flush() unit tests section
• stream_flush() specifications

The scenarios below define the test oracle for stream_flush().

Enumerator
STREAM_FLUSH_SCENARIO_S_NULL	WHEN s == NULL EXPECT: returns STREAM_STATUS_INVALID does not call fake_stream_vtbl.read/write/flush/close
STREAM_FLUSH_SCENARIO_BACKEND_NULL	WHEN s != NULL and s->backend == NULL EXPECT: returns STREAM_STATUS_NO_BACKEND does not call fake_stream_vtbl.flush
STREAM_FLUSH_SCENARIO_NOMINAL_OK	WHEN s != NULL and s->backend != NULL AND fake_stream_backend is configured as: flush_ret = STREAM_STATUS_OK EXPECT: returns STREAM_STATUS_OK calls fake_stream_vtbl.flush(fake_stream_backend) exactly once does not call fake_stream_vtbl.read/write/close
STREAM_FLUSH_SCENARIO_NOMINAL_IO_ERROR	WHEN s != NULL and s->backend != NULL AND fake_stream_backend is configured as: flush_ret = STREAM_STATUS_IO_ERROR EXPECT: returns STREAM_STATUS_IO_ERROR calls fake_stream_vtbl.flush(fake_stream_backend) exactly once does not call fake_stream_vtbl.read/write/close

Definition at line 1554 of file unit_test_stream.c.

stream_lifecycle_scenario_t

enum stream_lifecycle_scenario_t

stream_status_t stream_create( stream_t **out, const stream_vtbl_t *vtbl, void *backend, const stream_env_t *env );

void stream_destroy(stream_t **s);

Invalid arguments:

• out, vtbl, env must not be NULL.
• vtbl->read, vtbl->write, vtbl->flush, vtbl->close must not be NULL.
• env->mem must not be NULL.

Success:

• Returns STREAM_STATUS_OK.
• Stores a valid stream in *out.
• The produced stream must be destroyed via stream_destroy().

Failure:

• Returns:
  • STREAM_STATUS_INVALID for invalid arguments
  • STREAM_STATUS_OOM on allocation failure
• Leaves *out unchanged if out is not NULL.

Lifecycle:

• stream_destroy() does nothing if s is NULL or *s is NULL.
• Otherwise, it releases the stream object and sets *s to NULL.

Doubles:

• fake_memory

See also:

• stream_create() / stream_destroy() unit tests section
• stream_create() specifications
• stream_destroy() specifications

The scenarios below define the test oracle for stream_create() and stream_destroy().

Enumerator
STREAM_LIFECYCLE_SCENARIO_OK	WHEN stream_create(out, vtbl, backend, env) is called with valid arguments EXPECT: returns STREAM_STATUS_OK stores a non-NULL stream handle in *out the produced handle is eligible for destruction by stream_destroy()
STREAM_LIFECYCLE_SCENARIO_OUT_NULL	WHEN out == NULL EXPECT: returns STREAM_STATUS_INVALID no stream handle is produced
STREAM_LIFECYCLE_SCENARIO_VTBL_NULL	WHEN vtbl == NULL and out != NULL EXPECT: returns STREAM_STATUS_INVALID leaves *out unchanged
STREAM_LIFECYCLE_SCENARIO_ENV_NULL	WHEN env == NULL and out != NULL EXPECT: returns STREAM_STATUS_INVALID leaves *out unchanged
STREAM_LIFECYCLE_SCENARIO_ENV_MEM_NULL	WHEN env != NULL but env->mem == NULL and out != NULL EXPECT: returns STREAM_STATUS_INVALID leaves *out unchanged
STREAM_LIFECYCLE_SCENARIO_OOM	WHEN allocation of the stream handle fails (allocator reports OOM) EXPECT: returns STREAM_STATUS_OOM leaves *out unchanged Notes: This scenario is exercised by configuring fake_memory to fail the allocation performed by stream_create().
STREAM_LIFECYCLE_SCENARIO_DESTROY_IDEMPOTENT	WHEN stream_create() succeeds and stream_destroy() is called twice EXPECT: first stream_destroy(&s) releases the handle and sets s to NULL second stream_destroy(&s) is a no-op and keeps s as NULL Notes: This scenario checks the idempotence guarantee of stream_destroy().
STREAM_LIFECYCLE_SCENARIO_VTBL_READ_NULL	WHEN vtbl != NULL but vtbl->read == NULL and out != NULL EXPECT: returns STREAM_STATUS_INVALID leaves *out unchanged Notes: The stream port requires a well-formed vtbl at creation time.

Definition at line 330 of file unit_test_stream.c.

stream_read_scenario_t

enum stream_read_scenario_t

size_t stream_read(stream_t *s, void *buf, size_t n, stream_status_t *st);

Precondition:

• If s != NULL, s has been created by stream_create() with fake_stream_vtbl and fake_stream_backend.

Doubles:

• fake_stream_backend_t
• fake_stream_vtbl
• fake_memory

See also:

• stream_read() unit tests section
• stream_read() specifications

The scenarios below define the test oracle for stream_read().

Enumerator
STREAM_READ_SCENARIO_N_ZERO	WHEN n == 0 and st != NULL EXPECT: returns 0 sets *st = STREAM_STATUS_OK does not call fake_stream_vtbl.read/write/flush/close
STREAM_READ_SCENARIO_N_ZERO_ST_NULL	WHEN n == 0 and st == NULL EXPECT: returns 0 does not call fake_stream_vtbl.read/write/flush/close
STREAM_READ_SCENARIO_S_NULL	WHEN n > 0 and s == NULL and st != NULL EXPECT: returns 0 sets *st = STREAM_STATUS_INVALID does not call fake_stream_vtbl.read/write/flush/close
STREAM_READ_SCENARIO_S_NULL_ST_NULL	WHEN n > 0 and s == NULL and st == NULL EXPECT: returns 0 does not call fake_stream_vtbl.read/write/flush/close
STREAM_READ_SCENARIO_BUF_NULL	WHEN n > 0 and buf == NULL and st != NULL EXPECT: returns 0 sets *st = STREAM_STATUS_INVALID does not call fake_stream_vtbl.read/write/flush/close
STREAM_READ_SCENARIO_BUF_NULL_ST_NULL	WHEN n > 0 and buf == NULL and st == NULL EXPECT: returns 0 does not call fake_stream_vtbl.read/write/flush/close
STREAM_READ_SCENARIO_BACKEND_NULL	WHEN n > 0 and s != NULL and buf != NULL and s->backend == NULL and st != NULL EXPECT: returns 0 sets *st = STREAM_STATUS_NO_BACKEND does not call fake_stream_vtbl.read/write/flush/close
STREAM_READ_SCENARIO_BACKEND_NULL_ST_NULL	WHEN n > 0 and s != NULL and buf != NULL and s->backend == NULL and st == NULL EXPECT: returns 0 does not call fake_stream_vtbl.read/write/flush/close
STREAM_READ_SCENARIO_NOMINAL_OK	WHEN n > 0 and s != NULL and buf != NULL and s->backend != NULL and st != NULL AND fake_stream_backend is configured as: read_ret = n read_st_to_set = STREAM_STATUS_OK EXPECT: calls fake_stream_vtbl.read(fake_stream_backend, buf, n, st) exactly once does not call fake_stream_vtbl.write/flush/close returns n sets *st = STREAM_STATUS_OK
STREAM_READ_SCENARIO_NOMINAL_EOF	WHEN n > 0 and s != NULL and buf != NULL and s->backend != NULL and st != NULL AND fake_stream_backend is configured as: read_ret == 0 read_st_to_set = STREAM_STATUS_EOF EXPECT: calls fake_stream_vtbl.read(fake_stream_backend, buf, n, st) exactly once does not call fake_stream_vtbl.write/flush/close returns 0 sets *st = STREAM_STATUS_EOF
STREAM_READ_SCENARIO_NOMINAL_ST_NULL	WHEN n > 0 and s != NULL and buf != NULL and s->backend != NULL and st == NULL AND fake_stream_backend is configured as: read_ret == 5 EXPECT: calls fake_stream_vtbl.read(fake_stream_backend, buf, n, st=NULL) exactly once does not call fake_stream_vtbl.write/flush/close returns 5

Definition at line 714 of file unit_test_stream.c.

stream_write_scenario_t

enum stream_write_scenario_t

size_t stream_write(stream_t *s, const void *buf, size_t n, stream_status_t *st);

Precondition:

• If s != NULL, s has been created by stream_create() with fake_stream_vtbl and fake_stream_backend.

Doubles:

• fake_stream_backend_t, fake_stream_vtbl

See also:

• stream_write() unit tests section
• stream_write() specifications

The scenarios below define the test oracle for stream_write().

Enumerator
STREAM_WRITE_SCENARIO_N_ZERO	WHEN n == 0 and st != NULL EXPECT: returns 0 sets *st = STREAM_STATUS_OK does not call fake_stream_vtbl.read/write/flush/close
STREAM_WRITE_SCENARIO_N_ZERO_ST_NULL	WHEN n == 0 and st == NULL EXPECT: returns 0 does not call fake_stream_vtbl.read/write/flush/close
STREAM_WRITE_SCENARIO_S_NULL	WHEN n > 0 and s == NULL and st != NULL EXPECT: returns 0 sets *st = STREAM_STATUS_INVALID does not call fake_stream_vtbl.read/write/flush/close
STREAM_WRITE_SCENARIO_S_NULL_ST_NULL	WHEN n > 0 and s == NULL and st == NULL EXPECT: returns 0 does not call fake_stream_vtbl.read/write/flush/close
STREAM_WRITE_SCENARIO_BUF_NULL	WHEN n > 0 and buf == NULL and st != NULL EXPECT: returns 0 sets *st = STREAM_STATUS_INVALID does not call fake_stream_vtbl.read/write/flush/close
STREAM_WRITE_SCENARIO_BUF_NULL_ST_NULL	WHEN n > 0 and buf == NULL and st == NULL EXPECT: returns 0 does not call fake_stream_vtbl.read/write/flush/close
STREAM_WRITE_SCENARIO_BACKEND_NULL	WHEN n > 0 and s != NULL and buf != NULL and s->backend == NULL and st != NULL EXPECT: returns 0 sets *st = STREAM_STATUS_NO_BACKEND does not call fake_stream_vtbl.read/write/flush/close
STREAM_WRITE_SCENARIO_BACKEND_NULL_ST_NULL	WHEN n > 0 and s != NULL and buf != NULL and s->backend == NULL and st == NULL EXPECT: returns 0 does not call fake_stream_vtbl.read/write/flush/close
STREAM_WRITE_SCENARIO_NOMINAL_OK	WHEN n > 0 and s != NULL and buf != NULL and s->backend != NULL and st != NULL AND fake_stream_backend is configured as: write_ret = n write_st_to_set = STREAM_STATUS_OK EXPECT: calls fake_stream_vtbl.write(fake_stream_backend, buf, n, st) exactly once does not call fake_stream_vtbl.read/flush/close returns n sets *st = STREAM_STATUS_OK
STREAM_WRITE_SCENARIO_NOMINAL_IO_ERROR	WHEN n > 0 and s != NULL and buf != NULL and s->backend != NULL and st != NULL AND fake_stream_backend is configured as: write_ret == 0 write_st_to_set = STREAM_STATUS_IO_ERROR EXPECT: calls fake_stream_vtbl.write(fake_stream_backend, buf, n, st) exactly once does not call fake_stream_vtbl.read/flush/close returns 0 sets *st = STREAM_STATUS_IO_ERROR
STREAM_WRITE_SCENARIO_NOMINAL_ST_NULL	WHEN n > 0 and s != NULL and buf != NULL and s->backend != NULL and st == NULL AND fake_stream_backend is configured as: write_ret == 5 EXPECT: calls fake_stream_vtbl.write(fake_stream_backend, buf, n, st=NULL) exactly once does not call fake_stream_vtbl.read/flush/close returns 5

Definition at line 1134 of file unit_test_stream.c.

Function Documentation

test_stream_default_env()

static void test_stream_default_env ( void **  state )

static

stream_env_t stream_default_env(const osal_mem_ops_t *mem_ops);

Success:

• ret.mem == mem_ops.

Failure:

• None.

Doubles:

• dummy osal_mem_ops_t

See also:

• stream_default_env() unit tests section
• stream_default_env() specifications.

Definition at line 278 of file unit_test_stream.c.

test_stream_default_ops()

static void test_stream_default_ops ( void **  state )

static

const stream_ops_t *stream_default_ops(void);

Success:

• ret, ret->read, ret->write and ret->flush are non-NULL.

Failure:

• None.

See also:

• stream_default_ops() unit-tests section
• stream_default_ops() specifications

Definition at line 251 of file unit_test_stream.c.