Merge branch 'refs/heads/1.x' into feat/add-assert-equal-not-equal

Author: roxblnfk

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-    <a href="#installation"><img alt="TESTO"
+    <a href="#get-started"><img alt="TESTO"
          src="https://github.com/php-testo/.github/blob/1.x/resources/logo-full.svg?raw=true"
          style="width: 2in; display: block"
     /></a>
@@ -16,7 +16,13 @@
 
 <br />
 
-## Installation
+Testo is an extensible testing framework built on a lightweight core with a middleware system.
+It gives you full control over your testing environment while keeping the familiar PHP syntax you already know.
+
+
+## Get Started
+
+### Installation
 
 ```bash
 composer require testo/testo
@@ -27,6 +33,93 @@ composer require testo/testo
 [![License](https://img.shields.io/packagist/l/testo/testo.svg?style=flat-square)](LICENSE.md)
 [![Total Destroys](https://img.shields.io/packagist/dt/testo/testo.svg?style=flat-square)](https://packagist.org/packages/testo/testo/stats)
 
+### Configuration
+
+By default, if no configuration file is provided, Testo will run tests from the `tests` folder.
+
+To customize the configuration, create a `testo.php` file in the root of your project:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Testo\Config\ApplicationConfig;
+use Testo\Config\SuiteConfig;
+use Testo\Config\FinderConfig;
+
+return new ApplicationConfig(
+    suites: [
+        new SuiteConfig(
+            name: 'Unit',
+            location: new FinderConfig(
+                include: ['tests/Unit'],
+            ),
+        ),
+    ],
+);
+```
+
+### Running Tests
+
+To run your tests, execute:
+
+```bash
+vendor/bin/testo
+```
+
+### Writing Your First Test
+
+Create a test class in the configured test directory (e.g., `tests/CalculatorTest.php`):
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use Testo\Assert;
+use Testo\Attribute\Test;
+use Testo\Attribute\RetryPolicy;
+use Testo\Attribute\ExpectException;
+
+final class CalculatorTest
+{
+    #[Test]
+    public function dividesNumbers(): void
+    {
+        $result = 10 / 2;
+
+        Assert::same(5.0, $result);
+        Assert::notSame(5, $result); // Types matter!
+    }
+
+    #[Test]
+    #[RetryPolicy(maxAttempts: 3)]
+    public function flakyApiCall(): void
+    {
+        // Retries up to 3 times if test fails
+        $response = $this->makeExternalApiCall();
+
+        Assert::same(200, $response->status);
+    }
+
+    #[Test]
+    #[ExpectException(\RuntimeException::class)]
+    public function throwsException(): void
+    {
+        throw new \RuntimeException('Expected error');
+    }
+}
+```
+
+What to note:
+- Use the `#[Test]` attribute to mark test methods
+- Test classes don't need to extend any base class
+- Use `Assert` class for assertions (`same`, `true`, `false`, `null`, `contains`, `instanceOf`, etc.)
+- Testo provides multiple attributes to extend testing capabilities (retry policies, exception handling, and more)
+
 ## IDE Support
 
 Testo comes with the [IDEA plugin `Testo`](https://plugins.jetbrains.com/plugin/28842-testo?noRedirect=true).

src/Application.php

@@ -7,6 +7,7 @@
 use Testo\Common\Container;
 use Testo\Common\Filter;
 use Testo\Common\Internal\ObjectContainer;
+use Testo\Common\Path;
 use Testo\Config\ApplicationConfig;
 use Testo\Config\Internal\ConfigInflector;
 use Testo\Config\ServicesConfig;
@@ -39,13 +40,13 @@ public static function createFromConfig(
     /**
      * Create the application instance from ENV, CLI arguments, and config file.
      *
-     * @param non-empty-string|null $xml Path to XML file or raw XML content
+     * @param Path|null $configFile Path to config file
      * @param array<string, mixed> $inputOptions Command-line options
      * @param array<string, mixed> $inputArguments Command-line arguments
      * @param array<string, string> $environment Environment variables
      */
     public static function createFromInput(
-        ?string $xml = null,
+        ?Path $configFile = null,
         array $inputOptions = [],
         array $inputArguments = [],
         array $environment = [],
@@ -57,8 +58,20 @@ public static function createFromInput(
             'inputOptions' => $inputOptions,
         ];
 
-        # Read XML config file
-        // $xml === null or $args['xml'] = $this->readConfig($xml);
+        # Bind reading provided config file
+        $configFile === null or $container
+            ->bind(ApplicationConfig::class, function () use ($configFile): ApplicationConfig {
+                $cfg = include $configFile;
+                $cfg instanceof ApplicationConfig or throw new \InvalidArgumentException(
+                    \sprintf(
+                        'Configuration file %s must return an instance of %s, %s returned.',
+                        $configFile,
+                        ApplicationConfig::class,
+                        \is_object($cfg) ? \get_class($cfg) : \gettype($cfg),
+                    ),
+                );
+                return $cfg;
+            });
 
         # Register Config inflector
         $container->addInflector($container->make(ConfigInflector::class, $args));

src/Assert/Interceptor/ObjectTrackerInterceptor.php

@@ -4,10 +4,7 @@
 
 namespace Testo\Assert\Interceptor;
 
-use Testo\Assert\State;
 use Testo\Assert\State\AssertException;
-use Testo\Assert\State\Record;
-use Testo\Assert\State\Success;
 use Testo\Assert\StaticState;
 use Testo\Interceptor\TestRunInterceptor;
 use Testo\Test\Dto\Status;

src/Common/Command/Base.php

@@ -12,9 +12,7 @@
 use Symfony\Component\Console\Style\SymfonyStyle;
 use Testo\Application;
 use Testo\Common\Container;
-use Testo\Config\ApplicationConfig;
-use Testo\Config\FinderConfig;
-use Testo\Config\SuiteConfig;
+use Testo\Common\Path;
 use Yiisoft\Injector\Injector;
 
 /**
@@ -72,17 +70,12 @@ protected function execute(
         InputInterface $input,
         OutputInterface $output,
     ): int {
-        $cfg = new ApplicationConfig(
-            src: new FinderConfig(['src']),
-            suites: [
-                new SuiteConfig(
-                    name: 'default',
-                    location: new FinderConfig(['tests/Testo']),
-                ),
-            ],
+        $this->application = Application::createFromInput(
+            configFile: $this->getConfigFile($input),
+            inputOptions: $input->getOptions(),
+            inputArguments: $input->getArguments(),
+            environment: \getenv(),
         );
-
-        $this->application = Application::createFromConfig($cfg);
         $this->container = $this->application->getContainer();
 
         $this->container->set($input, InputInterface::class);
@@ -91,4 +84,30 @@ protected function execute(
 
         return $this->container->get(Injector::class)->invoke($this) ?? Command::SUCCESS;
     }
+
+    /**
+     * Resolves configuration file path from input or default location.
+     *
+     * @param InputInterface $input Command input
+     *
+     * @return Path|null Path to the configuration file
+     */
+    protected function getConfigFile(InputInterface $input): ?Path
+    {
+        /** @var string|null $config */
+        $config = $input->getOption('config');
+        $isConfigured = $config !== null;
+        // $config ??= './testo.xml';
+        $config ??= './testo.php';
+
+        if (\is_file($config)) {
+            return Path::create($config);
+        }
+
+        $isConfigured and throw new \InvalidArgumentException(
+            'Configuration file not found: ' . $config,
+        );
+
+        return null;
+    }
 }

src/Common/Command/Run.php

@@ -6,7 +6,6 @@
 
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
-use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;

src/Render/Terminal/Formatter.php

@@ -265,7 +265,6 @@ public static function assertionHistoryHeader(OutputFormat $format): string
      * Formats a single assertion line.
      *
      * @param \Testo\Assert\State\Record $assertion
-     * @param OutputFormat $format
      * @return non-empty-string
      */
     public static function assertionLine(object $assertion, OutputFormat $format): string

src/Render/TerminalInterceptor.php

@@ -8,7 +8,6 @@
 use Testo\Interceptor\TestRunInterceptor;
 use Testo\Interceptor\TestSuiteRunInterceptor;
 use Testo\Render\Terminal\ColorMode;
-use Testo\Render\Terminal\OutputFormat;
 use Testo\Render\Terminal\Style;
 use Testo\Render\Terminal\TerminalLogger;
 use Testo\Test\Dto\CaseInfo;

testo.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+use Testo\Config\ApplicationConfig;
+use Testo\Config\SuiteConfig;
+
+return new ApplicationConfig(
+    suites: [
+        new SuiteConfig(
+            name: 'default',
+            location: new \Testo\Config\FinderConfig(
+                include: ['tests/Testo'],
+            ),
+        ),
+    ],
+);