В нашата работа активно използваме платформата SonarQube за поддържане на качеството на кода на високо ниво. При интеграцията на един от проектите, написан на VueJs+Typescript, възникнаха проблеми. Затова бих искал да разкажа повече за това как успяхме да ги решим.

В тази статия ще говорим, както писах по-горе, за платформата SonarQube. Няколко теоретични неща — какво представлява това изобщо, за тези, които чуват за нея за първи път:

SonarQube (бивш Sonar) — платформа с отворен код за непрекъснат анализ (англ. continuous inspection) и измерване на качеството на кода.
Поддържа анализ на кода и откриване на грешки съгласно правилата на стандартите за програмиране MISRA C, MISRA C++, MITRE/CWE и CERT Secure Coding Standards. А също така разпознава грешки от списъците OWASP Топ-10 и CWE/SANS Топ-25 грешки в програмирането.
Въпреки че платформата използва различни готови инструменти, SonarQube обединява резултатите в единен информационен панел (англ. dashboard), водейки история на стартиранията и позволявайки по този начин да видим общата тенденция на изменение на качеството на софтуера по време на разработката.

По-подробно може да научите на официалния сайт

Поддържа множество езици за програмиране. Судя по информацията от горната връзка — това са над 25 езика. За поддръжка на конкретен език е необходимо да се инсталира съответният плъгин. В community версията е включен плъгин за работа с Javascript (включително typesсript), въпреки че в wiki е написано обратното. За Javascript отговаря плъгина SonarJS, за Typescript SonarTS съответно.

За изпращане на информация за покритие се използва официален клиент sonarqube-scanner, който, използвайки настройките от config-файла, изпраща тези данни на сървъра SonarQube за по-нататъшна консолидация и агрегация.

За Javascript има npm обвивка.И така, започваме стъпка по стъпка внедряване SonarQube в Vue-проект, използващ Typescript.

За разполагане на сървъра SonarQube ще използваме docker-compose.

sonar.yaml:

version: '1'
    services:
        simplesample-sonar:
            image: sonarqube:lts
            ports:
                - 9001:9000
                - 9092:9092
            network_mode: bridge

Стартиране:

docker-compose -f sonar.yml up

След това SonarQube ще бъде достъпен на адреса – http://localhost:9001 .

Все още няма проекти в него и това е вярно. Ще решим тази ситуация. Като основа съм взел официален проект-пример за VueJS+TS+Jest. Клонираме го при нас:

git clone https://github.com/vuejs/vue-test-utils-typescript-example.git

Първо, трябва да инсталираме клиента SonarQube, който се нарича sonar-scanner, за npm има обвивка:

yarn add sonarqube-scanner

И веднага ще добавим команда в scripts за работа с него.

package.json:

{
 … 
   scripts: {
      ...
      "sonar": "sonar-scanner"
      ...
   },
 …
}

Следващата стъпка е да зададете настройките на проекта в специален файл. Нека започнем с основните.

sonar-project.properties:

sonar.host.url=http://localhost:9001

sonar.projectKey=test-project-vuejs-ts
sonar.projectName=Тестово приложение (VueJS+TS)

sonar.sources=src
# sonar.tests=
sonar.test.inclusions=src/**/*tests*/**
sonar.sourceEncoding=UTF-8

sonar.host.url – адрес Sonar’а;
sonar.projectKey – уникален идентификатор на проекта на сървъра Sonar’а;
sonar.projectName – наименование, което може да се променя по всяко време, тъй като идентификацията на проекта става по projectKey;
sonar.sources – папка с изходни файлове, обикновено това е src, но може да бъде всякаква. Тази папка се задава относително на кореновата папка, от която се стартира скенерът;
sonar.tests – параметър, който е в двойка с предишния. Това е папката, в която се намират тестовете. В този проект няма такава папка, а тестовете се намират до тествания компонент в папка ‘test‘, затова засега ще я игнорираме и ще използваме следния параметър;
sonar.test.inclusions – път за тестовете с маска, може да има няколко елемента, изброени с запетая;
sonar.sourceEncoding – кодировка за изходните файлове.

За първото стартиране на скенера всичко е готово, освен основното предхождащо действие: стартиране на самия тестов двигател, за да се генерира информация за покритие, която впоследствие ще бъде използвана от скенера.

Но за това трябва да настроим тестовия двигател да генерира тази информация. В този проект тестовият двигател е Jest. Неговите настройки се намират в съответния раздел на файла package.json.

Да добавим тези настройки:

"collectCoverage": true,
"collectCoverageFrom": [
      "src/**/*",
      "!src/main.ts",
      "!src/App.vue",
      "!src/**/*.d.*",
      "!src/**/*__tests__*"
],

Тоест задаваме флага за необходимост от изчисляване на покритие и източника (включително изключенията), на базата на които то ще бъде генерирано.

Сега да стартираме теста:

