Skip to content

Commit 8c482ee

Browse files
roxblnfkroxblnfk
committed
Improve docs about events
1 parent 0f72027 commit 8c482ee

File tree

4 files changed

+86
-155
lines changed

4 files changed

+86
-155
lines changed

‎CLAUDE.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,17 @@ npm run docs:preview # Preview build
8787
| callable | вызываемый | вызываемый объект | В контексте |
8888
| closure | закрытие | замыкание | |
8989

90+
### Иерархия Testo
91+
92+
Важно понимать правильную иерархию компонентов:
93+
94+
1. **Test Suite** (комплект тестов) - Unit, Integration, Feature
95+
- События: `TestSuite*` (TestSuiteStarting, TestSuiteFinished)
96+
2. **Test Case** (тестовый класс) - UserTest, OrderTest
97+
- События: `TestCase*` (TestCaseStarting, TestCaseFinished)
98+
3. **Test** (тестовый метод или функция) - testLogin(), testCreate()
99+
- События: `Test*` (TestStarting, TestFinished, TestBatchStarting)
100+
90101
### Специфичные фразы
91102

92103
| Английский | ❌ Неправильно | ✅ Правильно |

‎docs/events.md‎

Lines changed: 35 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -46,44 +46,46 @@ class MyPlugin
4646

4747
Events fire at three levels of granularity:
4848

49-
### Suite Level
49+
### Test Suite Level
5050

51-
One test class = one suite. Contains multiple test cases (methods).
51+
Test Suite (Unit, Integration, etc.) defined in configuration. Contains multiple test cases (classes).
5252

5353
```
54-
TestSuitePipelineStarting # Before suite interceptors
55-
TestSuiteStarting # Suite execution begins
54+
TestSuitePipelineStarting # Before test suite interceptors
55+
TestSuiteStarting # Test suite execution begins
5656
... test cases run ...
57-
TestSuiteFinished # Suite execution ends
58-
TestSuitePipelineFinished # After suite interceptors
57+
TestSuiteFinished # Test suite execution ends
58+
TestSuitePipelineFinished # After test suite interceptors
5959
```
6060

61-
### Case Level
61+
### Test Case Level
6262

63-
One test method = one case. May contain multiple test runs (via data providers or retries).
63+
One test class = one test case. Contains multiple test methods.
6464

6565
```
66-
TestCasePipelineStarting # Before case interceptors
67-
TestCaseStarting # Case execution begins
68-
... test batches run ...
69-
TestCaseFinished # Case execution ends
70-
TestCasePipelineFinished # After case interceptors
66+
TestCasePipelineStarting # Before test case interceptors
67+
TestCaseStarting # Test case execution begins
68+
... test methods run ...
69+
TestCaseFinished # Test case execution ends
70+
TestCasePipelineFinished # After test case interceptors
7171
```
7272

73-
### Test Level
73+
### Test Method Level
7474

75-
One execution of a test = one test run. This is the most granular level.
75+
One test method. May contain multiple test runs (via data providers or retries).
7676

7777
```
78-
TestPipelineStarting # Before test interceptors
78+
TestPipelineStarting # Before test method interceptors
7979
TestBatchStarting # Batch begins (for data providers/retries)
8080
TestStarting # Single test run starts
81+
... test execution ...
8182
TestFinished # Single test run ends
8283
TestRetrying # (optional) Test will be retried
8384
TestStarting # Retry attempt starts
85+
... test execution ...
8486
TestFinished # Retry attempt ends
8587
TestBatchFinished # Batch ends
86-
TestPipelineFinished # After test interceptors
88+
TestPipelineFinished # After test method interceptors
8789
```
8890

8991
## Event Ordering Rules
@@ -98,20 +100,20 @@ TestPipelineFinished # After test interceptors
98100

