Użycie TeamCity w projektach PHP cz.1

Witam. Tym postem chciałbym rozpocząć serię poradników, w której pokażę, w jaki sposób skonfigurować serwer integracji TeamCity pod kątem projektów pisanych w PHP. Serwer ten nie jest zbyt często wykorzystywany do integracji takich projektów – z tego powodu bardzo ciężko znaleźć opisy jak integrować poszczególne, najczęściej używane narzędzia. Powodem jest chyba brak „bezpośredniej” integracji z PHPUnit, Selenium itp. Jednak wszystkie te narzędzia używają standardowych plików raportów więc po odpowiedniej konfiguracji wszystko działa bardzo dobrze.

Poradnik ten rozbiję na następujące części i będę publikował je w krótkich odstępach czasu:

1. Podstawowa konfiguracja – wprowadzenie do TeamCity
2. Integracja z PHPUnit – testy jednostkowe
3. Integracja z PhpDocumentor DocBlox – generowanie dokumentacji projektu
4. Integracja z PHP Copy&Paste detector – wykrywanie dublowania kodu
5. Integracja z PHP Mess Detector – analiza kodu pod względem potencjalnych problemów wydajnościowych oraz błędów
6. Integracja z PHP Depend – analiza kodu pod względem jego złożoności
7. Integracja z PHP Code Sniffer – narzędziem do weryfikacji poprawności/zachowania standardów kodowania
8. Integracja z phploc – narzędziem do liczenia linii kodu
9. Integracja z PHP Dead Code Detector – narzędzie do wykrywania nie używanego kodu
10. Integracja z Selenium-RC
11. Integracja z testami jednostkowymi dla JavaScript

Ten poradnik oparty  jest w dużej mierze o post Continuous Integration and TeamCity (Непрерывная интеграция и TeamCity) oraz wątek na forum Integrate code coverage report (clover format, PHPUnit)

Lista jest obszerna, ale niektóre sekcje będą bardzo proste i nie powinny zająć więcej niż kilka minut.

Więc pora zaczynać 🙂

Instalacja

Instalacja serwera może być dokonana na dwa sposoby: albo jako samodzielny serwer lub jako aplikacja uruchamiana na istniejącej instancji serwera Tomcat. Ja zastosuje ten pierwszy sposób, ponieważ nie używam Tomcata do żadnych projektów. Drugi sposób instalacji opisany jest szczegółowo w bardzo dobrej dokumentacji.

Po wejściu do sekcji Download na stronie producenta trzeba wybrać system operacyjny i pobrać najnowszą wersję.

Darmowa edycja pozwala na zachowanie do 20 konfiguracji, ma limit użytkowników również 20 oraz nie ma możliwości autentykacji użytkowników przez zewnętrzne systemy (np LDAP, ActiveDirectory). Pozwala również na instalację tylko 3 agentów – ale jest to limit również wersji płatnej – każdy dodatkowy agent do umiarkowany wydatek 200+ dolarów, ale na początek wystarczą w zupełności 3.

Po pobraniu paczki na dysk wystarczy wydać polecenie:

tar xfz TeamCity-6.0.2.tar.gz

I zostanie utworzony katalog zawierający serwer. Po przejściu do podkatalogu bin wystarczy uruchomić polecenie:

./runAll.sh start

Uruchomiony zostanie serwer oraz jeden agent. Całość administracji odbywa się poprzez bardzo wygodny interfejs www dostępny pod adresem http://adres_serwera:8111/.

Po zaakceptowaniu licencji, serwer poprosi o utworzenie użytkownika, który będzie administratorem serwera.

Konfiguracja projektu

Pora utworzyć pierwszy projekt.

Może teraz słowo o celu przygotowywania konfiguracji budujących. Można je dzielić na różne sposoby i różnie nazywać, ale wydaje mi się, że najważniejsze są dwa oczekiwane rezultaty stosowania automatyzacji.

1. Nowa wersja
   Taka konfiguracja ma na celu wydanie nowej wersji – na produkcję, do testów, do demo itp itd. Interesuje nas pobranie najnowszej wersji do określonego katalogu na określonym serwerze – tak by można było otworzyć projekt w przeglądarce.
2. Testy
   Taka konfiguracja zawiera automatyczne testy, wykonuje się długo, ale jej celem nie zawsze jest wydanie wersji, w którą można kliknąć – nie jest wymagany określony serwer lub określona lokalizacja.

Obie konfiguracje mogą się opierać o ten sam plik – różnić się tylko zakresem – drugi przypadek zawiera też wywołanie pobrania nowej wersji. Jako narzędzie nadzorujące wybrałem program ant. Jest on dobrze znany, z dosyć dobrą dokumentacją oraz świetnie się integruje z TeamCity.

Przed dodaniem konfiguracji konkretnego projektu należy dodać repozytorium kodu. Wystarczy kliknąć zakładkę „VCS Roots”, a następnie na odnośnik „Create New VCS Root”. Po nadaniu nazwy, wybraniu typu repozytorium warto zaznaczyć wsparcie dla zewnętrznych repozytoriów oraz współdzielenie nowej konfiguracji z kolejnymi projektami.

