Модуль 6. Интеграция программных модулей

Описание задания

Для проверки данных от клиентов разработайте приложение, которое позволяет провести валидацию на корректность данных. Результат проверки необходимо фиксировать в документе ТестКейс.docx.
Сначала заполните в документе ТестКейс.docx столбцы «Действие» и «Ожидаемый результат», используя предоставленный текстовый редактор. Добавьте закладки в столбец «Результат».
Необходимо провести валидацию ФИО клиента на вхождение запрещённых символов. Проверьте два любых критерия.
Для эмуляции отправки данных от клиента необходимо запустить приложение TransferSimulator.exe. Методы эмулятора описаны в файле api_info.pdf.

Макет формы представлен на рисунке.

Макет форма — Рисунок 1 — Макет окна приложения валидации данных.

Логика работы приложения

При нажатии на кнопку «Получить данные» данные загружаются с эмулятора и отображаются на форме.
После нажатия на кнопку «Отправить результат теста» выполняется проверка данных по заполненному шаблону.

Результат проверки отображается:

на форме приложения;
в соответствующей строке таблицы документа ТестКейс.docx в столбце «Результат».

Сведения о реальном API эмулятора (TransferSimulator)

API доступно по адресу http://localhost:4444/TransferSimulator/

Описание методов.

Название метода	Параметры	Описание метода	Формат ответа
`fullName`	GET	Получение данных ФИО клиента	`{ "value": "Соколов& Сокол& Соколович" }`

Во время работы с API возможно получение следующих ошибок: HttpStatusCode: 5xx

1. Теоретические основы

1.1. Понятие валидации данных

Валидация данных — это процесс проверки входных данных на соответствие установленным правилам, форматам и ограничениям перед их обработкой или сохранением в информационной системе.

Валидация данных позволяет:

выявлять ошибки ввода;
предотвращать некорректную обработку информацию;
обеспечивать целостность и достоверность данных;
повышать надёжность информационной системы.

В прикладных информационных системах валидация выполняется:

на стороне клиента (в интерфейсе приложения);
на стороне сервера (в бизнес-логике);
при интеграции с внешними источниками данных.

1.2. Валидация персональных данных клиента

Персональные данные клиента — это сведения, позволяющие идентифицировать физическое лицо и используемые при работе информационной системы.

К персональным данным относятся:

фамилия, имя, отчество (ФИО);
контактные данные;
идентификаторы клиента;
сведения, полученные от внешних систем.

В рамках данного задания объектом валидации является ФИО клиента, получаемое из внешнего источника данных (эмулятора).

1.3. Критерии корректности ФИО

Для проверки корректности ФИО в информационной системе задаются критерии валидации, которым должно соответствовать значение поля.

1.3.1. Проверка на наличие запрещённых символов

ФИО клиента должно содержать только допустимые символы.

Допустимые символы:

буквы кириллицы или латиницы;
пробел;
дефис (-).

Запрещённые символы:

