Покрытие кода и метрики качества

Stimulus — это легковесный JavaScript-фреймворк для улучшения взаимодействия с DOM без необходимости масштабного SPA. Он ориентирован на поведение элементов через контроллеры, а не на полное управление состоянием приложения. Контроллеры привязываются к DOM через атрибуты data-controller, а их методы — к событиям с помощью data-action.

Контроллер представляет собой класс с обязательными методами connect() и disconnect(). Метод connect() вызывается при инициализации элемента, метод disconnect() — при его удалении из DOM. Для управления внутренними элементами можно использовать targets — элементы, отмеченные атрибутами data-[controller]-target, которые автоматически связываются с полем контроллера.

export default class extends Stimulus.Controller {
  static targets = ["input", "output"]

  connect() {
    console.log("Контроллер подключен")
  }

  update() {
    this.outputTarget.textContent = this.inputTarget.value
  }
}

Связывание событий и действий

Ключевое преимущество Stimulus — декларативное связывание событий через data-action. Формат записи: event->controller#method. Это позволяет поддерживать чистоту кода, минимизируя использование addEventListener.

<input data-action="input->example#update" data-example-target="input">
<span data-example-target="output"></span>

Такая схема снижает вероятность утечек памяти, так как Stimulus сам управляет подписками при подключении и отключении контроллера.

Работа с targets и values

Targets упрощают доступ к внутренним элементам контроллера. При большом числе элементов они позволяют избежать повторного поиска через querySelector.

Values дают возможность хранить и автоматически обновлять данные. Они объявляются через static values и доступны как свойства контроллера.

static values = { count: Number }

increment() {
  this.countValue++
}

Изменения значений можно отслеживать через методы valueChanged, что полезно для реактивного поведения.

Организация структуры приложения

Stimulus поощряет разделение ответственности на контроллеры с узкой специализацией. Каждый контроллер должен управлять лишь своим набором элементов, что облегчает тестирование и покрытие кода.

Рекомендуется:

  • Использовать отдельные файлы контроллеров для каждого модуля.
  • Минимизировать прямое взаимодействие между контроллерами. Связь осуществляется через события DOM (dispatch/CustomEvent) или глобальный объект для приложения.
  • Следовать единому стилю именования targets и actions, чтобы код был предсказуемым и читаемым.

Покрытие кода

Для измерения качества кода Stimulus-контроллеров применяются стандартные инструменты Jav * aScript:

  • Jest — тестирование логики контроллеров.
  • @testing-library/dom — проверка взаимодействия с DOM.
  • c8 или Istanbul — генерация метрик покрытия.

Примеры покрытия:

  1. Проверка метода connect:
test("connect sets up initial state", () => {
  document.body.innerHTML = `<div data-controller="example"><span data-example-target="output"></span></div>`
  const application = Stimulus.Application.start()
  application.register("example", ExampleController)
  
  const output = document.querySelector('[data-example-target="output"]')
  expect(output.textContent).toBe("")
})
  1. Проверка событий:
test("update method updates outputTarget", () => {
  document.body.innerHTML = `
    <input data-action="input->example#update" data-example-target="input" value="test">
    <span data-example-target="output"></span>
  `
  const controller = new ExampleController(document.querySelector('[data-controller="example"]'))
  controller.connect()
  controller.update()
  expect(controller.outputTarget.textContent).toBe("test")
})

Метрики качества

Покрытие кода измеряется через процент выполненных строк, функций и ветвлений. Для контроллеров Stimulus важно учитывать:

  • Методы connect/disconnect — обязательны к тестированию, так как управляют жизненным циклом элемента.
  • Обработчики событий — проверка реакций на user actions.
  • Values и targets — должны корректно инициализироваться и изменяться.

Помимо покрытия, следует оценивать структурную и логическую чистоту кода:

  • Нет дублирования поиска DOM-элементов.
  • Каждый контроллер имеет узкую специализацию.
  • Методы имеют одну ответственность и предсказуемое поведение.

Автоматизация тестирования

Stimulus интегрируется с CI/CD через стандартные pipeline. Используются:

  • Автоматическое покрытие с отчетами.
  • Проверка DOM-рендеринга и событий.
  • Валидация корректности targets и actions через статический анализ.

Для поддержания высокого качества кода рекомендуется включать постоянное измерение покрытия и интеграцию с линтерами, которые проверяют корректность синтаксиса data-* атрибутов.

Расширенные возможности

  • Dynamic targets: добавление элементов в DOM после инициализации контроллера автоматически связывает их как targets.
  • Custom events: контроллеры могут отправлять события для уведомления других частей приложения, сохраняя слабую связность.
  • Values observers: позволяют реагировать на изменение данных без ручного вызова методов.

Stimulus сочетает легковесность с мощными инструментами тестирования и покрытием, делая код предсказуемым и управляемым даже в сложных интерфейсах.

Оглавление