yarn test

Ще видим следното:

Причината е, че в самия компонент на практика няма код. Нека го поправим.

HelloWorld.vue:

...
methods: {
    calc(n) {
      return n + 1;
    }
  },
mounted() {
  this.msg1 = this.msg + this.calc(1);
},
...

Това ще е достатъчно за изчисляване на покритие.

След повторното стартиране на теста, нека се уверим в това:

На екрана трябва да видим информация за покритие, а в папката на проекта ще бъде създадена папка покритие с информация за покритие от тестовете в универсален формат LCOV (разширение на LTP GCOV).

Gcov — безплатна утилита за изследване на покритието на кода. Gcov генерира точния брой изпълнения за всеки оператор в програмата и позволява добавянето на анотации към изходния код. Gcov идва като стандартна утилита в пакета GCC.
Lcov — графичен интерфейс за gcov. Той събира gcov файлове за няколко изходни файла и създава комплект HTML страници с кода и данни за покритието. Също така се генерират страници за улесняване на навигацията. Lcov поддържа покритие на редове, функции и разклонения.

След изпълнение на тестовете, информацията за покритието ще се намира в coverage/lcov.info.
Трябва да посочим Sonarоткъде да я вземем. Затова добавяме следните редове в неговия конфигурационен файл. Но има един момент: проектите могат да бъдат многоезични, тоест в папката src се намират изходни кодове за няколко езика за програмиране и принадлежността към съответния език, а оттам и използването на определен плъгин, се определя по разширението му. Информацията за покритието може да се съхранява на различни места за различни езици за програмиране, затова за всеки език има свой раздел за настройка. Нашият проект използва Typescript, затова ни е необходим раздел за настройки именно за него:

sonar-project.properties:

sonar.typescript.coveragePlugin=lcov
sonar.typescript.lcov.reportPaths=coverage/lcov.info

Всичко е готово за първото стартиране на скенера. Искам да отбележа, че проектът в Sonarсе създава автоматично при първото стартиране на скенера за съответния проект. При последващите стартирания информацията вече ще се акумулира, за да видим динамиката на промяната на параметрите на проекта през времето.

И така, нека използваме командата, създадена по-рано в package.json:

yarn run sonar

Забележка: може също да се използва параметър -X за по-подробно логиране.

Ако стартирането на скенера е за първи път, първо ще се изтегли бинарният файл на самия скенер. След това той се стартира и започва да сканира сървъра Sonarза установени плъгини, изчислявайки по този начин поддържаните езици за програмиране. Също така се зареждат различни параметри за неговата работа: качество профили, активни правила, метрики хранилище, правила на сървъра.

Забележка: няма да се спираме подробно на тях в рамките на тази статия, но винаги можете да се обърнете към официалните източници.

Следва анализ на папката src относно наличието на изходни файлове за всички (освен ако не е зададен конкретен) поддържани програмни езици, последвани от индексация.

Следват различни анализи, на които не се фокусираме в тази статия (например: линтинг, определяне на дублирания код и т.н.).

В края на работния процес на скенера се извършва агрегиране на цялата събрана информация, архивиране и изпращане на сървъра.

След това можем да видим какво е получено в уеб интерфейса:

Както виждаме, нещо е получено и дори показва някакво покритие, но то не отговаря на нашето Jest-отчет.

Нека разберем. Нека да разгледаме проекта по-подробно, да кликнем върху стойността на покритие и да "проваляме" в детайлен отчет по файлове:

Тук виждаме освен основния, изследван файл HelloWorld.vue, присъства и файл main.ts, който разваля цялостната картина на покритието. Но как така, ние го изключихме от изчислението на покритие. Да, всичко е правилно, но това беше на ниво Jest, но скенерът го е индексирал, затова той попада в неговите изчисления.

Нека го коригираме:

sonar-project.properties:

...
sonar.exclusions=src/main.ts
...

Искам да уточня: освен папките, които са зададени в този параметър, се добавят и всички папки, изброени в параметъра sonar.test.inclusions.

След стартиране на скенера виждаме вече коректна информация:

Нека разгледаме следния момент – Качествени профили. Споменах по-горе за поддръжката на Sonar” няколко програмни езика едновременно. Това точно наблюдаваме. Но знаем, че проектът ни е написан на TS, затова защо да натоварваме скенера с излишни манипулации и проверки. Езикът за анализ ще зададем чрез добавяне на още един параметър в конфигурационния файл Sonar’а:

sonar-project.properties:

...
sonar.language=ts
...

Отново стартираме скенера и виждаме резултата:

Покритието е напълно изчезнало.

Ако погледнем в логовете на скенера, можем да видим следния ред:

Тоест файловете на нашия проект просто не са били индексирани.

Ситуацията е следната: официалната поддръжка на VueJs съществува в плъгина, SonarJSкойто отговаря за Javascript.