Po dodaniu repozytorium i powrocie na pierwszą zakładkę możemy rozpocząć dodawanie konfiguracji. Na tej stronie podajemy standardowe informacje, które nie wymagają wyjaśnienia – poza dwoma, które teraz opiszę: „Artifacts path” (1) oraz „Status widget” (2).

Pierwsza pozwala na automatyczne importowanie różnego rodzaju raportów, które będą generowane przez testy i inne narzędzia. Można tu na przykład ustawić katalog, do którego PHP Documentator będzie przygotowywał dokumentację. Swoje konfiguracje przygotowuję tak, by wyniki wszystkich narzędzi zapisywane były do osobnych podkatalogów i w tym miejscu podaje ścieżkę do głównego katalogu. Pozwala to, na przeglądanie wszystkiego ,co jest generowane. Druga opcja pozwala na pobranie statusu ostatniego statusu konfiguracji poprzez JavaScript lub obrazek o określonym kolorze – pozwala to na wpisanie do stopki na serwerze testowym stanu ostatnich testów. Więcej szczegółów oraz przykłady kodu znajdują się w dokumentacji.

Po kliknięciu „VCS Settings >>>” na dole strony zostaniemy poproszeniu o wybranie repozytorium kodu.

Na tym ekranie najważniejsze są dwie zaznaczone na czerwono opcje. W tym miejscu następuje pierwsza różnica w konfiguracji. Jeżeli chcemy przygotować wersję dostępną do klikania, to w pierwszej opcji wybieramy „Do not checkout files automatically” – spowoduje to że agent budujący nie będzie pobierał przed uruchomieniem (lub po wykryciu zmian na dysku – np konfiguracja) nowej wersji kodu oraz nie pobierze jej za pierwszym razem, należ przygotować katalog samodzielnie. W tym przypadku należy też określić katalog, do którego będzie pobierany kod – zapewne widoczny przez serwer www.

Jeżeli chcemy tylko testować kod (automatycznie – przez testy jednostkowe – Selenium jest specjalnym przypadkiem, o którym za moment) nie interesuje nas miejsce pobrania kodu – będzie on uruchamiany z linii poleceń, a wyniki będą importowane na serwer. Pozwala to na dodanie agentów budujących na kilku serwerach (wystarczy zadbać o instalację wszystkich narzędzi) co umożliwi budowanie i testowanie większej ilości konfiguracji w tym samym czasie. Automatyczne pobieranie na serwer powoduje pobranie wersji, spakowanie jej i wysłanie na agenta. Możliwe jest też pobranie bezpośrednio na agencie – w tym przypadku potrzebny jest klient kontroli wersji na maszynach z agentem.

Selenium jest szczególnym przypadkiem – pobieranie następuje do określonego katalogu zawsze na jednej maszynie. W tym przypadku wybieram automatyczne pobieranie na agencie oraz określony katalog. Ograniczenie do wybranego agenta realizuję poprzez wymaganie narzucone na konfigurację – wymagam, by agent posiadał właściwość: „Selenium”. W ten sposób nie muszę przygotowywać konfiguracji i katalogu – agent sam się tym zajmie no i mogę przygotować więcej niż jednego agenta do testowania funkcjonalności www.

Na dole strony wystarczy kliknąć „Add Build Step >>>” by przejść do dodawania kroków budowania.

Od wersji 6.0 TeamCity umożliwia dodanie kilku różnych kroków. Pozwala to na przygotowanie jednego pliku build.xml z różnymi celami i wybieranie ich w zależności od potrzeb. Podstawowa wersja zawiera jeden krok typu Ant z celem: „checkout”.

<?xml version="1.0" encoding="UTF-8"?>
<project name="Application" default="checkout">

    <property name="artifactsDir" value="${basedir}/tests/artifacts/" description="Base dir for all output of build commands"/>

    <target name="checkout" description="Base task - update directory with new version from server and overwrite all conflicts with files from server">
        <exec executable="svn" failonerror="true" output="${artifactsDir}/svn.log">

            <arg value="up"/>
            <arg value="--force"/>
            <arg value="--accept theirs-full"/>
        </exec>

    </target>

</project>

Przedstawiony powyżej plik wystarczy zapisać pod nazwą build.xml w głównym katalogu projektu.

I to właściwie tyle. System powinien potrafić już pobrać kod do odpowiedniego katalogu i zaświecić statusem na zielono 🙂

Teraz w konfiguracji budującej projektu, na zakładce „Settings” wystarczy dodać „Build Trigger”, ustawić co godzinę lub codziennie o 12  i system będzie automatycznie uaktualniał wersje.

W następnym poście integracja z testami jednostkowymi.

1 lutego 2011 10:50 Grzegorz Drozd Brak komentarzy Komentuj Kategorie: Narz?dzia, PHP, Praca, TeamCity