doc: описание конструктора объекта

2025-04-11 11:11:51 +02:00 · 2024-12-10 23:55:27 +03:00 · 2024-12-10 23:55:27 +03:00 · 453f62c16c
commit 453f62c16c
parent 73b3bfae53
2 changed files with 379 additions and 0 deletions
--- a/documentation/docs/features/test-data/data-generation.md
+++ b/documentation/docs/features/test-data/data-generation.md
@ -161,6 +161,8 @@ toc_max_heading_level: 4
 Возврат Конструктор.Провести();
 ```

+Описание всех методов и примеры можно посмотреть в [описании конструктора объекта](./object-builder.md)
+
 #### Конструктор движения документа

 [`ЮТест.Данные().КонструкторДвижений`](/api/ЮТТестовыеДанные#конструктордвижений) - инструмент, с помощью которого вы можете формировать необходимые для теста движения документа.  
--- a/documentation/docs/features/test-data/object-builder.md
+++ b/documentation/docs/features/test-data/object-builder.md
@ -0,0 +1,377 @@
+# Руководство по использованию инструмента `КонструкторОбъекта`
+
+`Конструктор объекта` является ключевым инструментом для создания тестовых данных в контексте фреймворка YAxUnit. Он реализован как [текучий интерфейс](/docs/getting-started/fluent-api), что позволяет гибко и удобно настраивать объекты, табличные части и реквизиты. Доступ к нему осуществляется через фабрику [`ЮТест.Данные()`](/api/ЮТест#данные)[`.КонструкторОбъекта(<Вид метаданных>)`](/api/ЮТТестовыеДанные#конструкторобъекта).
+
+Это руководство содержит подробное описание методов класса, их параметров, возвращаемых значений, а также примеры использования.
+
+---
+
+## Основные возможности конструктора
+
+1. **Установка значений реквизитов объекта или табличной части.**
+2. **Генерация фиктивных значений для реквизитов.**
+3. **Работа с табличными частями: добавление строк, установка значений.**
+4. **Создание и запись объектов в базу данных.**
+5. **Поддержка текучего интерфейса для последовательной настройки объектов.**
+
+---
+
+## Методы класса
+
+### 1. `Установить(ИмяРеквизита, Значение)`
+
+Устанавливает значение реквизита создаваемого объекта. Если метод вызывается после вызова `ТабличнаяЧасть`, то устанавливается значение реквизита строки табличной части.
+
+- **Параметры:**
+  - `ИмяРеквизита` (Строка): Имя реквизита объекта или табличной части.
+  - `Значение` (Произвольный): Значение реквизита объекта или табличной части.
+
+- **Возвращаемое значение:**
+  - Конструктор для дальнейшей настройки.
+
+**Пример:**
+
+```bsl
+ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .Установить("Номер", "0001")
+    .Установить("Дата", Дата(2023, 10, 01))
+    .Записать();
+```
+
+---
+
+### 2. `УстановитьРеквизиты(ЗначенияРеквизитов)`
+
+Устанавливает значения нескольких реквизитов создаваемого объекта. Если метод вызывается после вызова `ТабличнаяЧасть`, то устанавливаются значения реквизитов строки табличной части.
+
+- **Параметры:**
+  - `ЗначенияРеквизитов` (Структура): Устанавливаемые значения реквизитов в формате `ИмяРеквизита = Значение`.
+
+- **Возвращаемое значение:**
+  - Конструктор для дальнейшей настройки.
+
+**Пример:**
+
+```bsl
+Значения = Новый Структура;
+Значения.Вставить("Номер", "0002");
+Значения.Вставить("Дата", Дата(2023, 10, 02));
+Значения.Вставить("Контрагент", Справочники.Контрагенты.НайтиПоКоду("00001"));
+
+ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .УстановитьРеквизиты(Значения)
+    .Записать();
+```
+
+---
+
+### 3. `Фикция(ИмяРеквизита, РеквизитыЗаполнения, ОграничениеТипа)`
+
+Устанавливает фиктивное значение реквизита создаваемого объекта. Фиктивное значение генерируется на основе типа реквизита:
+- Для примитивных типов — случайное значение.
+- Для ссылочных типов — новый объект.
+- Для перечислений — случайное значение перечисления.
+
+- **Параметры:**
+  - `ИмяРеквизита` (Строка): Имя реквизита объекта или табличной части.
+  - `РеквизитыЗаполнения` (Структура, Неопределено): Значения реквизитов заполнения создаваемого объекта базы.
+  - `ОграничениеТипа` (Тип, ОписаниеТипов, Неопределено): Используется для ограничения типа составного реквизита.
+
+- **Возвращаемое значение:**
+  - Конструктор для дальнейшей настройки.
+
+**Пример:**
+
+```bsl
+ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .Фикция("Контрагент")
+    .Фикция("Сумма", Неопределено, Новый ОписаниеТипов(Тип("Число"), Новый КвалификаторыЧисла(10, 2)))
+    .Записать();
+```
+
+---
+
+### 4. `ФикцияРеквизитов(ИменаРеквизитов)`
+
+Устанавливает фиктивные значения для нескольких реквизитов создаваемого объекта.
+
+- **Параметры:**
+  - `ИменаРеквизитов` (Строка, Массив из Строка): Имена реквизитов объекта или табличной части.
+
+- **Возвращаемое значение:**
+  - Конструктор для дальнейшей настройки.
+
+**Пример:**
+
+```bsl
+ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ФикцияРеквизитов("Контрагент, Сумма, Дата")
+    .Записать();
+```
+
+---
+
+### 5. `ФикцияОбязательныхПолей()`
+
+Автоматически заполняет фиктивными значениями все обязательные поля объекта, определенные в метаданных (с признаком "Проверка заполнения = Выдавать ошибку").
+
+- **Возвращаемое значение:**
+  - Конструктор для дальнейшей настройки.
+
+**Пример:**
+
+```bsl
+ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ФикцияОбязательныхПолей()
+    .Записать();
+```
+
+---
+
+### 6. `ТабличнаяЧасть(ИмяТабличнойЧасти)`
+
+Переключает конструктор на работу с указанной табличной частью объекта.
+
+- **Параметры:**
+  - `ИмяТабличнойЧасти` (Строка): Имя табличной части.
+
+- **Возвращаемое значение:**
+  - Конструктор для дальнейшей настройки.
+
+**Пример:**
+
+```bsl
+ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ТабличнаяЧасть("Товары")
+        .ДобавитьСтроку()
+            .Установить("Номенклатура", Справочники.Номенклатура.НайтиПоКоду("00001"))
+            .Установить("Количество", 10)
+    .Записать();
+```
+
+---
+
+### 7. `ДобавитьСтроку(ЗначенияРеквизитов)`
+
+Добавляет новую строку в табличную часть объекта. При необходимости можно сразу установить значения реквизитов новой строки.
+
+- **Параметры:**
+  - `ЗначенияРеквизитов` (Структура, Неопределено): Устанавливаемые значения реквизитов новой строки.
+
+- **Возвращаемое значение:**
+  - Конструктор для дальнейшей настройки.
+
+**Пример:**
+
+```bsl
+ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ТабличнаяЧасть("Товары")
+        .ДобавитьСтроку()
+            .Установить("Номенклатура", Справочники.Номенклатура.НайтиПоКоду("00001"))
+            .Установить("Количество", 5)
+        .ДобавитьСтроку()
+            .Установить("Номенклатура", Справочники.Номенклатура.НайтиПоКоду("00002"))
+            .Установить("Количество", 3)
+    .Записать();
+```
+
+---
+
+### 8. `Записать(ВернутьОбъект, ОбменДаннымиЗагрузка)`
+
+Создает и записывает объект в базу данных. Возвращает объект или ссылку на него.
+
+- **Параметры:**
+  - `ВернутьОбъект` (Булево): Если `Истина`, возвращает объект, иначе — ссылку.
+  - `ОбменДаннымиЗагрузка` (Булево): Если `Истина`, записывает объект с признаком `ОбменДанными.Загрузка = Истина`.
+
+- **Возвращаемое значение:**
+  - Произвольный: Созданный объект или ссылка на него.
+
+**Пример:**
+
+```bsl
+Ссылка = ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ФикцияОбязательныхПолей()
+    .Записать();
+```
+
+---
+
+### 9. `Провести(ВернутьОбъект)`
+
+Создает, записывает и проводит документ. Возвращает объект или ссылку на него.
+
+- **Параметры:**
+  - `ВернутьОбъект` (Булево): Если `Истина`, возвращает объект, иначе — ссылку.
+
+- **Возвращаемое значение:**
+  - Произвольный: Созданный объект или ссылка на него.
+
+**Пример:**
+
+```bsl
+Ссылка = ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ФикцияОбязательныхПолей()
+    .Провести();
+```
+
+---
+
+### 10. `НовыйОбъект()`
+
+Создает новый объект, но не записывает его в базу данных. Этот метод полезен, если требуется получить объект для дальнейшей работы с ним в тестах, не сохраняя его в базе.
+
+- **Важно:** После создания объекта данные не очищаются, поэтому многократный вызов метода создаст множество одинаковых объектов. Если нужно создать новый объект, необходимо повторно инициировать конструктор.
+
+- **Возвращаемое значение:**
+  - Произвольный: Созданный объект.
+
+**Пример:**
+
+```bsl
+Объект = ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ФикцияОбязательныхПолей()
+    .НовыйОбъект();
+
+// Далее можно работать с объектом, не записывая его в базу
+Сообщить("Номер документа: " + Объект.Номер);
+```
+
+---
+
+### 11. `ДобавитьЗапись(ОбменДаннымиЗагрузка)`
+
+Записывает новый объект в базу данных, но в отличие от методов `Записать` или `Провести` возвращает конструктор, что позволяет продолжить работу по созданию тестовых данных. Этот метод полезен, если требуется записать объект и продолжить настройку других объектов или табличных частей.
+
+- **Параметры:**
+  - `ОбменДаннымиЗагрузка` (Булево): Если `Истина`, записывает объект с признаком `ОбменДанными.Загрузка = Истина`.
+
+- **Важно:** После создания объекта данные не очищаются, поэтому многократный вызов метода создаст множество одинаковых объектов. Если нужно создать новый объект, необходимо повторно инициировать конструктор.
+
+- **Возвращаемое значение:**
+  - Конструктор для дальнейшей настройки.
+
+**Пример:**
+
+```bsl
+ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ФикцияОбязательныхПолей()
+    .ДобавитьЗапись(Истина) // Записываем объект с признаком "ОбменДанными.Загрузка = Истина"
+    .ТабличнаяЧасть("Товары")
+        .ДобавитьСтроку()
+            .Установить("Номенклатура", Справочники.Номенклатура.НайтиПоКоду("00001"))
+    .ДобавитьЗапись(); // Записываем объект без признака "ОбменДанными.Загрузка"
+```
+
+Этот метод позволяет гибко управлять процессом создания и записи объектов, сохраняя возможность продолжить настройку тестовых данных.
+
+---
+
+### 12. `УстановитьСсылкуНового(Значение)`
+
+Устанавливает уникальный идентификатор ссылки для создаваемого объекта. Этот метод полезен, если требуется явно задать идентификатор объекта, например, для создания объекта с заранее известным GUID.
+
+- **Параметры:**
+  - `Значение` (УникальныйИдентификатор, Строка): Уникальный идентификатор ссылки нового объекта. Может быть представлен как строка или объект типа `УникальныйИдентификатор`.
+
+- **Возвращаемое значение:**
+  - Конструктор для дальнейшей настройки.
+
+**Пример:**
+
+```bsl
+ЮТест.Данные().КонструкторОбъекта("Справочник.Контрагенты")
+    .УстановитьСсылкуНового("00000000-0000-0000-0000-000000000001")
+    .ФикцияОбязательныхПолей()
+    .Записать();
+```
+
+---
+
+### 13. `УстановитьДополнительноеСвойство(ИмяСвойства, Значение)`
+
+Устанавливает дополнительное свойство для создаваемого объекта. Этот метод позволяет добавлять произвольные данные, которые не являются реквизитами объекта, но могут быть полезны для тестов.
+
+- **Параметры:**
+  - `ИмяСвойства` (Строка): Имя дополнительного свойства.
+  - `Значение` (Произвольный): Значение дополнительного свойства.
+
+- **Возвращаемое значение:**
+  - Конструктор для дальнейшей настройки.
+
+**Пример:**
+
+```bsl
+ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ФикцияОбязательныхПолей()
+    .УстановитьДополнительноеСвойство("Тег", "ТестовыйДокумент")
+    .Записать();
+```
+
+---
+
+### 14. `Объект()`
+
+Переключает конструктор на заполнение объекта. Этот метод используется для возврата к настройке реквизитов объекта после работы с табличной частью.
+
+- **Возвращаемое значение:**
+  - Конструктор для дальнейшей настройки.
+
+**Пример:**
+
+```bsl
+ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ТабличнаяЧасть("Товары")
+        .ДобавитьСтроку()
+            .Установить("Номенклатура", Справочники.Номенклатура.НайтиПоКоду("00001"))
+    .Объект()
+    .Установить("Контрагент", Справочники.Контрагенты.НайтиПоКоду("00001"))
+    .Записать();
+```
+
+---
+
+### 15. `ДанныеСтроки()`
+
+Возвращает данные текущей строки табличной части объекта. Если конструктор настроен на заполнение объекта, возвращается `Неопределено`.
+
+- **Возвращаемое значение:**
+  - Структура: Данные строки табличной части.
+  - Неопределено: Если заполняется объект.
+
+**Пример:**
+
+```bsl
+ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ТабличнаяЧасть("Товары")
+        .ДобавитьСтроку()
+            .Установить("Номенклатура", Справочники.Номенклатура.НайтиПоКоду("00001"))
+            .Установить("Количество", 10)
+        .ДанныеСтроки(); // Возвращает данные строки табличной части
+```
+
+---
+
+### 16. `ДанныеОбъекта()`
+
+Возвращает данные создаваемого объекта в виде структуры. Этот метод полезен для проверки или использования данных объекта в тестах.
+
+- **Возвращаемое значение:**
+  - Структура: Данные объекта.
+
+**Пример:**
+
+```bsl
+Данные = ЮТест.Данные().КонструкторОбъекта("Документ.ПриходныйОрдер")
+    .ФикцияОбязательныхПолей()
+    .ДанныеОбъекта();
+
+Сообщить("Номер документа: " + Данные.Номер);
+```
+
+---
+
+## Заключение
+
+`Конструктор объекта` предоставляет мощный и гибкий инструмент для создания тестовых данных в 1С. Его текучий интерфейс позволяет легко настраивать объекты, табличные части и реквизиты, а также автоматически генерировать фиктивные значения. Используйте этот класс для упрощения процесса написания тестов и повышения их качества.