Skip to content

Commit ba1bce7

Browse files
roxblnfkroxblnfk
committed
Refactor docs
1 parent f571a73 commit ba1bce7

File tree

16 files changed

+2801
-48
lines changed

16 files changed

+2801
-48
lines changed

‎.vitepress/config.mts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,20 @@ export default defineConfig({
2828
{ text: 'Getting Started', link: '/docs/getting-started' },
2929
],
3030
},
31+
{
32+
text: 'Guide',
33+
items: [
34+
{ text: 'CLI Reference', link: '/docs/cli-reference' },
35+
{ text: 'Filtering', link: '/docs/filtering' },
36+
{ text: 'Sample Module', link: '/docs/sample-module' },
37+
],
38+
},
39+
{
40+
text: 'Customization',
41+
items: [
42+
{ text: 'Events', link: '/docs/events' },
43+
],
44+
},
3145
],
3246
},
3347
},
@@ -49,6 +63,20 @@ export default defineConfig({
4963
{ text: 'Начало работы', link: '/ru/docs/getting-started' },
5064
],
5165
},
66+
{
67+
text: 'Руководство',
68+
items: [
69+
{ text: 'CLI справка', link: '/ru/docs/cli-reference' },
70+
{ text: 'Фильтрация', link: '/ru/docs/filtering' },
71+
{ text: 'Модуль Sample', link: '/ru/docs/sample-module' },
72+
],
73+
},
74+
{
75+
text: 'Кастомизация',
76+
items: [
77+
{ text: 'События', link: '/ru/docs/events' },
78+
],
79+
},
5280
],
5381
},
5482
outline: {

‎dd/README.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
<p align="center">
2+
<a href="#get-started"><img alt="TESTO"
3+
src="https://github.com/php-testo/.github/blob/1.x/resources/logo-full.svg?raw=true"
4+
style="width: 2in; display: block"
5+
/></a>
6+
</p>
7+
8+
<p align="center">The PHP Testing Framework You Control</p>
9+
10+
<div align="center">
11+
12+
[![Support on Boosty](https://img.shields.io/static/v1?style=flat-square&label=Boosty&message=%E2%9D%A4&logo=Boosty&color=%23F15F2C)](https://boosty.to/roxblnfk)
13+
[![Support on Patreon](https://img.shields.io/static/v1?style=flat-square&label=Patreon&message=%E2%9D%A4&logo=Patreon&color=%23fe0086)](https://patreon.com/roxblnfk)
14+
15+
</div>
16+
17+
Testo (pronounced [test-oh], meaning "dough" in East and South Slavic languages) — is an extensible testing framework for PHP. Built for scenarios requiring complete customization of the testing process: SDKs, framework tools, complex integrations.
18+
19+
Unlike other testing frameworks, Testo provides all at once: familiar and convenient PHP syntax, unprecedented extensibility and customizability, and a simple yet powerful architecture based on a minimal core and middleware system.
20+
21+
Like dough, you can mold and shape it into any testing infrastructure you need.
22+
23+
We believe developers should have full control over their testing environment, and Testo delivers exactly that.
24+
25+
26+
<br />
27+
28+
Testo is an extensible testing framework built on a lightweight core with a middleware system.
29+
It gives you full control over your testing environment while keeping the familiar PHP syntax you already know.
30+
31+
32+
## Get Started
33+
34+
### Installation
35+
36+
```bash
37+
composer require --dev testo/testo *
38+
```
39+
40+
[![PHP](https://img.shields.io/packagist/php-v/testo/testo.svg?style=flat-square&logo=php)](https://packagist.org/packages/testo/testo)
41+
[![Latest Version on Packagist](https://img.shields.io/packagist/v/testo/testo.svg?style=flat-square&logo=packagist)](https://packagist.org/packages/testo/testo)
42+
[![License](https://img.shields.io/packagist/l/testo/testo.svg?style=flat-square)](LICENSE.md)
43+
[![Total Destroys](https://img.shields.io/packagist/dt/testo/testo.svg?style=flat-square)](https://packagist.org/packages/testo/testo/stats)
44+
45+
### Configuration
46+
47+
By default, if no configuration file is provided, Testo will run tests from the `tests` folder.
48+
49+
To customize the configuration, create a `testo.php` file in the root of your project:
50+
51+
```php
52+
<?php
53+
54+
declare(strict_types=1);
55+
56+
use Testo\Config\ApplicationConfig;
57+
use Testo\Config\SuiteConfig;
58+
use Testo\Config\FinderConfig;
59+
60+
return new ApplicationConfig(
61+
suites: [
62+
new SuiteConfig(
63+
name: 'Unit',
64+
location: new FinderConfig(
65+
include: ['tests/Unit'],
66+
),
67+
),
68+
],
69+
);
70+
```
71+
72+
### Running Tests
73+
74+
To run your tests, execute:
75+
76+
```bash
77+
vendor/bin/testo
78+
```
79+
80+
### Writing Your First Test
81+
82+
Create a test class in the configured test directory (e.g., `tests/CalculatorTest.php`):
83+
84+
```php
85+
<?php
86+
87+
declare(strict_types=1);
88+
89+
namespace Tests;
90+
91+
use Testo\Assert;
92+
use Testo\Attribute\Test;
93+
use Testo\Attribute\RetryPolicy;
94+
use Testo\Attribute\ExpectException;
95+
96+
final class CalculatorTest
97+
{
98+
#[Test]
99+
public function dividesNumbers(): void
100+
{
101+
$result = 10 / 2;
102+
103+
Assert::same(5.0, $result);
104+
Assert::notSame(5, $result); // Types matter!
105+
}
106+
107+
#[Test]
108+
#[RetryPolicy(maxAttempts: 3)]
109+
public function flakyApiCall(): void
110+
{
111+
// Retries up to 3 times if test fails
112+
$response = $this->makeExternalApiCall();
113+
114+
Assert::same(200, $response->status);
115+
}
116+
117+
#[Test]
118+
#[ExpectException(\RuntimeException::class)]
119+
public function throwsException(): void
120+
{
121+
throw new \RuntimeException('Expected error');
122+
}
123+
}
124+
```
125+
126+
What to note:
127+
- Use the `#[Test]` attribute to mark test methods
128+
- Test classes don't need to extend any base class
129+
- Use `Assert` class for assertions (`same`, `true`, `false`, `null`, `contains`, `instanceOf`, etc.)
130+
- Testo provides multiple attributes to extend testing capabilities (retry policies, exception handling, and more)
131+
132+
## IDE Support
133+
134+
Testo comes with the [IDEA plugin `Testo`](https://plugins.jetbrains.com/plugin/28842-testo?noRedirect=true).
135+
136+
[![Version](https://img.shields.io/jetbrains/plugin/v/28842-testo?style=flat-square)](https://plugins.jetbrains.com/plugin/28842-testo/versions)
137+
[![Rating](https://img.shields.io/jetbrains/plugin/r/rating/28842-testo?style=flat-square)](https://plugins.jetbrains.com/plugin/28842-testo/reviews)
138+
[![Downloads](https://img.shields.io/jetbrains/plugin/d/28842-testo?style=flat-square)](https://plugins.jetbrains.com/plugin/28842-testo)

‎dd/cli.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Command Line Interface
2+
3+
This document describes the command line interface for Testo.
4+
5+
## Commands
6+
7+
### `run`
8+
9+
Execute test suites with optional filtering and output formatting.
10+
11+
This is the default command and can be omitted when using flags.
12+
13+
```bash
14+
./bin/testo run [options]
15+
./bin/testo [options] # run is optional
16+
```
17+
18+
**Examples:**
19+
```bash
20+
# Explicit run command
21+
./bin/testo run
22+
./bin/testo run --suite=Unit
23+
24+
# Implicit run command (default)
25+
./bin/testo
26+
./bin/testo --suite=Unit
27+
```
28+
29+
## Common Configuration Flags
30+
31+
### `--config`
32+
33+
Specify path to configuration file.
34+
35+
**Default:** `./testo.php`
36+
37+
**Examples:**
38+
```bash
39+
./bin/testo run --config=./custom-testo.php
40+
./bin/testo run --suite=Integration --config=./ci-testo.php
41+
```
42+
43+
## Running Tests
44+
45+
### Output Formatting
46+
47+
#### `--teamcity`
48+
49+
Enable TeamCity service message format for JetBrains IDE integration.
50+
51+
Used by the [Testo plugin](https://plugins.jetbrains.com/plugin/28842-testo) for PHPStorm/IntelliJ IDEA and TeamCity CI server.
52+
53+
**Examples:**
54+
```bash
55+
./bin/testo --teamcity
56+
./bin/testo --suite=Unit --teamcity
57+
```
58+
59+
### Filtering
60+
61+
Testo provides three types of filters that can be combined to selectively run tests.
62+
63+
**Filter Combination Logic:**
64+
- Same type filters use OR logic: `--filter=test1 --filter=test2` → test1 OR test2
65+
- Different type filters use AND logic: `--filter=test1 --suite=Unit` → test1 AND Unit
66+
- Formula: `AND(OR(filters), OR(paths), OR(suites))`
67+
68+
For detailed information about filtering behavior, see [filter.md](filter.md).
69+
70+
#### `--suite`
71+
72+
Filter tests by test suite name. Suites are defined in configuration.
73+
74+
**Repeatable:** Yes (OR logic)
75+
76+
**Examples:**
77+
```bash
78+
# Single suite
79+
./bin/testo run --suite=Unit
80+
81+
# Multiple suites
82+
./bin/testo run --suite=Unit --suite=Integration
83+
```
84+
85+
#### `--path`
86+
87+
Filter test files by glob patterns. Supports wildcards: `*`, `?`, `[abc]`
88+
89+
**Repeatable:** Yes (OR logic)
90+
91+
**Note:** Asterisk `*` is automatically appended if the path doesn't end with a wildcard.
92+
- `tests/Unit` becomes `tests/Unit*`
93+
- `tests/Unit/` becomes `tests/Unit/*`
94+
95+
**Examples:**
96+
```bash
97+
# Matches tests/Unit*
98+
./bin/testo run --path="tests/Unit"
99+
100+
# Matches tests/Unit/*Test.php
101+
./bin/testo run --path="tests/Unit/*Test.php"
102+
103+
# Multiple paths
104+
./bin/testo run --path="tests/Unit" --path="tests/Integration"
105+
106+
# Nested directories
107+
./bin/testo run --path="tests/*/Security/*Test.php"
108+
```
109+
110+
#### `--filter`
111+
112+
Filter tests by class, method, or function names.
113+
114+
**Repeatable:** Yes (OR logic)
115+
116+
**Supported Formats:**
117+
- **Method**: `ClassName::methodName` or `Namespace\ClassName::methodName`
118+
- **FQN**: `Namespace\ClassName` or `Namespace\functionName`
119+
- **Fragment**: `methodName`, `functionName`, or `ShortClassName`
120+
121+
**Examples:**
122+
```bash
123+
# Specific method
124+
./bin/testo run --filter=UserTest::testLogin
125+
126+
# Entire class
127+
./bin/testo run --filter=UserTest
128+
129+
# By FQN
130+
./bin/testo run --filter=Tests\Unit\UserTest
131+
132+
# Method name across all classes
133+
./bin/testo run --filter=testLogin
134+
135+
# Multiple filters (OR)
136+
./bin/testo run --filter=UserTest::testCreate --filter=UserTest::testUpdate
137+
138+
# Combine with other filters (AND)
139+
./bin/testo run --filter=testAuthentication --suite=Unit
140+
./bin/testo run --filter=UserTest --path="tests/Unit"
141+
```
142+
143+
**Filter Behavior:** See [filter.md](filter.md) for details.
144+
145+
### Combining Filters
146+
147+
**Examples:**
148+
```bash
149+
# Name AND suite
150+
./bin/testo run --filter=testLogin --suite=Unit
151+
152+
# Name AND path
153+
./bin/testo run --filter=UserTest --path="tests/Unit"
154+
155+
# All three types (AND)
156+
./bin/testo run --filter=testImportant --path="tests/Unit" --suite=Critical
157+
158+
# Multiple values with multiple types
159+
./bin/testo run \
160+
--filter=testCreate --filter=testUpdate \
161+
--path="tests/Unit" --path="tests/Integration" \
162+
--suite=Critical
163+
```
164+
165+
## Exit Codes
166+
167+
- `0` (SUCCESS): All tests passed
168+
- `1` (FAILURE): One or more tests failed
169+
- `2` (INVALID): Invalid command or configuration

0 commit comments

Comments
 (0)