99101
3. **Hierarchy flows downward:**
100102
```
101-
Suite Pipeline Start
102-
Suite Start
103-
Case Pipeline Start
104-
Case Start
105-
Test Pipeline Start
106-
Batch Start
107-
Test Start
108-
Test Finish
109-
Batch Finish
110-
Test Pipeline Finish
111-
Case Finish
112-
Case Pipeline Finish
113-
Suite Finish
114-
Suite Pipeline Finish
103+
Test Suite Pipeline Start (TestSuitePipelineStarting)
104+
Test Suite Start (TestSuiteStarting)
105+
Test Case Pipeline Start (TestCasePipelineStarting)
106+
Test Case Start (TestCaseStarting)
107+
Test Method Pipeline Start (TestPipelineStarting)
108+
Batch Start (TestBatchStarting)
109+
Test Start (TestStarting)
110+
Test Finish (TestFinished)
111+
Batch Finish (TestBatchFinished)
112+
Test Method Pipeline Finish (TestPipelineFinished)
113+
Test Case Finish (TestCaseFinished)
114+
Test Case Pipeline Finish (TestCasePipelineFinished)
115+
Test Suite Finish (TestSuiteFinished)
116+
Test Suite Pipeline Finish (TestSuitePipelineFinished)
115117
```
116118

117119
4. **Batches group runs:**
@@ -152,61 +154,19 @@ $events->addListener(TestResultEvent::class, function (TestResultEvent $event) {
152154
});
153155
```
154156

155-
### Listen to All Case Events
157+
### Listen to All Test Case Events
156158

157159
```php
158160
use Testo\Test\Event\TestCase\TestCaseEvent;
159161

160162
$events->addListener(TestCaseEvent::class, function (TestCaseEvent $event) {
161-
// Fires for all TestCase* events
163+
// Fires for all TestCase* events (test case level)
162164
$this->trackCase($event->caseInfo);
163165
});
164166
```
165167

166168
This is useful when you don't care about the specific event type, only the data it carries.
167169

168-
## Common Use Cases
169-
170-
### Collecting Test Metrics
171-
172-
```php
173-
$events->addListener(TestFinished::class, function (TestFinished $event) {
174-
$duration = $event->testResult->executionTime;
175-
$memory = $event->testResult->memoryUsage;
176-
177-
$this->metrics->record($event->testInfo->name, $duration, $memory);
178-
});
179-
```
180-
181-
### Custom Test Output
182-
183-
```php
184-
$events->addListener(TestCaseStarting::class, function (TestCaseStarting $event) {
185-
echo "Running: {$event->caseInfo->className}::{$event->caseInfo->methodName}\n";
186-
});
187-
```
188-
189-
### Retry Notifications
190-
191-
```php
192-
$events->addListener(TestRetrying::class, function (TestRetrying $event) {
193-
$this->logger->warning(
194-
"Retrying test {$event->testInfo->name}, attempt {$event->attempt}"
195-
);
196-
});
197-
```
198-
199-
### Integration with External Tools
200-
201-
```php
202-
$events->addListener(TestSuiteFinished::class, function (TestSuiteFinished $event) {
203-
$this->externalReporter->sendSuiteResults(
204-
$event->suiteInfo,
205-
$event->suiteResult
206-
);
207-
});
208-
```
209-
210170
## Custom Event Dispatcher
211171

212172
Testo uses PSR-14 compliant event dispatcher. You can replace it via the [plugin system](./plugins.md) by providing your own `EventDispatcherInterface` and `EventListenerCollector` implementations (PSR-14 doesn't define listener configuration, so Testo uses `EventListenerCollector` as the API for this).

‎ru/docs/cli-reference.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

1111
### `testo run`
1212

13-
Выполнить комплекты тестов с опциональной фильтрацией и форматированием вывода.
13+
Выполнить Test Suite с опциональной фильтрацией и форматированием вывода.
1414

1515
Это команда по умолчанию и может быть опущена при использовании флагов.
1616

@@ -73,16 +73,16 @@ Testo предоставляет три типа фильтров, которы
7373

7474
#### `--suite`
7575

76-
Фильтрация тестов по имени комплекта тестов. Комплекты определяются в конфигурации.
76+
Фильтрация тестов по имени Test Suite. Test Suite определяются в конфигурации.
7777

7878
**Повторяемый:** Да (логика ИЛИ)
7979

8080
**Примеры:**
8181
```bash
82-
# Один набор
82+
# Один Test Suite
8383
testo run --suite=Unit
8484

