Add comprehensive testing guidelines for contributor alignment

To ensure our quality standards remain consistent as the project grows, I’ve
compiled these implicit practices into a formal set of testing guidelines.

This documentation is a shared philosophy designed to keep our tests
maintainable and meaningful. I’ve focused on three core pillars:

1. Data-Driven Testing: Encouraging the use of data providers to
   exhaustively cover edge cases without cluttering test logic.
2. Black-Box Philosophy: Prioritizing the testing of public behavior
   over internal implementation details to ensure refactors don't
   unnecessarily break tests.
3. Real Instances over Mocks: Emphasizing the use of actual objects
   wherever possible. This avoids the "brittle test" trap where mocks
   pass even when the underlying integration is broken.

Assisted-by: OpenCode (GLM-4.6)
Assisted-by: Gemini 3 (Thinking)

Author: henriquemoody

AGENTS.md

@@ -15,6 +15,10 @@ This file contains instructions for AI agents working on this repository.
 ## Testing & Quality Standards
 
 - **Unit tests**: Located in `tests/Unit/`
+- **Testing guidelines**: See `docs/contributing/testing-guidelines.md` for patterns
+- **Data-driven testing**: Use comprehensive providers with descriptive keys
+- **Arrange-Act-Assert**: Structure tests with clear setup, action, and assertion sections
+- **No mocks**: Create custom test implementations instead of PHPUnit mocks
 - **All contributions must include tests that pass**
 - **Code style**: Follow PSR-12 coding standard
 - **Static analysis**: Use PHPStan, fix any issues before submitting

CONTRIBUTING.md

@@ -7,6 +7,7 @@ For detailed guidelines, see the [contributing documentation](docs/contributing/
 - [Getting Started](docs/contributing/getting-started.md) - Set up your development environment
 - [Guidelines](docs/contributing/guidelines.md) - Best practices
 - [Adding Formatters](docs/contributing/adding-formatters.md) - How to create new formatters
+- [Testing Guidelines](docs/contributing/testing-guidelines.md) - Testing standards and patterns
 - [Development](docs/contributing/development.md) - Testing, linting, and static analysis
 - [Submitting Changes](docs/contributing/submitting-changes.md) - Pull request process
 - [Commit Guidelines](docs/contributing/commit-guidelines.md) - How to write good commit messages

docs/contributing/testing-guidelines.md

@@ -0,0 +1,168 @@
+# Testing Guidelines
+
+This document outlines the testing standards and practices for contributions to StringFormatter.
+
+## Core Testing Principles
+
+1. Use Data-Driven Testing: Create comprehensive data providers with descriptive string keys
+2. Test behaviors, not implementations: Focus on input/output results through public interfaces
+3. Use real instances: Avoid PHPUnit mocks - create custom test implementations when needed
+4. Black box testing: Verify interactions through results, not internal state
+
+## Test Structure Standards
+
+### Class Organization
+
+- All test classes must be `final`
+- Use the `Respect\StringFormatter\Test\Unit` namespace
+- Add `#[CoversClass(ClassName::class)]` attribute for code coverage
+- Extend `PHPUnit\Framework\TestCase`
+
+### Method Organization
+
+- Use `#[Test]` attribute for test methods
+- Use `#[DataProvider('methodName')]` for parameterized tests
+- Follow naming pattern: `itShould[Behavior]When[Condition]` or `itShould[ExpectedBehavior]`
+
+## Data Provider Patterns
+
+```php
+/ @return array<string, array{0: InputType, 1: TemplateType, 2: ExpectedType}> */
+public static function providerForFeatureName(): array
+{
+    return [
+        'descriptive test case name' => [
+            $input,
+            $template,
+            $expected,
+        ],
+        'another test case' => [
+            $input2,
+            $template2,
+            $expected2,
+        ],
+    ];
+}
+```
+
+### Provider Requirements
+
+- Use descriptive string keys for each test case
+- Document array structure with PHPDoc array shapes
+- Include edge cases, error conditions, and real-world scenarios
+- Test Unicode support and internationalization when applicable
+
+## Test Structure: Arrange-Act-Assert
+
+Follow the Arrange-Act-Assert pattern for clear test organization:
+
+```php
+#[Test]
+public function itShouldFormatTemplateCorrectly(): void
+{
+    // Arrange: Set up test data and objects
+    $parameters = ['name' => 'John'];
+    $template = 'Hello {{name}}!';
+    $expected = 'Hello John!';
+
+    // Act: Execute the method being tested
+    $formatter = new FormatterClass($parameters);
+    $actual = $formatter->format($template);
+
+    // Assert: Verify the result
+    self::assertSame($expected, $actual);
+}
+```
+
+### Pattern Benefits
+
+- **Arrange**: Clearly separates test setup
+- **Act**: Highlights the specific behavior being tested
+- **Assert**: Makes verification explicit and easy to read
+
+## Assertion Patterns
+
+### Primary Assertions
+
+```php
+// Following Arrange-Act-Assert pattern:
+// 1. Arrange: Create formatter and setup (done above)
+// 2. Act: Call format method (done above)
+// 3. Assert: Verify result
+self::assertSame($expected, $actual);
+```
+
+### Exception Testing
+
+```php
+#[Test]
+public function itShouldThrowExceptionForInvalidInput(): void
+{
+    $this->expectException(InvalidFormatterException::class);
+    $this->expectExceptionMessage('Specific error message');
+
+    new FormatterClass($invalidInput);
+}
+```
+
+## Coverage Requirements
+
+### Test Coverage Areas
+
+- Happy Path: Primary functionality with valid inputs
+- Edge Cases: Empty inputs, boundary conditions, malformed data
+- Error Conditions: Invalid inputs, exception scenarios
+- Type Support: All PHP types when the class under test handler mixed types directly
+- Unicode: International characters, emoji, mixed languages
+- Real-world Usage: Email templates, log messages, URLs, etc.
+
+## Code Quality Standards
+
+### Test Organization
+
+- Each test method validates one specific behavior
+- Group related tests logically by feature
+- Keep test setup minimal and inline
+- Use descriptive test case names in data providers
+
+### Documentation Standards
+
+- Document test methods with PHPDoc when behavior isn't obvious
+- Use type annotations for complex parameters in data providers
+- Include real-world examples in test cases
+
+## Dependencies and Mocks
+
+### Preferred Approach
+
+- Create real instances of any objects needed for testing
+- Use custom test implementations instead of PHPUnit mocks
+- Test through public APIs like `format()` and `formatWith()`
+
+### When Custom Implementations Are Needed
+
+```php
+class DumpStringifier implements Stringifier
+{
+    public function stringify(mixed $value): string
+    {
+        return var_export($value, true);
+    }
+}
+```
+
+## Static Analysis Compatibility
+
+- Write tests that pass PHPStan static analysis
+- Use proper type annotations in PHPDoc
+- Ensure test code follows PSR-12 coding standard
+
+## Examples from Codebase
+
+See these test files for reference patterns:
+
+- `tests/Unit/PlaceholderFormatterTest.php` - Data-driven testing with comprehensive providers
+- `tests/Unit/PatternFormatterTest.php` - Exception testing and edge case coverage
+- `tests/Unit/JavascriptFormatterTest.php` - Unicode and internationalization testing
+
+Remember: Tests should be clear, maintainable, and focused on verifying desired behaviors rather than implementation details.