Но тази поддръжка липсва в плъгина SonarTS за TS, за което е заведена официална тикет в баг-трекера. Sonar’а:

Ето някои отговори от един от представителите на разработчиците на SonarQube, потвърдили този факт.

Но нали всичко работеше, може да възразите. Да, така е, нека опитаме малко “да хакнем”.
Ако има поддръжка за .vue-файлове. Sonarтова, нека да опитаме да му кажем да ги разглежда като Typescript.

Добавяме параметър:

sonar-project.properties:

...
sonar.typescript.file.suffixes=.ts,.tsx,.vue
...

Стартираме скенера:

И, voila, всичко се върна на мястото си, само с един профил за Typescript. Тоест успяхме да разрешим проблема с поддръжката на VueJs+TS за SonarQube.

Нека опитаме да продължим напред и да подобрим информацията за покритие.

Какво направихме до момента:

добавихме в проекта Sonar-скенер;
настроихме Jest за генериране на информация за покритие;
конфигурирахме Sonar-скенер;
разрешихме проблема с поддръжката на .vue-файлове + Typescript.

Освен покритие с тестове, има и други интересни полезни критерии за качество на кода, например, дублиране на код и брой редове (участва в изчислението на коефициенти, свързани със сложността на кода) на проекта.

В текущата реализация на плагина за работа с TS (SonarTS) няма да работи CPD (Copy Paste Detector) и броене на редове код .vue-файлове.

За да създадем синтетична ситуация за дублиране на код, просто дублираме файла на компонента с друго име, също така добавяме в кода main.ts празна функция и я дублираме с друго име. За да проверим дублирането като в .vue, така и в .ts -файловете.

main.ts:

...
function name(params:string): void {
  console.log(params);
}
...

За това е необходимо временно да коментираме реда на конфигурацията:

sonar-project.properties:

...
sonar.exclusions=src/main.ts
...

Нека рестартираме скенера заедно с тестовете:

yarn test && yarn run sonar

Разбира се, покритието ще спадне, но в момента това не ни интересува.

В контекста на дублиране на редовете код ще видим:

За проверка ще използваме CPD-инструмента - jscpd:

npx jscpd src

За редовете код:

Възможно е, че това ще бъде решено в бъдещите версии на плъгините SonarJS(TS). Искам да отбележа, че постепенно започват да обединяват тези два плъгина в един SonarJS, което мисля, че е правилно.

Сега искам да разгледам вариант за подобряване на информацията за покритие.

Докато виждаме покритие с тестове в процентно отношение, за целия проект и по файлове в частност. Но има възможност да разширим този показател с информация за броя unit-тестове в проекта, а също и по файлове.

Има библиотека, която умее Jest-репорт да се конвертира във формат за Sonar’а:
generic test data — https://docs.sonarqube.org/display/SONAR/Generic+Test+Data.

Нека инсталираме тази библиотека в нашия проект:

yarn add jest-sonar-reporter

И да я добавим в конфигурацията Jest:

package.json:

…
"testResultsProcessor": "jest-sonar-reporter"
…

Сега да изпълним теста:

yarn test

След което в корена на проекта ще бъде създаден файл test-report.xml.

Нека го използваме в конфигурацията Sonar’а:

sonar-project.properties:

…
sonar.testExecutionReportPaths=test-report.xml
…

И да рестартираме скенера:

yarn run sonar

Да видим, какво се е променило в интерфейса Sonar’а:

И нищо не се е променило. Работата е там, че Sonar не разглежда файловете, описани в Jest-репорта, като unit-тестове. За да коригираме тази ситуация, ще използваме конфигурационен параметър Sonar sonar.tests, в който ясно ще посочим папките с тестовете (в момента имаме само една):

sonar-project.properties:

…
sonar.tests=src/components/__tests__
…

Да рестартираме скенера:

yarn run sonar

Да видим, какво се е променило в интерфейса:

Сега видяхме количеството на нашите unit-тестове и, като кликнем, можем да видим разпределението на това число по файловете на проекта:

Заключение

И така, разгледахме инструмента за непрекъснат анализ SonarQube. Успешно интегрирахме в него проект, написан на VueJs+TS. Решихме някои проблеми с съвместимостта. Повишихме информативността на показателя за покритие с тестове. В тази статия разгледахме само един от критериите за качество на кода (възможно е един от основните), но SonarQube поддържа и други критерии за качество, включително тестване за сигурност. Но не всички тези възможности са налични в community-версия. Една от интересните и полезни възможности е интеграцията SonarQube с различни системи за управление на кодовите репозитории, например, като GitLab и BitBucket. За да предотвратим merge pull(merge) request'а в основната клон на репозитория при деградация на покритието. Но това е история за съвсем друга статия.

PS: Всичко, което е описано в статията под формата на код, е достъпно в моят fork.

Само регистрирани потребители могат да участват в анкетата. Влезте, моля.