85-
# Несколько наборов
85+
# Несколько Test Suite
8686
testo run --suite=Unit --suite=Integration
8787
```
8888

‎ru/docs/events.md‎

Lines changed: 36 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -46,44 +46,46 @@ class MyPlugin
4646

4747
События генерируются на трёх уровнях детализации:
4848

49-
### Уровень набора
49+
### Уровень Test Suite
5050

51-
Один тестовый класс = один набор. Содержит несколько тестовых кейсов (методов).
51+
Test Suite (Unit, Integration и т.д.), определённые в конфигурации. Содержат несколько тестовых классов (Test Cases).
5252

5353
```
54-
TestSuitePipelineStarting # Перед перехватчиками набора
55-
TestSuiteStarting # Начинается выполнение набора
56-
... выполняются тестовые кейсы ...
57-
TestSuiteFinished # Завершается выполнение набора
58-
TestSuitePipelineFinished # После перехватчиков набора
54+
TestSuitePipelineStarting # Перед перехватчиками Test Suite
55+
TestSuiteStarting # Начинается выполнение Test Suite
56+
... выполняются тестовые классы ...
57+
TestSuiteFinished # Завершается выполнение Test Suite
58+
TestSuitePipelineFinished # После перехватчиков Test Suite
5959
```
6060

61-
### Уровень кейса
61+
### Уровень Test Case
6262

63-
Один тестовый метод = один кейс. Может содержать несколько запусков теста (через провайдеры данных или повторные попытки).
63+
Один тестовый класс = один Test Case. Содержит несколько тестовых методов.
6464

6565
```
66-
TestCasePipelineStarting # Перед перехватчиками кейса
67-
TestCaseStarting # Начинается выполнение кейса
68-
... выполняются пакеты тестов ...
69-
TestCaseFinished # Завершается выполнение кейса
70-
TestCasePipelineFinished # После перехватчиков кейса
66+
TestCasePipelineStarting # Перед перехватчиками Test Case
67+
TestCaseStarting # Начинается выполнение Test Case
68+
... выполняются тестовые методы ...
69+
TestCaseFinished # Завершается выполнение Test Case
70+
TestCasePipelineFinished # После перехватчиков Test Case
7171
```
7272

73-
### Уровень теста
73+
### Уровень тестового метода
7474

75-
Одно выполнение теста = один запуск теста. Это самый детальный уровень.
75+
Один тестовый метод. Может содержать несколько запусков теста (через провайдеры данных или повторные попытки).
7676

7777
```
78-
TestPipelineStarting # Перед перехватчиками теста
78+
TestPipelineStarting # Перед перехватчиками тестового метода
7979
TestBatchStarting # Начинается пакет (для провайдеров данных/повторов)
8080
TestStarting # Начинается один запуск теста
81+
... выполнение теста ...
8182
TestFinished # Завершается один запуск теста
8283
TestRetrying # (опционально) Тест будет повторён
8384
TestStarting # Начинается попытка повтора
85+
... выполнение теста ...
8486
TestFinished # Завершается попытка повтора
8587
TestBatchFinished # Завершается пакет
86-
TestPipelineFinished # После перехватчиков теста
88+
TestPipelineFinished # После перехватчиков тестового метода
8789
```
8890

8991
## Правила упорядочивания событий
@@ -98,20 +100,20 @@ TestPipelineFinished # После перехватчиков тест
98100

99101
3. **Иерархия течёт вниз:**
100102
```
101-
Suite Pipeline Start
102-
Suite Start
103-
Case Pipeline Start
104-
Case Start
105-
Test Pipeline Start
106-
Batch Start
107-
Test Start
108-
Test Finish
109-
Batch Finish
110-
Test Pipeline Finish
111-
Case Finish
112-
Case Pipeline Finish
113-
Suite Finish
114-
Suite Pipeline Finish
103+
Test Suite Pipeline Start (TestSuitePipelineStarting)
104+
Test Suite Start (TestSuiteStarting)
105+
Test Case Pipeline Start (TestCasePipelineStarting)
106+
Test Case Start (TestCaseStarting)
107+
Test Method Pipeline Start (TestPipelineStarting)
108+
Batch Start (TestBatchStarting)
109+
Test Start (TestStarting)
110+
Test Finish (TestFinished)
111+
Batch Finish (TestBatchFinished)
112+
Test Method Pipeline Finish (TestPipelineFinished)
113+
Test Case Finish (TestCaseFinished)
114+
Test Case Pipeline Finish (TestCasePipelineFinished)
115+
Test Suite Finish (TestSuiteFinished)
116+
Test Suite Pipeline Finish (TestSuitePipelineFinished)
115117
```
116118

117119
4. **Пакеты группируют запуски:**
@@ -152,61 +154,19 @@ $events->addListener(TestResultEvent::class, function (TestResultEvent $event) {
152154
});
153155
```
154156

