{"id":32713399,"url":"https://github.com/codenimja/nimtest","last_synced_at":"2025-11-02T11:01:46.758Z","repository":{"id":321614521,"uuid":"1085445757","full_name":"codenimja/nimtest","owner":"codenimja","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-30T16:35:18.000Z","size":745,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-30T16:42:24.996Z","etag":null,"topics":["assertion-library","automation","benchmarking","cli-testing","continuous-integration","nim","nim-lang","quality-assurance","software-testing","tdd","test-automation","test-framework","testing","unit-testing"],"latest_commit_sha":null,"homepage":null,"language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codenimja.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-29T03:46:59.000Z","updated_at":"2025-10-30T16:35:19.000Z","dependencies_parsed_at":"2025-10-30T16:42:33.174Z","dependency_job_id":null,"html_url":"https://github.com/codenimja/nimtest","commit_stats":null,"previous_names":["codenimja/nimtest"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/codenimja/nimtest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenimja%2Fnimtest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenimja%2Fnimtest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenimja%2Fnimtest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenimja%2Fnimtest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codenimja","download_url":"https://codeload.github.com/codenimja/nimtest/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenimja%2Fnimtest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282271384,"owners_count":26642101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-02T02:00:06.609Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assertion-library","automation","benchmarking","cli-testing","continuous-integration","nim","nim-lang","quality-assurance","software-testing","tdd","test-automation","test-framework","testing","unit-testing"],"created_at":"2025-11-02T11:00:30.401Z","updated_at":"2025-11-02T11:01:46.746Z","avatar_url":"https://github.com/codenimja.png","language":"Nim","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nimtest v1.0 — CI-Ready Testing with Lock-Free Progress Bars\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\n[![Nim Version](https://img.shields.io/badge/Nim-2.0+-blue.svg?style=flat-square)](https://nim-lang.org/)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/codenimja/nimtest/ci.yml?branch=main\u0026style=flat-square)](https://github.com/codenimja/nimtest/actions)\n[![CI](https://github.com/codenimja/nimtest/actions/workflows/ci.yml/badge.svg)](https://github.com/codenimja/nimtest/actions)\n[![Docs](https://img.shields.io/badge/docs-latest-blue)](https://codenimja.github.io/nimtest/)\n\n**A comprehensive testing framework for Nim with automatic resource management, CLI testing, and CI/CD integration.**\n\n## One-Liner Power\n\n```bash\n# One command to test like a god:\nnimble install nimtest \u0026\u0026 echo 'test \"hello\"' \u003e tests/t_hello.nim \u0026\u0026 nimtest\n```\n\n→ Get started quickly with comprehensive testing utilities.\n\n## Install\n\n```bash\nnimble install nimtest\n```\n\n```nim\nimport nimtest/api\n\nvar ctx = createTestContext()\ntry:\n  let file = createTestFile(ctx, \"test.txt\", \"hello\")\n  discard assertFileContains(file, \"hello\")\nfinally:\n  ctx.cleanup()\n```\n\n## Core Features\n\n| Feature | Killer Detail |\n|---------|---------------|\n| TestContext | `createTestContext()` → `ctx.cleanup()` in finally |\n| File Testing | `assertFileContains()`, `createTempTestDir()` |\n| CLI Testing | `runCliCommand()`, `assertExitCode()` |\n| Perf Testing | `benchmark(\"op\", 10_000): proc()` |\n| Reporting | `saveReport(rfJunit, \"ci.xml\")` |\n| Progress Bars | `pbsGlobe`, `pbsSpinner`, `pbsBar` — lock-free |\n| Cross-Platform | Linux, macOS, Windows |\n\n## CI/CD Integration\n\n```yaml\n# .github/workflows/ci.yml\nname: CI\non: [push, pull_request]\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: jiro4989/setup-nim-action@v2\n      - run: nimble install nimtest\n      - run: nim c -r tests/all_tests.nim\n      - uses: actions/upload-artifact@v3\n        with:\n          name: junit-report\n          path: test-results.xml\n```\n\n## Documentation\n\nThis documentation covers all aspects of the nimtest framework:\n\n### Getting Started\n- [Quick Start Guide](QUICKSTART.md) - Get up and running in 5 minutes\n- [Configuration Guide](CONFIGURATION.md) - Complete setup and configuration\n- [User Guide](USER_GUIDE.md) - Complete usage instructions\n\n### Core Documentation\n- [API Reference](API.md) - Complete API documentation\n- [Architecture](ARCHITECTURE.md) - Framework design and architecture\n- [Best Practices](BEST_PRACTICES.md) - Recommended patterns and practices\n\n### Examples and Guides\n- [Examples and Patterns](EXAMPLES.md) - Common testing scenarios\n\n### Community\n- [Contribution Guidelines](CONTRIBUTING.md) - How to contribute to the project\n- [CI/CD Guide](CI_CD_GUIDE.md) - Integration with CI/CD systems\n\n## Core Concepts\n\n### Public API\n\nThe recommended way to import nimtest is:\n\n```nim\nimport nimtest/api\n```\n\nThis provides access to all core functionality in a clean namespace.\n\n### Test Context\n\nThe `TestContext` manages temporary resources and ensures proper cleanup:\n\n```nim\n# Create test context\nvar ctx = createTestContext()\ntry:\n  # Create temporary files and directories\n  let tempDir = createTempTestDir(ctx, \"test_prefix\")\n  # ... your test code\nfinally:\n  # Cleanup all registered resources\n  ctx.cleanup()\n```\n\n### File System Utilities\n\nComprehensive utilities for file and directory testing:\n\n```nim\n# Basic assertions (return bool, throw exception on failure)\ndiscard assertFileExists(\"path/to/file\")\ndiscard assertFileContains(\"path/to/file\", \"expected content\")\ndiscard assertDirExists(\"path/to/directory\")\n```\n\n### Performance Testing\n\nBuilt-in benchmarking and timing utilities:\n\n```nim\n# Time a code block\nlet duration = measureTime(\"operation\"):\n  proc() =\n    # Your code here\n    sleep(100)\n\n# Run benchmarks\nlet results = benchmark(\"test operation\", 1000):\n  proc() =\n    # Code to benchmark\n    discard 1 + 1\n```\n\n### Progress Visualization\n\nFive different animated progress bar styles:\n\n```nim\nlet bar = newProgressBar(pbsGlobe, total = 100, message = \"Processing...\")\nfor i in 0..99:\n  # Do work\n  bar.update(i + 1)\nbar.finish(\"Complete!\")\n```\n\n### Reporting\n\nMultiple output formats for different use cases:\n\n```nim\nvar report = newTestSuiteReport(\"My Tests\")\n# ... add test results\ngenerateConsoleReport(report)  # Human-readable output\nsaveReport(report, rfJunit, \"junit.xml\")  # CI/CD integration\nsaveReport(report, rfJson, \"report.json\")  # Programmatic access\n```\n\n## Framework Architecture\n\nnimtest is organized into focused modules:\n\n```\nsrc/nimtest/\n├── api.nim          # Public API facade - import this\n├── core.nim         # TestContext, basic utilities\n├── helpers.nim      # Advanced assertions, extended utilities\n├── reporting.nim    # Test results, multiple output formats\n├── progress.nim     # Progress bar implementations\n└── config.nim       # Project configuration constants\n```\n\n## Contributing\n\nWe welcome contributions! See our [Contribution Guidelines](CONTRIBUTING.md) for details on how to get involved.\n\n## License\n\nMIT License - see [LICENSE](../LICENSE) for details.\n    # Use nimtest utilities in your tests\n    let testDir = ctx.createTempTestDir(\"basic_test\")\n    let testFile = testDir / \"sample.txt\"\n    writeFile(testFile, \"Hello, nimtest!\")\n\n    # Verify with assertions\n    assertFileExists(testFile)\n    assertFileContains(testFile, \"Hello, nimtest!\")\n\n    # Test passes if no assertion fails\n    check true == true\n```\n\n### Key Framework Components\n\n#### Resource Management\n```nim\n# Create test context for automatic cleanup\nvar ctx = createTestContext()\ndefer: ctx.cleanup()\n\n# Create temporary resources\nlet testDir = ctx.createTempTestDir(\"my_test\")\n```\n\n#### File System Assertions\n```nim\nassertFileExists(\"path/to/file\")\nassertDirExists(\"path/to/directory\")\nassertFileContains(\"config.json\", \"expected_content\")\nassertOutputContains(output, \"expected_text\")\n```\n\n#### CLI Testing\n```nim\n# Example usage with command output stored in a variable\nlet output = \"Version: 1.0.0\\nBuild Date: 2025-01-01\"\ndiscard assertOutputContains(output, \"1.0.0\")\n```\n\n#### Performance Testing\n```nim\nmeasureTime(\"operation name\"):\n  performOperation()\n\nbenchmark(\"operation\", 1000):\n  performOperation()\n```\n\n#### Progress Bars\n```nim\n# Create progress bar with different styles\nlet bar = newProgressBar(pbsGlobe, width = 40, total = 100, message = \"Processing...\")\n\n# Update progress\nbar.updateProgress(50, \"Halfway done...\")\nbar.display()\n\n# Complete progress bar\nbar.finish(\"All done!\")\n```\n\n## Configuration\n\nConfigure nimtest by editing `src/nimtest/config.nim` in your project:\n\n```nim\nconst\n  ProjectName* = \"yourproject\"          # Your project name\n  ProjectDisplayName* = \"Your Project\"  # Human-readable name\n  TempDirPrefix* = \"nimtest_temp\"       # Prefix for temporary directories\n  TestSuiteVersion* = \"0.1.0\"           # Version for test reports\n```\n\n## Test Organization\n\nOrganize your tests in a logical directory structure:\n\n```\ntests/\n├── unit/                    # Unit tests for individual functions/modules\n├── integration/             # Integration tests for multiple components\n├── performance/             # Performance and benchmark tests\n├── cli/                     # CLI command tests (if applicable)\n├── fixtures/                # Test data and fixture files\n├── helpers.nim              # Shared test utilities specific to your project\n└── test_all.nim             # Main test runner\n```\n\n## CI/CD Integration\n\nnimtest is designed to work well in CI/CD environments:\n\n- Compatible with GitHub Actions, GitLab CI, and other systems\n- Cross-platform support (Linux, Windows, macOS)\n- Multiple report formats (JSON, JUnit XML) for CI integration\n- Console output formatted for CI logs\n\n## Best Practices\n\n1. **Always use TestContext**: Create and clean up contexts properly for resource management\n2. **Use setup/teardown**: Initialize resources in setup, clean up in teardown\n3. **Use descriptive test names**: Make test names clear and specific\n4. **Test one thing per test**: Keep tests focused on a single functionality\n5. **Use meaningful assertions**: Provide clear messages for failed assertions\n6. **Clean up resources**: Always ensure temporary files and directories are cleaned up\n7. **Use performance utilities**: Measure and track performance of critical operations\n8. **Generate reports**: Use reporting utilities to track test results over time\n\n## Roadmap\n\nnimtest has an ambitious roadmap for 2026 focused on usability, performance, and observability. See [ROADMAP.md](docs/ROADMAP.md) for the complete strategic plan including:\n\n- **Q1 2026 (v1.1)**: Macro DSL for tests, CLI runner binary, enhanced assertions\n- **Q2 2026 (v1.2)**: Parallel execution, async/await support, E2E integration lanes\n- **Q3 2026 (v1.3)**: Interactive HTML reports, coverage integration, fuzzing hooks\n- **Q4 2026+**: Wild cards including AI-assisted test generation and compile-time fuzzing\n\n**Contribute**: Help shape the future by participating in roadmap discussions on the [Nim Forum](https://forum.nim-lang.org/) or [GitHub Discussions](https://github.com/codenimja/nimtest/discussions).\n\n## Dependencies\n\n- `nim \u003e= 2.0.0`\n- `std/unittest` (built-in)\n- `std/os` (built-in)\n- `std/osproc` (built-in)\n- `std/json` (built-in)\n- `std/parseutils` (built-in)\n\n## License\n\nMIT License - See LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenimja%2Fnimtest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodenimja%2Fnimtest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenimja%2Fnimtest/lists"}