Crate test_tools 

Module :: test_tools

Tools for writing and running tests.

Basic use-case

use test_tools::*;

#[ cfg( feature = "enabled" ) ]
#[ cfg( not( feature = "no_std" ) ) ]
tests_impls!
{
  fn pass1()
  {
    assert_eq!( true, true );
  }

  //

  fn pass2()
  {
    assert_eq!( 1, 1 );
  }
}

//
#[ cfg( feature = "enabled" ) ]
#[ cfg( not( feature = "no_std" ) ) ]
tests_index!
{
  pass1,
  pass2,
}

To add to your project

cargo add test_tools --dev

Try out from the repository

git clone https://github.com/Wandalen/wTools
cd wTools
cd examples/test_trivial
cargo run

Sample

Important: vec! Macro Ambiguity

When using use test_tools::*, you may encounter ambiguity between std::vec! and collection_tools::vec!.

Solutions :

// RECOMMENDED: Use std::vec! explicitly
use test_tools::*;
let v = std::vec![1, 2, 3];

// OR: Use selective imports
use test_tools::{ BTreeMap, HashMap };
let v = vec![1, 2, 3]; // No ambiguity

// OR: Use collection macros explicitly  
let collection_vec = collection_tools::vector_from![1, 2, 3];

API Stability Facade

This crate implements a comprehensive API stability facade pattern (FR-3) that shields users from breaking changes in underlying constituent crates. The facade ensures :

• Stable API Surface : Core functionality remains consistent across versions
• Namespace Isolation : Changes in constituent crates don’t affect public namespaces
• Dependency Insulation : Internal dependency changes are hidden from users
• Backward Compatibility : Existing user code continues to work across updates

Stability Mechanisms

1. Controlled Re-exports

All types and functions from constituent crates are re-exported through carefully controlled namespace modules (own, orphan, exposed, prelude) that maintain consistent APIs.

2. Dependency Isolation Module

The dependency module provides controlled access to underlying crates, allowing updates to constituent crates without breaking the public API.

3. Feature-Stable Functionality

Core functionality works regardless of feature combinations, with optional features providing enhanced capabilities without breaking the base API.

Test Compilation Troubleshooting Guide

This crate aggregates testing tools from multiple ecosystem crates. Due to the complexity of feature propagation and macro re-exports, test compilation can fail in specific patterns.

Quick Diagnosis Commands

# Test compilation (fastest diagnostic)
cargo test -p test_tools --all-features --no-run

# Full test suite  
cargo test -p test_tools --all-features

# Verbose compilation for detailed errors
cargo test -p test_tools --all-features --no-run -v

Common Error Patterns & Solutions

E0432 Errors (API Visibility)

error[E0432]: unresolved imports `test_tools::tests_impls`, `test_tools::exposed`

**Root Cause: ** Public API modules hidden by cfg gates
**Solution: ** Remove #[ cfg(not(feature = "doctest")) ] gates on namespace modules
**Prevention: ** See warnings in namespace module documentation below

E0433 Errors (Macro Resolution)

error[E0433]: failed to resolve: could not find `heap` in `the_module`

**Root Cause: ** Collection constructor macros not re-exported
**Solution: ** Verify macro re-exports around line 160-180 in this file
**Quick Fix: ** Ensure explicit macro re-exports with proper feature gates

Step-by-Step Debugging Process

1. **Count errors by type: ** cargo test -p test_tools --all-features --no-run 2>&1 | grep "error\[" | sort | uniq -c
2. **For E0432 (API visibility) : ** Check namespace modules for doctest cfg gates
3. **For E0433 (macro resolution) : ** Check macro re-exports and feature configuration
4. **Verify feature propagation: ** Check with -v flag for enabled features

Historical Context

• **Task 001 : ** Fixed 147 E0432 errors by removing doctest cfg gates from API modules
• **Task 002 : ** Fixed 7 E0433 errors by adding explicit macro re-exports
• **Task 003 : ** Added this embedded documentation to prevent regressions

Re-exports

pub use test::process;

pub use super::super::asset;

pub use super::super::compiletime;

pub use super::super::helper;

pub use super::super::smoke_test;

pub use super::super::version;

pub use super::super::process as process_tools;

Modules

behavioral_equivalence

Behavioral equivalence verification framework for re-exported utilities. Behavioral Equivalence Verification Framework

dependency

Namespace with dependencies.

exposed

Exposed namespace of the module.

orphan

Shared with parent namespace of the module

own

vec! macro removed to prevent ambiguity with std ::vec! Aggregated collection_tools tests will need to use collection_tools ::vec! explicitly Own namespace of the module.

prelude

Prelude to use essentials: use my_module::prelude::*.

test

Tools for testing.

Macros

doc_file_test

Test a file with documentation.

num

Required to convert integets to floats.

Structs

SmokeModuleTest

Context for smoke testing of a module.

Functions

smoke_test_for_local_run

Run smoke test for local version of the module.

smoke_test_for_published_run

Run smoke test for published version of the module.

smoke_test_run

Run smoke test for the module with proper cleanup on failure.

smoke_tests_run

Run smoke test for both published and local version of the module.

verify_api_stability

Verifies that the API stability facade is functioning correctly. This function can be used to check that all stability mechanisms are operational.

Attribute Macros

nightly

stable