155-
### Слушать все события кейса
157+
### Слушать все события Test Case
156158

157159
```php
158160
use Testo\Test\Event\TestCase\TestCaseEvent;
159161

160162
$events->addListener(TestCaseEvent::class, function (TestCaseEvent $event) {
161-
// Срабатывает для всех событий TestCase*
163+
// Срабатывает для всех событий TestCase* (уровень Test Case)
162164
$this->trackCase($event->caseInfo);
163165
});
164166
```
165167

166168
Это полезно, когда вас не интересует конкретный тип события, а только данные, которые оно несёт.
167169

168-
## Распространённые случаи использования
169-
170-
### Сбор метрик тестов
171-
172-
```php
173-
$events->addListener(TestFinished::class, function (TestFinished $event) {
174-
$duration = $event->testResult->executionTime;
175-
$memory = $event->testResult->memoryUsage;
176-
177-
$this->metrics->record($event->testInfo->name, $duration, $memory);
178-
});
179-
```
180-
181-
### Пользовательский вывод тестов
182-
183-
```php
184-
$events->addListener(TestCaseStarting::class, function (TestCaseStarting $event) {
185-
echo "Running: {$event->caseInfo->className}::{$event->caseInfo->methodName}\n";
186-
});
187-
```
188-
189-
### Уведомления о повторах
190-
191-
```php
192-
$events->addListener(TestRetrying::class, function (TestRetrying $event) {
193-
$this->logger->warning(
194-
"Retrying test {$event->testInfo->name}, attempt {$event->attempt}"
195-
);
196-
});
197-
```
198-
199-
### Интеграция с внешними инструментами
200-
201-
```php
202-
$events->addListener(TestSuiteFinished::class, function (TestSuiteFinished $event) {
203-
$this->externalReporter->sendSuiteResults(
204-
$event->suiteInfo,
205-
$event->suiteResult
206-
);
207-
});
208-
```
209-
210170
## Пользовательский диспетчер событий
211171

212172
Testo использует совместимый с PSR-14 диспетчер событий. Вы можете заменить его через [систему плагинов](./plugins.md), предоставив свои собственные реализации `EventDispatcherInterface` и `EventListenerCollector` (PSR-14 не определяет конфигурацию слушателей, поэтому Testo использует `EventListenerCollector` в качестве API для этого).

0 commit comments

Comments
 (0)