nimtest v1.0.0 — CI-Ready Testing with Lock-Free Progress Bars

A comprehensive testing framework for Nim with automatic resource management, CLI testing, and CI/CD integration.

One-Liner Power

# One command to test like a god:
nimble install nimtest && nimtest

→ Get started quickly with comprehensive testing utilities.

Install

nimble install nimtest

import nimtest/api

var ctx = createTestContext()
try:
  let file = createTestFile(ctx, "test.txt", "hello")
  discard assertFileContains(file, "hello")
finally:
  ctx.cleanup()

Core Features

Feature	Killer Detail
TestContext	createTestContext() → ctx.cleanup() in finally
File Testing	assertFileContains(), createTempTestDir()
CLI Testing	runCliCommand(), assertExitCode()
Perf Testing	benchmark("op", 10_000): proc()
Reporting	saveReport(rfJunit, "ci.xml")
Progress Bars	pbsGlobe, pbsPulse, pbsDots, pbsBlocks — lock-free
Cross-Platform	Linux, macOS, Windows

CI/CD Integration

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jiro4989/setup-nim-action@v2
      - run: nimble install nimtest
      - run: nim c -r examples/test_all.nim
      - uses: actions/upload-artifact@v3
        with:
          name: junit-report
          path: test-results.xml

Documentation

This documentation covers all aspects of the nimtest framework:

Getting Started

• Quick Start Guide - Get up and running in 5 minutes
• Configuration Guide - Complete setup and configuration
• User Guide - Complete usage instructions

Core Documentation

• API Reference - Complete API documentation
• Architecture - Framework design and architecture
• Best Practices - Recommended patterns and practices

Examples and Guides

• Examples and Patterns - Common testing scenarios

Community

• Contribution Guidelines - How to contribute to the project
• CI/CD Guide - Integration with CI/CD systems

Core Concepts

Public API

The recommended way to import nimtest is:

import nimtest/api

This provides access to all core functionality in a clean namespace.

Test Context

The TestContext manages temporary resources and ensures proper cleanup:

# Create test context
var ctx = createTestContext()
try:
  # Create temporary files and directories
  let tempDir = createTempTestDir(ctx, "test_prefix")
  # ... your test code
finally:
  # Cleanup all registered resources
  ctx.cleanup()

File System Utilities

Comprehensive utilities for file and directory testing:

# Basic assertions (return bool, throw exception on failure)
discard assertFileExists("path/to/file")
discard assertFileContains("path/to/file", "expected content")
discard assertDirExists("path/to/directory")

Performance Testing

Built-in benchmarking and timing utilities:

# Time a code block
let duration = measureTime("operation"):
  proc() =
    # Your code here
    sleep(100)

# Run benchmarks
let results = benchmark("test operation", 1000):
  proc() =
    # Code to benchmark
    discard 1 + 1

Progress Visualization

Five different animated progress bar styles:

let bar = newProgressBar(pbsGlobe, total = 100, message = "Processing...")
for i in 0..99:
  # Do work
  updateProgress(bar, i + 1)
bar.finish("Complete!")

Reporting

Multiple output formats for different use cases:

var report = newTestSuiteReport("My Tests")
# ... add test results
generateConsoleReport(report)  # Human-readable output
saveReport(report, rfJunit, "junit.xml")  # CI/CD integration
saveReport(report, rfJson, "report.json")  # Programmatic access

Framework Architecture

nimtest is organized into focused modules:

src/nimtest/
├── api.nim          # Public API facade - import this
├── core.nim         # TestContext, basic utilities
├── helpers.nim      # Advanced assertions, extended utilities
├── reporting.nim    # Test results, multiple output formats
├── progress.nim     # Progress bar implementations
└── config.nim       # Project configuration constants

Contributing

We welcome contributions! See our Contribution Guidelines for details on how to get involved.

License

MIT License - see LICENSE for details. # Use nimtest utilities in your tests let testDir = ctx.createTempTestDir("basic_test") let testFile = testDir / "sample.txt" writeFile(testFile, "Hello, nimtest!")

# Verify with assertions
assertFileExists(testFile)
assertFileContains(testFile, "Hello, nimtest!")

# Test passes if no assertion fails
check true == true

### Key Framework Components

#### Resource Management
```nim
# Create test context for automatic cleanup
var ctx = createTestContext()
defer: ctx.cleanup()

# Create temporary resources
let testDir = ctx.createTempTestDir("my_test")

File System Assertions

assertFileExists("path/to/file")
assertDirExists("path/to/directory")
assertFileContains("config.json", "expected_content")
assertOutputContains(output, "expected_text")

CLI Testing

# Example usage with command output stored in a variable
let output = "Version: 1.0.0\nBuild Date: 2025-01-01"
discard assertOutputContains(output, "1.0.0")

Performance Testing

measureTime("operation name"):
  performOperation()

benchmark("operation", 1000):
  performOperation()

Progress Bars

# Create progress bar with different styles
let bar = newProgressBar(pbsGlobe, width = 40, total = 100, message = "Processing...")

# Update progress
updateProgress(bar, 50, "Halfway done...")
bar.display()

# Complete progress bar
bar.finish("All done!")

Configuration

Configure nimtest by editing src/nimtest/config.nim in your project:

const
  ProjectName* = "yourproject"          # Your project name
  ProjectDisplayName* = "Your Project"  # Human-readable name
  TempDirPrefix* = "nimtest_temp"       # Prefix for temporary directories
  TestSuiteVersion* = "0.1.0"           # Version for test reports

Test Organization

Organize your tests in a logical directory structure:

tests/
├── unit/                    # Unit tests for individual functions/modules
├── integration/             # Integration tests for multiple components
├── performance/             # Performance and benchmark tests
├── cli/                     # CLI command tests (if applicable)
├── fixtures/                # Test data and fixture files
├── helpers.nim              # Shared test utilities specific to your project
└── test_all.nim             # Main test runner

CI/CD Integration

nimtest is designed to work well in CI/CD environments:

• Compatible with GitHub Actions, GitLab CI, and other systems
• Cross-platform support (Linux, Windows, macOS)
• Multiple report formats (JSON, JUnit XML) for CI integration
• Console output formatted for CI logs

Best Practices

1. Always use TestContext: Create and clean up contexts properly for resource management
2. Use setup/teardown: Initialize resources in setup, clean up in teardown
3. Use descriptive test names: Make test names clear and specific
4. Test one thing per test: Keep tests focused on a single functionality
5. Use meaningful assertions: Provide clear messages for failed assertions
6. Clean up resources: Always ensure temporary files and directories are cleaned up
7. Use performance utilities: Measure and track performance of critical operations
8. Generate reports: Use reporting utilities to track test results over time

Roadmap

nimtest has an ambitious roadmap for 2026 focused on usability, performance, and observability. See ROADMAP.md for the complete strategic plan including:

• Q1 2026 (v1.1): Macro DSL for tests, CLI runner binary, enhanced assertions
• Q2 2026 (v1.2): Parallel execution, async/await support, E2E integration lanes
• Q3 2026 (v1.3): Interactive HTML reports, coverage integration, fuzzing hooks
• Q4 2026+: Wild cards including AI-assisted test generation and compile-time fuzzing

Contribute: Help shape the future by participating in roadmap discussions on the Nim Forum or GitHub Discussions.

Dependencies

• nim >= 2.0.0
• std/unittest (built-in)
• std/os (built-in)
• std/osproc (built-in)
• std/json (built-in)
• std/parseutils (built-in)

License

MIT License - See LICENSE file for details