В нашата работа активно използваме платформа 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 езика. За поддържане на конкретен език е необходимо да се инсталира съответният плъгин. В общността версия включва плъгин за работа с Вашият DevOps пайплайн почти е готов за ползване. Добра работа! (включително typesсript), въпреки че в wiki е написано обратното. За Вашият DevOps пайплайн почти е готов за ползване. Добра работа! отговаря плъгинът SonarJS, за Typescript SonarTS съответно.

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

За Вашият DevOps пайплайн почти е готов за ползване. Добра работа! има 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 extension).

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за налични плъгини, като по този начин изчислява поддържаните ПЕ. Също така се изтеглят и други различни параметри за неговата работа: quality profiles, active rules, metrics repository, server rules.

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

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

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

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

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

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

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

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

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

sonar-project.properties:

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

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

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

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

sonar-project.properties:

...
sonar.language=ts
...

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

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

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

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

Ситуацията е следната: официална поддръжка на VueJs има в плъгина SonarJS, който отговаря за Вашият DevOps пайплайн почти е готов за ползване. Добра работа!.

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

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

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

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

sonar-project.properties:

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

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

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

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

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

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

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

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

За да създадем синтетична ситуация за дублиране на код, просто дублираме файла на компонента с различно име, също така добавяме в кода main.ts празна функция и я дублираме с различно име. За да проверим дублирането, както в -файлове, така и в .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: Всичко, което е описано в статията под формата на код, е достъпно в моя форк.

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