Agenix.Api 0.1.0-alpha0104

<div align="center">

<img src=".assets/logos/agenix-logo-social.png" alt="Agenix Framework Logo" width="1280"/>

<h1>🧪 Agenix Test Automation Framework</h1>

<p><strong>Test the Pieces.Verify the Whole.</strong></p> <p><em>Intelligent integration testing framework for modern applications</em></p>

<p> <a href="https://github.com/agenixframework/Agenix/actions"> <img src="https://github.com/agenixframework/Agenix/actions/workflows/dotnet-pr-check.yml/badge.svg" alt="CI Status"/> </a> <a href="https://www.nuget.org/packages/Agenix.Core/"> <img src="https://img.shields.io/nuget/v/Agenix.Core.svg" alt="NuGet Version"/> </a> <a href="https://github.com/agenixframework/agenix/blob/master/LICENSE"> <img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"/> </a> </p>

</div>

Agenix is a comprehensive test automation framework built with C# .NET 8.0 that enables the creation of fully automated end-to-end use case tests for enterprise SOA applications. Designed with modern testing patterns and practices, Agenix provides a robust foundation for testing complex distributed systems, APIs, databases, and user workflows.

Key Features

• 🎭 Screenplay Pattern: Actor-based testing with fluent, readable test scenarios using Tasks, Questions, and Abilities
• 🌐 Multi-Protocol Support: Built-in support for HTTP/REST APIs, SQL databases, and web services
• 🔧 Framework Integration: Seamless integration with NUnit and Reqnroll (SpecFlow successor) for BDD testing
• ✅ Rich Validation: Comprehensive validation capabilities for JSON, text, binary data, and custom formats
• 🏗️ Modular Architecture: Clean separation of concerns with extensible, plugin-based design
• 📊 Advanced Reporting: Detailed test execution reports with contextual information
• 🔄 Enterprise Ready: Built for complex SOA environments with session management and context handling

What Makes Agenix Different

Unlike traditional testing frameworks, Agenix focuses on business-readable test automation that bridges the gap between technical implementation and business requirements. The framework's Screenplay pattern allows you to write tests that read like natural language while maintaining the full power of programmatic test automation.

️ Framework Origins

This framework is based on the Citrus Framework, originally developed for Java-based integration testing. Key portions of this .NET implementation were derived from and inspired by the Citrus Framework codebase.

• Original Citrus Framework: Copyright (C) 2006-2024 the original author or authors
• License: Both projects are licensed under Apache License 2.0
• Agenix Implementation: Copyright (C) 2025 Agenix

We extend our gratitude to the Citrus Framework maintainers and contributors for their excellent work that served as the foundation for this .NET adaptation.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

This project includes software derived from the Citrus Framework - see the NOTICE file for additional attribution details.

Related Projects

• Citrus Framework (Java) - The original framework that inspired this implementation

Table of Contents

• Overview
• Prerequisites
• Getting Started
• Module overview
• Development Guidelines

Overview

Agenix.ATF is a comprehensive test framework built on .NET 8.0, designed to provide robust testing capabilities with modern testing patterns and practices.

Technologies Used

• .NET 8.0 - Target framework
• C# 12.0 - Programming language
• NUnit 3.x-4.x - Testing framework
• NSubstitute - Mocking library

Prerequisites

Before you begin, ensure you have the following installed:

• .NET 8.0 SDK or later
• JetBrains Rider (recommended) or Visual Studio 2022+
• Git for version control

Getting Started

1. Clone the Repository

git clone <repository-url>
cd Agenix.ATF

Module Overview

🏗️ Core Framework Modules

🌐 Protocol & Communication Modules

🎭 Testing Pattern Implementations

🔌 Framework Integration Modules

✅ Validation & Assertion Modules

🧪 Test Project Modules

📋 Configuration & Support Files

🎯 Framework Capabilities

Development Guidelines

🛠️ Prerequisites

• .NET 8.0 SDK or later
• JetBrains Rider or Visual Studio 2022 (recommended IDEs)
• Git for version control
• NuGet package manager

📝 Coding Standards

Naming Conventions

• Classes: PascalCase (CustomerService, HttpRequestBuilder)
• Methods: PascalCase (PerformAs, AnsweredBy)
• Properties: PascalCase (Name, RequestUrl)
• Fields: camelCase with underscore prefix for private (_httpClient, _connectionString)
• Constants: PascalCase (MaxRetryCount, DefaultTimeout)
• Interfaces: PascalCase with 'I' prefix (IPerformable, IQuestion<T>)

Code Style

• File scoped namespaces for new files
• Primary constructors where appropriate (C# 12 feature)
• Expression-bodied members for simple implementations
• Nullable reference types enabled
• XML documentation for public APIs

🧪 Testing Guidelines

Test Structure

• Arrange-Act-Assert pattern for unit tests
• Given-When-Then structure for BDD scenarios
• Descriptive test names that explain the scenario

Test Categories

• Unit Tests: Fast, isolated, test single components
• Integration Tests: Test component interactions
• Acceptance Tests: End-to-end business scenarios using Screenplay pattern

🔧 Development Workflow

Branch Strategy

1. main: Production-ready code
2. develop: Integration branch for features
3. feature/: Individual feature development
4. bugfix/: Bug fixes
5. release/: Release preparation

Commit Guidelines

• Use conventional commits format:

  type(scope): description
  
  feat(screenplay): add question chaining support
  fix(http): resolve timeout issue in HttpClient
  docs(readme): update installation instructions
  test(validation): add binary comparison tests
  

📦 Dependencies

Core Dependencies

• NUnit 4.x: Primary testing framework
• NSubstitute/Moq: Mocking library
• Newtonsoft.Json: JSON processing
• System.Net.Http: HTTP client operations

Adding New Dependencies

1. Evaluate necessity and alternatives
2. Check license compatibility
3. Add to appropriate project only
4. Update documentation

🚀 Building and Testing

Local Development

# Restore packages
dotnet restore

# Build solution
dotnet build

# Run all tests
dotnet test

# Run specific test project
dotnet test Agenix.Screenplay.Tests

IDE Configuration

• EditorConfig settings are enforced
• ReSharper/Rider settings in .sln.DotSettings
• License headers automatically applied using templates

📋 Pull Request Guidelines

Before Submitting

• All tests pass locally
• Code follows established conventions
• XML documentation added for public APIs
• License headers present in new files
• Breaking changes documented

PR Description Should Include

• What: Brief description of changes
• Why: Reason for the change
• How: Technical approach used
• Testing: How the change was tested
• Breaking Changes: Any breaking changes

🐛 Issue Reporting

When reporting issues, please include:

• Framework version
• Target framework (.NET version)
• Minimal reproduction case
• Expected vs actual behavior
• Environment details (OS, IDE, etc.)

🔒 Security Considerations

• No hardcoded credentials in code or tests
• Sensitive data should use configuration or environment variables
• Dependencies regularly updated for security patches
• Test data should not contain real customer information