цифры;
специальные символы (@, #, $, %, &, _ и др.);
служебные знаки.

При обнаружении запрещённых символов:

проверка считается не пройденной;
формируется сообщение об ошибке;
результат фиксируется как «Не успешно».

1.3.2. Проверка структуры ФИО

ФИО клиента должно соответствовать установленной структуре.

Требования к структуре ФИО:

состоит из трёх частей: Фамилия Имя Отчество;
части разделены одиночным пробелом;
отсутствуют лишние пробелы в начале и конце строки;
каждая часть содержит не менее двух символов.

Если структура ФИО нарушена, данные считаются некорректными.

1.4. Тестирование и тест-кейсы

Тестирование — это процесс проверки корректности работы программного обеспечения путём выполнения заранее подготовленных сценариев.

Тест-кейс — это описание последовательности действий, ожидаемого и фактического результата проверки.

Тест-кейс включает:

действие пользователя или системы;
ожидаемый результат;
фактический результат выполнения;
статус выполнения (успешно / не успешно).

В рамках задания тест-кейсы оформляются в документе ТестКейс.docx.

1.5. Документирование результатов проверки

Результаты валидации данных фиксируются:

на форме приложения;
в документе ТестКейс.docx в столбце «Результат».

Для автоматической записи результатов используются закладки документа Word, каждая из которых соответствует определённому тест-кейсу.

Использование закладок позволяет:

однозначно определить место записи результата;
автоматизировать заполнение документа;
обеспечить воспроизводимость тестирования.

1.6. Использование эмулятора передачи данных

Для получения входных данных клиента используется приложение TransferSimulator.exe.

Эмулятор позволяет:

имитировать поступление данных от внешней системы;
получать данные по API;
передавать результаты проверки обратно в систему.

Описание методов взаимодействия с эмулятором приведено в файле api_info.pdf.

1.7. Общая логика работы приложения

Работа приложения валидации данных включает следующие этапы:

Получение данных клиента из эмулятора.
Отображение данных на форме приложения.
Запуск проверки данных по заданным критериям.
Формирование результата валидации.
Отображение результата пользователю.
Запись результата в документ ТестКейс.docx.

2. Практическая часть: пошаговое создание приложения (C# WinForms)

2.0. Подготовка файла ТестКейс.docx

2.1. Создание проекта WinForms

Создайте проект

Visual Studio → Create a new project
Выберите Windows Forms App
Имя проекта: ClientValidationApp
Framework: .NET 8 (или нужный по заданию)
Create

2.2. Макет формы (UI)

Разместите элементы на форме (Form1)

Откройте Form1 (Designer) и добавьте:

Поля для данных клиента:

TextBox txtFio (ФИО)

Кнопки:

Button btnGetData — текст: Получить данные
Button btnRunTest — текст: Отправить результат теста

Вывод результата:

Label lblStatus — текст: Статус: —
TextBox txtErrors — Multiline = true, ReadOnly = true (для описания ошибок)

2.3. Подключение NuGet-пакета для Word (закладки)

Вариант для надёжной работы с закладками — Open XML SDK.

Установите пакет Open XML

Project → Manage NuGet Packages
Browse → найдите: DocumentFormat.OpenXml
Install

2.4. Структура кода (рекомендуемая)

Создайте папки/классы в проекте

В Solution Explorer добавьте:

Models/FullNameResponse.cs
Services/SimulatorApiClient.cs
Services/WordTestCaseWriter.cs
Validation/FioValidator.cs

2.5. Модель ответа API

Создайте модель `FullNameResponse`

Ответ метода GET fullName имеет формат:

{ "value": "Соколов& Сокол& Соколович" }

Создайте модель:

namespace ClientValidationApp.Models;

public class FullNameResponse
{
    public string? Value { get; set; }
}

2.6. Клиент для TransferSimulator (получение ФИО)

Реализуйте `SimulatorApiClient` строго под ваш API

Базовые адреса:

базовый адрес (локально): http://localhost:4444/TransferSimulator/
резервный адрес (если Linux/не настроен локальный): http://prb.sylas.ru/TransferSimulator/

Метод получения ФИО:

GET fullName

Возможные ошибки:

HttpStatusCode: 5xx

Замените ваш SimulatorApiClient на версию ниже.

using System.Net.Http.Json;
using ClientValidationApp.Models;

namespace ClientValidationApp.Services;

public class SimulatorApiClient
{
    private readonly HttpClient _http;

    public SimulatorApiClient(string baseUrl)
    {
        // baseUrl должен оканчиваться на /TransferSimulator/
        if (!baseUrl.EndsWith("/")) baseUrl += "/";

        _http = new HttpClient
        {
            BaseAddress = new Uri(baseUrl),
            Timeout = TimeSpan.FromSeconds(10)
        };
    }

    public async Task<string> GetFullNameAsync()
    {
        // GET fullName -> { "value": "..." }
        using var response = await _http.GetAsync("fullName");

        // Явная обработка 5xx (как в условии)
        if ((int)response.StatusCode >= 500)
        {
            throw new HttpRequestException(
                $"Ошибка эмулятора: HttpStatusCode {(int)response.StatusCode} (5xx).",
                null,
                response.StatusCode);
        }

        if (!response.IsSuccessStatusCode)
        {
            throw new HttpRequestException(
                $"Ошибка запроса: {(int)response.StatusCode} {response.ReasonPhrase}",
                null,
                response.StatusCode);
        }

        var dto = await response.Content.ReadFromJsonAsync<FullNameResponse>();

        var fio = dto?.Value ?? "";
        return fio;
    }
}

2.7. Валидация ФИО (2 критерия)

Выбираем:

Запрещённые символы (обязательно)
Структура ФИО из 3 частей (удобный второй критерий)

Реализуйте `FioValidator`

using System.Text.RegularExpressions;

namespace ClientValidationApp.Validation;

public static class FioValidator
{
    // Разрешаем: буквы (рус/лат), пробел, дефис
    private static readonly Regex AllowedCharsRegex =
        new(@"^[A-Za-zА-Яа-яЁё\s\-]+$");

    public static (bool ok, string error) CheckForbiddenSymbols(string fio)
    {
        if (string.IsNullOrWhiteSpace(fio))
            return (false, "ФИО не заполнено.");

        if (!AllowedCharsRegex.IsMatch(fio))
            return (false, "ФИО содержит запрещённые символы (разрешены буквы, пробел, дефис).");

        return (true, "");
    }

    public static (bool ok, string error) CheckThreeParts(string fio)
    {
        fio = fio.Trim();

        // Если хотите считать множественные пробелы ошибкой — оставьте так.
        // Если хотите нормализовать — замените Regex.Replace(fio, @"\s+", " ")
        var parts = fio.Split(' ', StringSplitOptions.RemoveEmptyEntries);

        if (parts.Length != 3)
            return (false, "ФИО должно состоять из 3 частей: Фамилия Имя Отчество.");

        if (parts.Any(p => p.Length < 2))
            return (false, "Каждая часть ФИО должна содержать минимум 2 символа.");

        return (true, "");
    }
}

2.8. Запись результата в Word по закладкам

Подготовьте документ ТестКейс.docx

В столбце «Результат» создайте закладки:
TC_01_Result (для проверки запрещённых символов)
TC_02_Result (для проверки структуры из 3 частей)
Убедитесь, что закладки стоят внутри нужных ячеек.

Реализуйте `WordTestCaseWriter` (OpenXML)

Класс будет:

открывать ТестКейс.docx
находить закладку по имени
заменять текст внутри диапазона закладки на “Успешно” / “Не успешно”

using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Wordprocessing;
using DocumentFormat.OpenXml;

namespace ClientValidationApp.Services;

public class WordTestCaseWriter
{
    public void WriteBookmarkText(string docPath, string bookmarkName, string text)
    {
        using var doc = WordprocessingDocument.Open(docPath, true);
        var body = doc.MainDocumentPart?.Document.Body;
        if (body == null) return;

        var bookmarkStart = body.Descendants<BookmarkStart>()
            .FirstOrDefault(b => b.Name == bookmarkName);

        if (bookmarkStart == null)
            throw new InvalidOperationException($"Закладка '{bookmarkName}' не найдена.");

        // По стандарту у BookmarkStart есть Id; конец — BookmarkEnd с тем же Id
        var bookmarkId = bookmarkStart.Id?.Value;
        var bookmarkEnd = body.Descendants<BookmarkEnd>()
            .FirstOrDefault(b => b.Id?.Value == bookmarkId);

        if (bookmarkEnd == null)
            throw new InvalidOperationException($"Конец закладки '{bookmarkName}' не найден.");

        // Удаляем всё между start и end (если было)
        var current = bookmarkStart.NextSibling();
        while (current != null && current != bookmarkEnd)
        {
            var next = current.NextSibling();
            current.Remove();
            current = next;
        }

        // Вставляем новый текст
        bookmarkStart.Parent!.InsertAfter(
            new Run(new Text(text) { Space = SpaceProcessingModeValues.Preserve }),
            bookmarkStart
        );

        doc.MainDocumentPart!.Document.Save();
    }
}

2.9. Основная логика формы: получить данные → проверить → записать в Word

Подключите сервисы в `Form1`

В Form1.cs добавьте поля:

using ClientValidationApp.Services;
using ClientValidationApp.Validation;

public partial class Form1 : Form
{
    private readonly SimulatorApiClient _api;
    private readonly WordTestCaseWriter _writer;

    // Укажите путь к ТестКейс.docx (можно хранить рядом с exe)
    private readonly string _testCaseDocPath =
        Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "ТестКейс.docx");

    public Form1()
    {
        InitializeComponent();

        // Реальный baseUrl (локальный)
        _api = new SimulatorApiClient("http://localhost:4444/TransferSimulator/");

        // Резервный baseUrl (если Linux/не настроен локальный)
        // _api = new SimulatorApiClient("http://prb.sylas.ru/TransferSimulator/");

        _writer = new WordTestCaseWriter();
    }
}

Практический совет: положите ТестКейс.docx в папку bin/Debug/netX (рядом с .exe), чтобы путь был стабильным.

Реализуйте кнопку «Получить данные» (GET fullName)

private async void btnGetData_Click(object sender, EventArgs e)
{
    try
    {
        lblStatus.Text = "Статус: Получение данных...";
        txtErrors.Clear();

        var fio = await _api.GetFullNameAsync();

        txtFio.Text = fio;
        lblStatus.Text = "Статус: Данные получены.";
    }
    catch (HttpRequestException ex)
    {
        lblStatus.Text = "Статус: Ошибка получения данных.";
        txtErrors.Text = ex.Message;
    }
    catch (TaskCanceledException)
    {
        lblStatus.Text = "Статус: Ошибка получения данных.";
        txtErrors.Text = "Превышено время ожидания ответа от API (Timeout).";
    }
    catch (Exception ex)
    {
        lblStatus.Text = "Статус: Ошибка получения данных.";
        txtErrors.Text = ex.Message;
    }
}

Реализуйте кнопку «Отправить результат теста» (проверка + фиксация в Word)

Здесь выполняем:

TC-01: запрещённые символы
TC-02: 3 части
отображение результата на форме
запись результата в Word

В описании API на текущий момент указан только метод получения ФИО (GET fullName). Метод отправки результата теста через API (POST/PUT) в предоставленном описании не указан, поэтому по кнопке «Отправить результат теста» выполняются проверки и обязательная фиксация в документе ТестКейс.docx в столбце «Результат».

private void btnRunTest_Click(object sender, EventArgs e)
{
    try
    {
        lblStatus.Text = "Статус: Проверка данных...";
        txtErrors.Clear();

        var fio = txtFio.Text ?? "";

        // TC-01: запрещённые символы
        var (ok1, err1) = FioValidator.CheckForbiddenSymbols(fio);
        var tc01 = ok1 ? "Успешно" : "Не успешно";

        // TC-02: структура из 3 частей
        var (ok2, err2) = FioValidator.CheckThreeParts(fio);
        var tc02 = ok2 ? "Успешно" : "Не успешно";

        // Вывод на форму
        var errors = new List<string>();
        if (!ok1) errors.Add($"TC-01: {err1}");
        if (!ok2) errors.Add($"TC-02: {err2}");
        txtErrors.Text = errors.Count == 0
            ? "Ошибок не обнаружено."
            : string.Join(Environment.NewLine, errors);

        // Запись в Word (в столбец «Результат» по закладкам)
        _writer.WriteBookmarkText(_testCaseDocPath, "TC_01_Result", tc01);
        _writer.WriteBookmarkText(_testCaseDocPath, "TC_02_Result", tc02);

        lblStatus.Text = "Статус: Результат сформирован и сохранён.";
    }
    catch (Exception ex)
    {
        lblStatus.Text = "Статус: Ошибка проверки/записи.";
        txtErrors.Text = ex.Message;
    }
}

2.10. Проверка результата (как понять, что всё работает)

Контрольные признаки правильной работы

После нажатия «Отправить результат теста» должно быть:

На форме:
lblStatus: «Результат сформирован…»
txtErrors: либо «Ошибок не обнаружено.», либо описание нарушений
В документе ТестКейс.docx:
в ячейке с закладкой TC_01_Result появилось Успешно/Не успешно
в ячейке с закладкой TC_02_Result появилось Успешно/Не успешно

3. Тестирование приложения

3.1. Ручное тестирование (по тест-кейсам)

Подготовьте 2 тестовых значения ФИО

Кейс для TC-01 (запрещённые символы):

Соколов& Сокол& Соколович → TC-01 должен быть Не успешно (есть &)

Кейс для TC-02 (структура):

Соколов Сокол Соколович → TC-02 должен быть Успешно (3 части)

Дополнительно (позитивный кейс):

Иванов Иван Иванович → оба должны быть Успешно

Выполните прогон

Запустите TransferSimulator.exe
Запустите WinForms-приложение
Нажмите «Получить данные»
Убедитесь, что в txtFio появилось значение из value (например: Соколов& Сокол& Соколович)
Нажмите «Отправить результат теста»
Откройте ТестКейс.docx и проверьте заполнение столбца «Результат»

3.2. Автоматизированное тестирование валидатора (Unit tests)

Это важно, чтобы убедиться, что логика проверки корректна независимо от формы, Word и эмулятора.

Создайте проект тестов

Solution → Add → New Project
Выберите: MSTest Test Project
Имя: ClientValidationApp.Tests
Добавьте ссылку на основной проект:
- Tests → Dependencies → Add Project Reference → ClientValidationApp

Напишите тесты для `FioValidator`

using ClientValidationApp.Validation;
using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace ClientValidationApp.Tests;

[TestClass]
public class FioValidatorTests
{
    [TestMethod]
    public void ForbiddenSymbols_ShouldFail_WhenHasAmpersand()
    {
        var (ok, _) = FioValidator.CheckForbiddenSymbols("Соколов& Сокол& Соколович");
        Assert.IsFalse(ok);
    }

    [TestMethod]
    public void ForbiddenSymbols_ShouldPass_WhenValid()
    {
        var (ok, _) = FioValidator.CheckForbiddenSymbols("Иванов Иван Иванович");
        Assert.IsTrue(ok);
    }

    [TestMethod]
    public void ThreeParts_ShouldFail_WhenTwoParts()
    {
        var (ok, _) = FioValidator.CheckThreeParts("Иванов Иван");
        Assert.IsFalse(ok);
    }

    [TestMethod]
    public void ThreeParts_ShouldPass_WhenThreeParts()
    {
        var (ok, _) = FioValidator.CheckThreeParts("Иванов Иван Иванович");
        Assert.IsTrue(ok);
    }
}

Запуск:

Test → Run All Tests Ожидаемо: все тесты зелёные.

3.3. Интеграционное тестирование (эмулятор + Word)

Прогон интеграции

Положите ТестКейс.docx рядом с exe приложения (в output-папке)
Запустите TransferSimulator.exe
Нажмите Получить данные → убедитесь, что данные пришли (GET fullName)
Нажмите Отправить результат теста
Проверьте:
- Word обновился по закладкам (TC_01_Result, TC_02_Result)
- ошибок на форме нет

4. Типовые проблемы и быстрые проверки

Закладка не находится
- проверьте имя: TC_01_Result без пробелов
- проверьте, что закладка вставлена именно в ячейку результата
Word не обновляется
- документ открыт в Word во время записи → закройте документ
- проверьте путь _testCaseDocPath (лучше хранить рядом с exe)
Не удаётся получить данные из симулятора
- симулятор не запущен
- неверный baseUrl (локально должен быть http://localhost:4444/TransferSimulator/)
- для резервного варианта проверьте доступность http://prb.sylas.ru/TransferSimulator/
- при ошибках сервера возможны ответы HttpStatusCode: 5xx (по условию)

Скачать пример приложения

Внимание! Не заработает без запущенного эмулятора и установленного JDK.

👉 Пример готового приложения