przemuh.dev [EN]

Short story about optimisation

Sun, 08 Nov 2020 00:00:00 GMT

This article has not been translated yet. Here is a Polish version. Stay tuned

Jakiś czas temu na Twitterze zamieściłem zrzut ekranu pokazujący flame-chart z narzędzia Profiler. Pracowałem wtedy nad poprawą wydajności aplikacji, którą rozwijamy w Egnyte. Pewna funkcjonalność, dla dużej ilości danych, zajmowała strasznie dużo czasu - 3,5 minuty! Przez ten czas w aplikacji pokazywany był "kręciołek", a użytkownik nie wiedział, czy coś się dzieje, czy może coś się zawiesiło. Po kilku dniach pracy z Profilerem udało mi się zaimplementować poprawki, które zredukowały czas potrzebny do obliczeń z 3,5 minuty do 35 sekund. W tym wpisie chciałbym opisać jak do tego doszedłem.

Opis funkcjonalności

Zacznijmy od opisu funkcjonalności, która krótko mówiąc kulała pod względem wydajności. Jednym z głównych widoków w naszej apce jest tzw. "Sensitive Content". Pokazujemy tu listę folderów z plikami, które zawierają wrażliwe dane. To mogą być numery kart kredytowych, dane medyczne, personalne i nie tylko. Dane te mogą podchodzić pod jedną z kilkunastu wbudowanych polityk np. HIPA, GDPR, ale również dajemy możliwość użytkownikom zdefiniowana własnej polityki np. w oparciu o utworzony wcześniej słownik. Początkowo widok "Sensitive Content" pokazywał tylko płaską listę folderów. W zeszłym roku nasz Product Owner wraz z zespołem UX doszli do wniosku, że praca z płaską listą folderów może być nieefektywna. Zamiast tego dużo lepszym, i w zasadzie bardziej naturalnym sposobem reprezentacji danych, będzie drzewko folderów.

Widok Sensitive Content List

Algorytm budowania drzewa

Podejść do drzewek było już u nas w projekcie kilka. Głównie opierały się one na własności folderu jakim było unikalne folderId. Niestety, w przypadku "Sensitive Content" nie mogliśmy tego użyć, ponieważ nie wszystkie foldery mogły zawierać wrażliwe dane, a tylko dla takich folderów dostawaliśmy folderId.

/Shared/A/B/

W tym wypadku mamy 3 foldery (Shared, A, B), z czego tylko dla B dostajemy folderId

Takich lokacji z SC (Sensitive Content) może być multum. Problem wydajności pojawiał się już przy 250 tysiącach lokacji. A że nie jest to wyjątek utwierdził nas klient, u którego znaleźliśmy prawie milion folderów. To właśnie dla 1M elementów listy, czas budowania drzewka wynosił 3,5 minuty. Dlatego też, moje zadanie polegało na tym, że drzewko dla 1M elementów ma się budować w mniej niż 60s.

Wracając do algorytmu. Prosty - jak budowa cepa - tak by się wydawało :)

Weź całą ścieżkę i podziel ją na fragmenty wg. separatora np. /
Każdy folder wsadź do dwóch struktur: "drzewiastej" i "płaskiej"
Jeśli folder nie ma folderId traktuj go jako meta-folder

Dla uproszczenia pomijam kwestię tego, że wspieramy różne źródła danych i te separatory mogą się mocno różnić :) Co więcej, jak się później okazało, niektóre źródła danych mogą mieć dwa foldery o tej samej nazwie, na tym samym poziomie zagnieżdżenia 😱. I jak je rozróżnić? Pominę też kwestię tego, że wynikowe drzewo mieliśmy przedstawić w formie "sparse-tree". W skrócie - chodzi o to, że jeśli folder zawiera tylko jeden sub-folder, to ścieżka rodzica powinna być zwinięta/scalona.

Lista:

/Shared/A/B/C
/Shared/A/B/D

-->
Drzewo:

/Shared/A/B
    /C
    /D

Pierwsza, a w zasadzie druga implementacja

Jak już wspomniałem wcześniej, nie było to pierwsze drzewo, jakie mieliśmy wyświetlić w aplikacji. W zupełnie innym widoku, też mieliśmy zrobić sparse-tree i nie chcieliśmy mieć kilku różnych implementacji. Dlatego napisaliśmy prosty moduł do budowania i zarządzania drzewkiem. Oparty został o dwa małe komponenty:

funkcję buildTree, która przyjmowała płaską tablicę węzłów i miejsce (ścieżkę w drzewie) od którego miała te węzły wstawiać
"plasterek" (slice) z redux-toolkit, który zarządzał strukturą drzewa (rozwijanie, zwijanie węzłów itp.)

Całe drzewo, a w zasadzie te dwie struktury "drzewiasta" i "płaska", trzymane były w reduxie w następujący sposób:

{
    tree: {
        path: "", // root
        children: {
            "Shared": { // path-part or folder name as a key
                path: "/Shared",
                children: {
                    "A": {
                        path: "/Shared/A",
                        children: {}
                    }
                }
            }
        }
    },

    paths: {
        "/Shared": {
            meta: true,
            ...nodeProps
        }
        "/Shared/A": {
            meta: false,
            folderId: "some-unique-id",
            ...nodeProps
        }
    }
}

Taką strukturę otrzymujemy z pomocniczej funkcji buildTree.

Dzięki zastosowaniu redux-toolkit, a co za tym idzie biblioteki immer, mogliśmy w bardzo prosty sposób wykonywać operacje na drzewie:

const initialTreeState = {
  initialized: false,
  tree: {
    path: "",
    children: {},
  },
  paths: {},
}

export const createTreeSlice = treeName =>
  createSlice({
    name: treeName,
    initialState: initialTreeState,
    reducers: {
      insertTree: ({ tree, paths }, { payload }) => {
        paths = {
          ...paths,
          ...payload.paths,
        }
        const node = getNodeByPath(payload.parentPath || "", tree)
        node.children = payload.tree.children
      },

      toggleNode: ({ tree }, { payload: path }) => {
        const node = getNodeByPath(path, tree)
        node.expanded = !node.expanded
      },
    },
  })

Pomocnicza funkcja getNodeByPath służy do wyszukiwania węzła po ścieżce. Potrafi też wyszukać węzeł w sparse-tree.

Pierwsze podejścia do optymalizacji i pierwsze błędy

No i wszystko pięknie-ładnie, ale przyszedł klient, 1 milion folderów i jebs... Product Owner zakłada Epic w Jirze pt. "Support 1M folders on SC tree view". Szybka burza mózgów i od razu kosz pełen pomysłów:

a może by tak budować drzewo w locie, jak parsujemy JSONa?
a może by tak budować drzewo w web-workerze, przynajmniej nie zablokujemy głównego wątku na 3,5 minuty?
a może by tak, pizgnąć to wszystko i wyjechać w Bieszczady? ⛰ 🐑

Pierwszy błąd - nikt nawet nie odpalił Profilera, żeby zobaczyć co zajmuje tyle czasu. Każdy założył, że obecna implementacja drzewka wymiata i lepiej być nie może. Sam Profiler na pierwszy rzut oka nie jest prostym narzędziem i może to było powodem tego, że rzuciliśmy się wtedy na tego typu pomysły jak budowanie drzewa "w locie" czy przeniesienie tego do web-workera. Warto też podkreślić, że sam Epic w Jirze powstał już jakiś czas temu, a do samej implementacji usiadłem w połowie października.

Pewnie zastanawiacie się - ale jak to w locie? Przecież jak idzie request to dopiero jak przyjdzie odpowiedź to przeglądarka parsuje JSONa i daje odpowiedź. Tak, ale...w tym przypadku nasi backendowcy też musieli podziałać trochę w kwestii optymalizacji i zamiast zwracać pełne dane to zaczęli tę naszą listę SC zwracać na zasadzie stream'u. Dzięki temu mogliśmy np. wykorzystać bibliotekę oboe.js to parsowania JSONa w locie.

Oczywiście spróbowałem tego podejścia, no bo w końcu ktoś to wpisał do zadania w Jirze, trzeba było sprawdzić co nie? 😜 Fajnie, JSON parsował się "w locie", ale stream zamiast 10s trwał 30s, a jeszcze nie zacząłem nawet budować drzewa. Dlatego odpuściłem i postanowiłem poszukać gdzie indziej.

Web-worker

Podejście z web-workerem też przetestowałem. Ale tu napotkałem zupełnie inny problem. Ok - mogę sobie pobrać 1M elementów i zbudować na tej podstawie drzewo, ale muszę je później przesłać z wątku web-workera do wątku głównego. Struktura drzewa jest dość obszerna, razem z danymi, które zapisywaliśmy w tej płaskiej strukturze paths. Jeśli chcemy przesłać tak duże dane z jednego wątku do drugiego, przeglądarka musi te dane zserializować, przesłać, a następnie ponownie sparsować. To też powodowało "zamrożenie" przeglądarki na czas przesyłania z jednego miejsca pamięci do drugiego. Oczywiście są sposoby na przesłanie "bezpośrednie" (bez kopiowania) poprzez tzw. Transferable Objects np. ArrayBuffer, ale uznałem, że na chwilę obecną to może być gra nie warta świeczki i postanowiłem sprawdzić, czy faktycznie ta nasza implementacja drzewka była tak zajebista jak myśleliśmy 😜

Profiler podejście pierwsze

Usiadłem przed ekranem komputera, odpaliłem dev-toolsy i wcisnąłem przycisk "record" w Profilerze. Po chwili dostałem taki kolorowy wykresik, który przypomniał mi czasy defregmentatora dysków z Windowsa 98 🤣

Flame graph

Pierwsze co rzuciło mi się w oczy to ten fioletowy kolor, który zanurkował bardzo, bardzo głęboko. Po bliższym spojrzeniu okazało się, że bardzo dużo tych fioletowych elementów to sprawka immer.js. Szybki rzut oka w dokumentację i boom! strzał w dziesiątkę. Okazuje się, że przy "wkładaniu" dużej ilości danych poprzez immer możemy przyspieszyć ten proces poprzez Object.freeze tutaj więcej info. Zabieg ten pozwolił mi na zejście z 12,54s na 11,24s dla 54K elementów. Dla 1M skok był oczywiście proporcjonalnie większy. No ale to nadal nie było to...

Od profilera, do źródeł

Wiedzieliście, że jak klikniecie na dany blok w Profilerze, a następnie przeniesiecie się do pliku, to dostaniecie czasy dla poszczególnych bloków kodu? Nie!? 😎 To teraz już wiecie ;)

Czasy przed optymalizacją dla buildTree

To co się rzuca w oczy to 229ms dla zbudowania prostego ciągu znaków 🤯 jakim jest aktualna ścieżka. Okazało się, że to zwykłe niedopatrzenie można było zastąpić krótszym kawałkiem kodu, który koniec końców zajmuje 1.7ms.

Czasy po optymalizacji dla buildTree

Pomyślicie - (ironicznie) wow... 227ms... "brawo Ty" 👏. Czym jest 227ms? Jeśli spojrzymy na to jako pojedynczą wartość - to fakt...mikro-optymalizacja. Ale pamiętajcie, że celem było obsłużenie 1M elementów, a operacja sklejania ścieżki dotyczyła każdego sub-folderu.

Mój spread operator AKA Object.assign taki piękny

Jak zrobić płytką kopię obiektu, bądź rozszerzyć inny obiekt - nic prostszego - spread operator .... Jeśli musicie wspierać przeglądarki takie jak IE11, to pewnie korzystacie z babel.js - tak jak my...no i taki spread operator, koniec końców jest tłumaczony na Object.assign (w wielkim uproszczeniu).

Object.assign jest stosunkowo wolny i przy większej skali może sprawiać problem. W tym przypadku postawiłem na zwykłe kopiowanie per klucz. Dzięki temu prostemu zabiegowi zbiłem 154ms do 44ms. I znowu, dla pojedynczych elementów to nie ma absolutnie żadnego znaczenia, ale kiedy iterujemy po dużym zbiorze danych takie optymalizacje mogą zdziałać cuda.

Dan Abramov o Object.assign

Agregacja wartości

Po "podkręceniu" immera i wyrzuceniu kliku Object.assign, bądź przepisaniu ich na prostą pętlę, skończyły mi się pomysły na "proste" optymalizacje. Trzeba było podkręcić sam sposób budowania drzewa.

Poprzednia implementacja, dzieliła sobie SC lokacje wg. źródła i dla każdego z nich budowała pod-drzewo. Dla każdego pod-drzewa liczone były zagregowane wartości (np. jeśli folder sam w sobie zawierał 10 SC, ale miał dodatkowo 50 sub-folderów, chcieliśmy pokazać zsumowane wartości). Dla każdego takiego pod-drzewa, wykonywane były sumowania, a następnie węzeł źródła był aktualizowany wg. zsumowanych wartości dla wszystkich folderów.

Każda taka operacja wrzucała coś do stanu w redux'ie. Pomyślałem - a na co to komu? A komu to potrzebne? Przecież nie pokazujemy drzewa dopóki wszystko nie jest policzone i zaktualizowane. Dlatego, zmieniłem kod tak, aby najpierw zbudować w pamięci całe drzewo wraz z policzonymi zagregowanymi wartościami, a następnie za pomocą jednej operacji, wsadzić zbudowane drzewo do reduxa.

Co więcej - w wymaganiach drzewka, było napisane, że pewne węzły miały być domyślnie rozwinięte np. pierwszy poziom + potencjalnie wcześniej zaznaczony element na liście (z listy do drzewka można przejść za pomocą prostego przycisku). Wcześniej operacje rozwijania były wyzwalane za pomocą akcji toggleNode. To też zmieniłem - zamiast odpalać reduxową akcję, po prostu zmieniam wartość expanded na true bezpośrednio w obiekcie węzła.

Można zapytać - co Ci to dało drogi Panie?

Dla 54K elementów zjechałem z czasu 12,25s na 2,4s 🚀

Łogień w szopie :) Product Owner cały w skowronkach.

Testy dla 1M

Poprosiłem backendowców, żeby przygotowali mi środowisko do testów dla 1M elementów. Chciałem sprawdzić czy moje optymalizacje dla 54K znajdą uzasadnienie. No i uśmiech nie uciekł z mej twarzy :)

Przed optymalizacją czas budowania drzewa wynosił ~3,5 minuty. Po zaaplikowaniu wyżej wymienionych zmian udało się zjechać do 59s.

Mniej więcej ~70% oszczędności. W sumie można by powiedzieć - job done - miało się budować w mniej niż 60s... 59 to mniej niż 60 😅 Jest git...

Trochę byłem już zmęczony tym grzebaniem w de-facto w nie swoim kodzie...ale kumpel z zespołu słusznie stwierdził:

No fajnie, fajnie, ale dla mnie nadal to jest wolno.

Dodał też potem, że nic mi nie ujmuje i wg. niego wykonałem kawał dobrej roboty...ale trudno było się z nim nie zgodzić. Od momentu kliknięcia w element nawigacji, do czasu wyświetlenia widoku, użytkownik musiał poczekać łącznie 90s:

25s pobieranie danych (streaming)
6s przeglądarka parsuje JSONa
59s budowanie drzewa

Jako użytkownik, gdybym przez 90s widział tylko spinner ("kręciołek") to by mnie szlag trafił :) Nie chcę myśleć, co czuli nasi użytkownicy jak musieli czekać 3,5 minuty...pewnie żaden nie wytrzymał 😅

...no...ale wracając...kumpel mówi: "wolno"...no to ja od razu: "co!? wolno!? ja Ci pokażę!" 🤣

Generowanie ID

Znowu zanurkowałem w Profiler. Dla meta-folderów generowny był folderId. Było to spowodowane tym, że inne miejsce w kodzie tego id potrzebowało (mniejsza o to). Koniec końców to generowane id nic nie znaczyło (nigdy nie było wysyłane do backendu). Ktoś jednak wymyślił, że to meta-folder-id ma być haszem ze ścieżki...

export const createUniqueIdForLocation = path => btoa(encodeURIComponent(path))

Funkcja btoa koduje ciąg znaków jako base64. Sama w sobie trwa średnio 0,25ms...czyli ułamek milisekund. Ale gdy mocniej się zastanowimy - a na co komu ten hasz? a na co komu to potrzebne?

No właśnie! Jeśli meta-folder-id to tylko base64 ze ścieżki, która de facto zawierała też w sobie id źródła, więc była unikatowa względem całej listy, to po co to w ogóle ten cały hash?

-            id: createUniqueIdForLocation(path),
+            id: path,
             name: getLocationName(path),

Ten jeden diff sprawił, że dla 1M elementów zszedłem z 59s na 35s, co dało ~40% zysku 🤯

Czyli teraz klient nie czekał już 90s a 66s - łącznie z pobieraniem i parsowaniem danych! Biorąc pod uwagę, że wymagania mówiły o budowaniu drzewka w czasie mniejszym niż 60s, to chyba Product Owner oraz klienci powinni być zadowoleni 😅

Dalsze kroki

Oczywiście nie spoczywamy na laurach. Blokowanie użytkownika na 60s nadal jest kiepskim pomysłem, dlatego dalej myślimy o ulepszeniu implementacji. Być może wyrzucimy to w końcu do web-workera. Kto wie? Może uda mi się dzięki temu zebrać materiał na następnego posta 😉.

Podsumowanie

Lekcja pierwsza - zamiast gdybać i sypać pomysłami z kapelusza o web-workerach, lepiej odpalić Profiler.

Lekcja druga - jeśli operujesz w dużej skali, iterujesz po dużym zbiorze danych, to optymalizacje na poziomie ms dla jednej iteracji potrafią czynić cuda 🚀

Lekcja trzecia - do reduxa wrzucaj dopiero wtedy, kiedy jesteś gotów 💪

Lekcja czwarta - jeśli nie ma potrzeby, to nie komplikuj sytuacji 😉 (patrz ID & btoa).

Mam nadzieję, że dzięki tej historii sięgniecie wcześniej do Profilera i uda się Wam poprawić wydajność nie jednej aplikacji.

10 golden advices for junior developer

Tue, 22 Sep 2020 00:00:00 GMT

This article has not been translated yet. Here is a Polish version. Stay tuned

Czy ten tytuł to clickbait? Oczywiście, że tak. Nie ma na świecie dwóch takich samych osób. To co sprawdziło się u mnie niekoniecznie musi się sprawdzić u Ciebie. Tak prawdę mówiąc, to tytuł tego posta powinien brzmieć "Co chciałbym przekazać sobie, gdybym dzisiaj miał zaczynać jako junior developer". Ale uznałem, że to trochę zbyt długie. Kto wie, może niektóre z poniższych wskazówek przydadzą się Tobie. Czy niektóre z tych rad są kontrowesyjne? Pewnie tak. Ale wszystkie z nich są szczere, i właśnie takie chciałbym usłyszeć gdybym wchodził jeszcze raz w świat IT. Traktruj ten wpis, raczej jako taki list Przemka do Przemka :)

TL;RD

nie buduj portfolio
załóż konto na Twitterze
uważaj na celebrytów-IT
nie kupuj książek
eksperymentuj, baw się kodem
naucz się świadomie zarządzać czasem
zainwestuj w umiejętności miękkie
znajdź mentora
kup notatnik
doszlifuj anglielski

Nie buduj portfolio

Kiedy zaczynałem szukać swojej pierwszej pracy jako programista (2012 r.) nie wiedziałem, że wyląduję na frontendzie. Nie miałem konta na githubie. Nie miałem portfolio. I gdybym dzisiaj miał szukać pracy, to też bym takiego portfolio nie budował. A już na pewno nie wrzucałbym tam aplikacji typu ToDo List, albo Weather App. Nie zrozum mnie źle, pisanie takich aplikacji jest jak najbardziej ok. Dzięki temu uczysz się jak składać działającą całość. Ale wrzucanie tego do portfolio jak dla mnie nie ma sensu.

No dobra...ale co zamiast portfolio?

Odpowiedź jest prosta - Open Source. Na githubie jest mnóstwo bibliotek, do których możesz kontrybuować. Wybierz sobie swoją, przeczytaj dokumentację, spróbuj zbudować lokalnie, zobacz jak wygląda lista Issues - z czym ludzie mają problemy. Dzięki temu nauczysz się o wiele więcej niż przy ToDo czy Weather App. Czytanie cudzego kodu to jedna z najważniejszych umiejętności w byciu programistą. Mówiąc o kontrybucji do Open Source, nie mam na myśli np. nowych ficzerów Reacta (chociaż do odważnych świat należy). Czasami jedna linijka kodu potrafi rozwiązać czyjś problem. Ba! Nie musisz wcale kodować. Pisanie dokumentacji to też cegiełka do Open Source. Pierwszy commit Kent C Dodds'a w ramach Open Source to była literówka. Nie wierzysz? - zobacz ten wpis.

Podsumowując - jedno Twoje zdanie podczas rekrutacji - "aktywnie udzielam się w świecie Open Source" znaczy więcej niż portfolio z fajerwerkami.

Załóż konto na Twitterze, ale ...

Znowu - kiedy zaczynałem szukać pierwszej pracy, jedynym portalem typu social media był dla mnie Facebook. Dopiero po czasie zobaczyłem ile mnie omija. Jeśli chcesz być na bieżąco z informacjami dot. technologii to Twitter jest chyba najlepszą opcją. Facebook = rodzina i przyjaciele, sprawy for fun, śmieszki, heheszki, memy, zdjęcia. Twitter = nowinki technologiczne, ciekawi ludzie z branży, motywacja, inspiracje. Dlatego, jeśli jeszcze nie masz konta na Twitterze, to czym prędzej je zakładaj. Poszukaj kilku osób z branży, a potem poszerzaj listę obserwowanych. Nie bój się również usuwać ludzi z listy. To nie są Twoi przyjaciele - nikt się nie obrazi :) Jeśli nie podobają Ci się treści, jakie wrzuca obserwowana przez Ciebie osoba - po prostu przestań ją obserwować, albo wycisz jej tweety.

Z durgiej strony - nie obrażaj się, jak Twój "idol" wrzuci od czasu do czasu posta niekoniecznie związanego z programowaniem. Koniec końców jest to portal typu social media. Zrzut ekranu ze Spotify jeszcze nikomu krzywdy nie zrobił ;)

No ale, co z tym "ale"?

Uważaj na celebrytów-IT

pfff "że co!?". Wierz mi, albo nie, "kiedyś to było". Może inaczej - kiedyś to NIE - było tylu blogów, tylu informacji, tylu kursów, tylu "mentorów". Z czasem ludzie podchwycili temat pt. "praca w IT = dużo hajsu". Zaczął się napływ ludzi do branży, bo to przecież "łatwe pieniądze". Siedzi się tylko i klepie w klawisze. Jak grzyby po deszczu zaczęły wyskakiwać kolejne szkoły programowania, bootcampy, kursy, mentorzy. Zrobił się z tego niezły biznes. Przecież każdy chce zarobić - co nie? - co w tym złego?

Nic. Jeśli masz pieniądze to je wydajesz jak chcesz. Gdybym tylko miał sobie dawać w tej kwesti radę, to powiedziałbym "uważaj na celebrytów w IT". Trochę takich ludzi szufladkuję, sorry. Naczytali się Aniserowicza i Szafrańskiego, jak to można zarabiać na blogu, kursach itp. Sami ledwo co skończyli bootcamp, liznęli pierwszej pracy a już wydają swój autorski kurs - "Programowanie w HTML dla zaawansowanych". Brzmi jak dowcip? Niestety. Brzmi jak zazdrość - kto wie - być może. Niestety nikt nie uczy tego, jak odfiltrować dobry content od tego skopiowanego i nastawionego na szybki zysk. Czasami nie jesteśmy w stanie zweryfikować doświadczenia danej osoby. Kto wie - może naczytał się pierdół o żabach i teraz na siłę próbuje zainteresować tym innych :) Sam musisz sobie wyrobić czujnik na takie osoby - Przemku.

Dobra wiadomość jest taka, że tych dobrych "dusz" jest więcej. A takie celebryto-IT-pijawki zdarzają się sporadycznie.

PS. Nie zrozum mnie źle. Dzielenie się wiedzą na blogu, vlogu (whatever) nawet jeśli dopiero co nauczyłeś się "czegoś" jest SUPER! Ale natychmiastowa próba zarabiania na tym - już nie - przynajmniej nie dla mnie. Gdy płacę za kurs, to chcę mieć pewność, że dana osoba "zęby na tym zjadła", a nie naczytała się pierdół o żabach ;)

Nie kupuj książek

A przynajmniej tych o technologiach. A już na pewno nie kupuj ich z myślą "kiedyś przeczytam". Książki o technologiach szybko się starzeją. Zwłaszcza te o technologiach frontendowych, o frameworkach itp. Jeśli chcesz mieć fajną podstawkę pod monitor - spoko, your choice :) Mam takie dwie cegły pt. JAVA ^^ #naPóźniej.

Zamiast tego, skup się na książkach ponadczasowych. "Clean Code", "Clean Coder", "Pragmatyczny Programista", "Zawód Programista", "Refaktoryzacja" ... to są książki, które się nie starzeją. Po takie książki warto sięgać kilkukrotnie w swojej karierze. Za każdym razem wyciągniesz z niej coś innego, będziesz miał inny punkt widzenia, inny poziom doświadczenia.

I żeby było jasne - nie ma nic złego w książkach o samych technologiach/frameworkach - o ile kupisz aktualną wersję i przeczytasz ją zaraz po zakupie. W innym przypadku - "daj se siana" ;)

PS. Jeśli możesz - czytaj w oryginale, inaczej mówiąc - uważaj na tłumaczenia. Wiem, że oryginały są znacznie droższe w porównaniu z wydanymi nad Wisłą "tłumaczeniami" - ale warto. Obserwuj takie strony jak HumbleBundle, tam często pojawiają się "paczki" książek np. z wydawnictwa O'Reilly Media i można je dostać za "śmieszne" pieniądze.

Eksperymentuj, baw się kodem

Często na grupach dla początkujących czytam: "najpierw skup się na podstawach, dopiero potem zajmij się Reaktem". Ding-dong - Bullshit detector - Ding Dong. Owszem - podstawy pt. zmienne, pętle, funkcje wypadałoby ogarnąć przed frameworkiem. Ale jak już łykniesz podstawowej składni to śmiało wypływaj na głębie. Podczas nauki samego Reakta otrzesz się o funkcje wyższego rzędu, kompozycje, destrukturyzację i to w takiej praktycznej formie. Nie ma sensu czekać!

It's fine to learn React while you're learning JavaScript. Frameworks can teach you closures, higher order functions, ternaries, etc...
— Eric Elliott (@_ericelliott) June 6, 2020

Inny wymiar tej rady mówi o tym, że programowanie powinno sprawiać Ci frajdę. Nie bój się napisać "brudnego kodu", eksperymentuj, baw się. Wykorzystaj różne podejścia. Sprawdź w czym najlepiej się czujesz.

W programowaniu chodzi o rozwiązywanie problemów. A najpiękniejsze w tym wszystkim jest to, że wiele problemów można rozwiązać na wiele, wiele, wiele różnych sposobów.

I na koniec - jeśli masz już za sobą ciężki bój przez te "podstawy", a pisanie każdej kolejnej linijki sprawia Ci ból - to zastanów się czy to na pewno dla Ciebie. Praca programisty nie jest usłana różami, czasami trzeba zanurkować w niemałe szambo i nikt Cię za to po plecach nie poklepie. Z drugiej strony - nie samymi programistami IT stoi. Do branży można wejść na różne sposoby ;)

Naucz się świadomie zarządzać czasem

Z niecierpliwością czekam, aż mój kolega Radomir, zbierze się w sobie i wygłosi prezentację na temat zarządzania czasem. Sprzedał mi ten temat kiedyś przy jakiejś kawie. Główny przekaz jest mniej więcej taki - jeśli jesteś na studiach to nawet nie wiesz ile masz wolnego czasu. Dopiero (o zgrozo) po czasie dochodzi do nas, ile cennych minut przepaliliśmy. I żebyśmy się dobrze zrozumieli - nie ma nic złego w naparzaniu po nocach w Counter Strike'a (gra się jeszcze w to?). Nie ma nic złego w imprezowaniu. Jest taki okres w życiu człowieka - studia - gdzie dopiero poznaje się "co to życie". Korzystaj póki możesz :) Ale pamiętaj - już nigdy nie będziesz miał tyle czasu co teraz. Każdy z nas ma tyle samo czasu. Doba ma 24 godziny. Różnimy się tym, jak ten czas wykorzystujemy. Naucz się swoich nawyków. Swojego organizmu. Sprawdź kiedy jesteś najbardziej produktywny, kiedy najlepiej się uczysz. Wykorzystuj to. Naucz się świadomie zarządzać czasem.

Ostatnio na Twitterze napisałem, że praca programisty to nieustanna nauka. Tak jest. Na tę naukę też trzeba umieć znaleźć czas. Chcesz prowadzić bloga? Sprawdź ile czasu zajmuje napisanie posta. Kanał na Youtube? Kurs gita, czy babela nagrywam już chyba od lutego :) To nie jest proste. Na wszystko trzeba znaleźć ten cholerny czas. Dlatego Przemku - naucz się świadomie zarządzać czasem.

Zainwesuj w umiejętności miękkie

Do pierwszej pracy dostałem się na staż. To nawet nie było stanowisko juniorskie. Kiedyś staż kojarzył mi się z parzeniem kawy i wpinaniu kartek do segregatora (tak tak, i jeszcze za to Unia płaciła...ale ciiiiii 🙊). Ale w Samsungu było inaczej. Konkretny projekt, konkretni ludzie, ogrom wiedzy. Dacie wiarę, że startowałem do zespołu C++ (myślałem, że jak kodowałem w tym języku na studiach to się uda) a dostałem się do zespołu SmartTV, w którym pisaliśmy we frontendowych technologiach? W życiu bym nie powiedział. Dla mnie JS kojarzył się tylko z jQuery i śnieżynkami na stronach. No ale nie o tym chciałem pisać.

Byłem zielony - to fakt. Szybko musiałem nadrobić wiedzę. Udało mi się to dzięki wspaniałym ludziom, z którymi miałem okazję pracować - ale o tym będzie następna rada. Pomimo braku w wielu kwestiach techniczncyh - dosyć szybko awansowałem. Dostałem też możliwość poprowadzenia małego zespołu. Mój szef coś we mnie dostrzegł. Od liceum bardzo lubiłem nawiązywać nowe kontakty. Uważałem się za duszę towarzystwa. Tu coś zagrać na gitarce, tu zagadać, tu się pośmiać. Spotkałem świetnych ludzi na swojej drodze. Byłem szczery, życzliwy, pracowity (teraz też jestem, żeby nie było 😜). Z perspektywy czasu widzę, że to właśnie relacje jakie budowałem z ludźmi pozwoliły mi tak szybko awansować, tak szybko stanąć na czele zespołu.

Bardzo często nie doceniamy umiejętności miękkich w IT (chociaż zauważam zmieniający się trend). Zdradzę Ci teraz pewien sekret - Przemku - pisanie kodu to nie wszystko. Ba! Umiejętna komunikacja i zdolność do budowania relacji znaczą o wiele więcej niż klepanie kodu.

Dlatego - zainwestuj w umiejętności miękkie. Sprawdź jak dobrze się komunikować - bo to wcale nie jest takie łatwe.

Znajdź mentora

W poprzednim punkcie pisałem o świetnych ludziach, z którymi miałem przyjemność współpracować. Szymon K., Grzegorz D., Bartek K., Maciej W. (trochę jak z kryminału :D...no ale nie wiem czy chcieliby się znaleźć tu z nazwiska więc dla pewności zostawiam tak :))...wiele by wymieniać. Wszysktich ich łączy jedno - dążyłem do tego, by być na zbliżonym do nich poziomie. Nie porównywałem się, bo to nie ma sensu. Każdy ma swoją drogę, swoje przeżycia, doświadczenia. Ale możemy się inspirować, czerpać wiedzę, pytać o przeżycia i bazować na doświadzczeniu innych. Dzięki temu zwiększałem prędkość nauki i wchodzenia na wyższy level. Dzisiaj nie wyobrażam sobie pracy w środowisku, w którym nie mogę uczyć się od lepszych od siebie. Zawsze szukam takiej osoby i staram się inspirować.

PS. Pamiętaj, że to może działać w dwie strony. U kogoś widzisz rzecz, której Tobie brakuje...za to ta druga strona widzi w Tobie rzeczy, które ją inspirują do działania. Dzięki temu wzajemnie się napędzacie.

Kup notatnik

Wszyscy mówią - załóż bloga, załóż kanał na YT. A ja mówię - kup notatnik. Taki zwykły zeszycik A5 może być. Zapisuj tam skrzętnie to, czego się nauczyłeś. Czytając książki, bądź oglądając kursy - rób notatki. Spisuj swoje osiągnięcia. Zapisuj przemyślenia. Rysuj mapy myśli. To pomaga - serio. Pomaga - ale z czasem. Np. podczas rozmowy o podwyżkę. Takie rozmowy często odbywają się raz do roku. Czy jesteś w stanie z pamięci wyrecytować wszystkie swoje osiągnięcia. Podpowiem Ci - NIE!. Czasami robimy małą rzecz dla siebie, ale wielką dla projektu. Zapisując swoje wszystkie sukcesy i porażki jesteś w stanie popłynąć na takiej ocenie rocznej i wywalczyć upragnioną podwyżkę. Ale nie rób notatek dla pieniędzy :) rób je dla siebie i dla swojego mózgu, który nie zawsze jest w stanie wszystko spamiętać ;)

PS. Bloga też sobie załóż jak chcesz - dziel się tam swoją nowo-zdobytą wiedzą i doświadczeniem. Tylko proszę - nie nastawiaj się od początku na "zarabianie z bloga". Nie każ mi akceptować powiadomień i zapisywać się do newslettera :) Na początku bloga prowadź go dla siebie. Sława i splendor przyjdą z czasem....albo i nie :P

Doszlifuj angielski

W liceum nie byłem jakoś specjalnie zainteresowany angielskim. Tu trójeczka, tam czwóreczka, tu coś ściągnąć, tam zagadać i "jakoś to będzie". Szybko tego pożałowałem. I choć nie miałem problemu w zrozumieniu słowa pisanego (dokumentacja, książki, maile) to szybko zarobiłem "plaskacza" w momencie, kiedy miałem poprowadzić spotkanie czy prezentację po angielsku. Mówi się, że podstawowym językiem programisty jest język angielski - to prawda. I chociaż coraz więcej publikacji powstaje w języku polskim, tłumaczone są dokumentacje (patrz React) to nadal - posługiwanie się językiem angielskim to podstawa. Bardzo dużo dają tzw. English-Days. W Suncrapers, w którym miałem okazję pracować, był taki jeden dzień - chyba czwartek z tego co pamiętam. W czwartki rozmawiało się tylko po angielsku. To nic, że w projekcie sami polacy. Trzeba było tłumaczyć i szprechać po inglishu. Wiadomo - dla ludzi, którzy dużo się oczytali, ale mało mówili to był problem. Wytłumaczenie prostej rzeczy zajmowało x2, x3 albo x4 tyle co po polsku. Z drugiej strony dzięki takim zabiegom później było łatwiej :)

Dzisiaj nie mam już problemu z posługiwaniem się językiem angielskim. Cały czas pracuję nad wzbogacaniem słownictwa (aktualnie trenuję z dziećmi Ba-Ba-Black Sheep ;))

Dlatego Przemku, jeśli to czytasz i chcesz wejść do IT - to wiedz, że bez angielskiego - ani rusz!

Podsumowanie

I to by było na tyle. Takie rady dałbym sobie dzisiaj, gdybym miał zaczynać jeszcze raz w IT. Banalne? Kontrowesyjne? Nudne? Dajcie znać w komentarzach ;)

Watch out for fixtures in cypress.io

Fri, 26 Jun 2020 00:00:00 GMT

Today I would like to tell you a story about a bug that cost me two days of searching and debugging sessions. It turned out a trivial thing, and with a better error message, it could have taken seconds instead of days. Let's go!

Hey Przemek! Could you help me?

A few days ago, I noticed that our VRT (Visual Regression Tests) suite started to fail for one case. I've asked my colleague, Monica, to check it. She accepted the challenge. After a long day of searching the root cause, she told me that she doesn't have any idea why the test is failing. On the local machine, it has been passing all the time, but on our GitlabCI, we got an error. Weird thing, isn't it? Monica was resigned and asked me for help. After two days of trying, committing, pushing, waiting, we've finally found it.

Fake server

We use a lot of tools in our tests. For unit testing, we use jest. In E2E, we use py.test with webDriver bindings. We also have UI tests that check our app on a higher level (interactions between components, pages, or views). Recently we introduced another test suite - VRT (Visual Regression Tests). The last two (UI and VRT) are based on cypress.io. It is an excellent tool for writing tests - from unit to full E2E.

Backend in our app is very complicated, and it is tough to setup a local environment. Because of that, for UI and VRT tests, we use a killer feature from cypress.io - network stubbing. Cypress can plug in between our app and network request giving us a possibility to decide about the response from API endpoint.

it("test with network stubbing", () => {
  // First, we need to start fake server
  cy.server()
  // Next, declare the route that we want to stub
  cy.route("/api/endpoint", { value: 1 })
})

More info about stub responses can be found in official Cypress documentation.

Fixtures

Fixtures are another feature from cypress.io that we use a lot, especially in our VRT suite. A fixture is a simple file that holds the data. We can reuse this file in many places. It helps us in organizing tests and managing the common responses from stubbed network requests. To load a fixture, we use a cy.fixture command. It expects a path to the file that we want to load. The path should be relative to a folder specified to hold fixtures (cypress/fixtures by default). Let's assume that we have the following file structure:

- fixtures
    - myFixture.json
    - someSubFolder
          - mySecondFixture.json

And now let's look at code which loads fixtures:

it("test with fixtures", () => {
  // We don't need to specify the file extension
  // Cypress will try to figure it out
  cy.fixture("myFixture").then(data => {
    // Here we can read the data
  })

  // We can save the fixture as an alias ...
  cy.fixture("someSubFolder/mySecondFixture").as("myAlias")

  // ...and then use the alias in stub of response
  cy.route("/api/endpoint", "@myAlias")
})

Authors of Cypress took care of reducing a boilerplate needed to use a fixture in stubbing network requests 🔥🔥🔥. The cy.route command can take a shortcut to fixture as a response argument:

cy.route("/api/path", "fixture:myFixture")
cy.route("/api/endpoint", "fx:someSubFolder/mySecondFixture")

In this way, we stubbed a network request with data kept in reusable fixture files. Great job!

Where is the hero of the story?

Ok, but where did our bug go?

I've created a simple app to visualize the issue. In the beginning, the app displays the Loading… message, then makes a request and replaces the text with a downloaded response.

Fetching the data in old, good XHR way 😎

<body>
  <div id="main">Loading...</div>
  <script>
    const mainEl = document.querySelector("#main")

    const req = new XMLHttpRequest()
    req.open("GET", "/api/endpoint", true)
    req.onreadystatechange = function() {
      if (req.readyState == 4) {
        const msg = req.status == 200 ? req.responseText : "Error"
        mainEl.innerHTML = msg
      }
    }
    req.send(null)
  </script>
</body>

I've also written a test:

describe("Simple fixture test", () => {
  it("displays response", function() {
    cy.server()
    cy.route("/api/endpoint", "fixture:examplefixture")

    cy.visit("/")

    cy.get("#main").should("have.text", "Hello")
  })
})

And created a fixture file fixtures/exampleFixture.json:

Hello

Have you noticed a bug yet?

In my case, the screenshot from the failed test was very helpful. Cypress takes them by default for failing tests, which is neat 🔥!

Screenshot from failed test

And now...Have you noticed a bug yet?

A message about the status from the stubbed request caught my attention. It was 400 instead of 200. That was a clue.

The typo and file systems

Our bug, which we've been trying to solve with Monica, was a simple typo. The name of the fixture file was in camelCase, and we tried to load it via shortcut without the same naming convention.

exampleFixture.json vs cy.route("/api", "fixture:examplefixture")

Ok, but why does it work on the local machine and doesn't on CI?

99% of our frontend team works on MacBooks. Our CI runs the tests in the docker container (Linux). You can think - "so what?". The default file system on Linux is case sensitive. On the other hand, the default file systems on Mac or Windows are not. What does it mean in practice?

On Linux you can create two files with the "same" name (different letter case):

myAwesomeFile.js
myawesomefile.js

Linux treats them as separate files. Try to do the same on Mac or Windows - you can't do it. It has also impact on the way how you load the files, for example in nodejs. On Mac, there is no difference in load file by "myFixture" or "mYFiXtURe" names - the file will be loaded. On Linux, we will get an error - file not found.

Let's check it

If we modify the code of our test in this way:

cy.route("/api/endpoint", "fixture:ExAmPlEFiXTuRe")

The test is always green on Mac. On Linux we get a 400 status for stubbed network request and an error message in console.

Screenshot with 400 for stubbed request

CypressError: The following error originated from your application code, not from Cypress.

When Cypress detects uncaught errors originating from your application it will automatically fail the current test.

This behavior is configurable, and you can choose to turn this off by listening to the `uncaught:exception` event.

https://on.cypress.io/uncaught-exception-from-application

Wait, wait, wait...WAT? The following error originated from your application code, not from Cypress. Are you sure Cypress? 🤔

Let's try to load the fixture without a shortcut:

// We made a mistake in fixture name
cy.fixture("examplEFixture").as("response")
cy.route("/api/endpoint", "@response")

// With storing fixture in an alias we can use it in our assertions
// We don't need to hardcode the "Hello" string
cy.get("@response").then(data => {
  cy.get("#main").should("have.text", data)
})

The error message for this code is quite different:

Error: A fixture file could not be found at any of the following paths:

> cypress/fixtures/examplEFixture
> cypress/fixtures/examplEFixture{{extension}}

Cypress looked for these file extensions at the provided path:
.json, .js, .coffee, .html, .txt, .csv, .png, .jpg, .jpeg, .gif, .tif, .tiff, .zip

Provide a path to an existing fixture file.

And this is the error message that I've been counting on 👏 . We know right the way where we should start looking 😎.

Summary

There are two takeaways from this story:

small typo could make you cry for two days of debugging session
you are as good as the error message from your test runner ;)

I think that Cypress could return the better message about missing fixtures than CypressError. That's why I've created an issue in cypress GitHub repository - here you can check the status.

Thank you for your attention. I am going to try to solve the issue that I've created 😉. Maybe I will be able to add something to the OpenSource community to make cypress.io even better 😁

Stop the time with cy.clock

Wed, 22 Apr 2020 17:00:00 GMT

Today I’m going to show you how to stop the time with one command. Unfortunately only in cypress.io tests. If you know how to do it in real life please DM me. It would be a very helpful tip 🙂. Ok, let’s stop joking and get our hands dirty!

App description

First, we need to have something to test. Our app will be deadly-simple. We want to display the enter time and a counter shows how many seconds we spent in the app.

Enter time:

Time on page: 0

import React from "react"

export default () => {
  const [enterDate, setEnterDate] = React.useState()
  const [counter, setCounter] = React.useState(0)

  React.useEffect(() => {
    setEnterDate(Date.now())

    const intervalId = setInterval(() => {
      setCounter(prev => prev + 1)
    }, 1000)

    return () => clearInterval(intervalId)
  }, [])

  return (
    <div>
      <p>
        Enter time: <span data-testid="enter-time">{enterDate}</span>
      </p>
      <p>
        Time on page: <span data-testid="counter">{counter}</span>
      </p>
    </div>
  )
}

Ok, we have our app. Now it is time to write some cypress tests.

We are testing!

In our test scenario we would like to check:

if the enter time is displayed properly,
if the counter increases its value after a one-second tick.

Let's try this way:

cy.visit("/")
  .get("[data-testid=enter-time]")
  .should("have.text", Date.now().toString())

The test looks decent but it doesn’t pass 😢

Assertion error

If we would like to show some formatted date (eg. 22-04-2020) instead of a number of milliseconds, then it would not be a problem. But our client wants to display milliseconds and we need to live with this requirement 😉

The cy.clock command comes with a rescue. It overrides native global functions related to time allowing them to be controlled synchronously via cy.tick() or the yielded clock object. This includes controlling:

setTimeout
clearTimeout
setInterval
clearInterval
Date

You can find more info about cy.clock in the cypress.io official documentation.

Now, let’s try to add cy.clock to our test:

cy.clock()
  .visit("/")
  .get("[data-testid=enter-time]")
  .should("have.text", Date.now().toString())

We still get an error. But this time the error message is different.

expected <span> to have text '1587547901669', but the text was '0'

What is going on with that 0? Because the time represented in timestamp value is a number of seconds passed from the start of Unix epoch (1st January 1970). We could ask what will happen after the 19th of January 2038 but this is a topic for another blog post 🙂.

Calling cy.clock without any arguments sets the date in our app to 1st January 1970. We could change it by passing an argument to the cy.clock:

const now = Date.now()
cy.clock(now)

Right now, with a little luck, our test will pass. It depends on how fast our computer is 😄. To fix this issue we need to remember that cy.clock overrides the time in our app, not in our tests (command chain). That’s why we need to change Date.now() in our assertion to now value that we’ve created at the beginning of the test.

const now = Date.now()
cy.clock(now)
  .visit("/")
  .get("[data-testid=enter-time]")
  .should("have.text", now.toString())

The test is green - always! - success! But there is one little difference in how our app works now. Before using cy.clock our timer has been running. Right now it stops on 0. Fortunately, it is expected behavior in our test-case scenario. We've set and stopped the time.

In order to move the time with some value, we need to call cy.tick command:

const now = Date.now()
cy.clock(now)
  .visit("/")
  .get("[data-testid=enter-time]")
  .should("have.text", now.toString())
  .get("[data-testid=counter]")
  .should("have.text", "0")
  .tick(1000)
  .get("[data-testid=counter]")
  .should("have.text", "1")

Tada 🎉! We've just wrote the test checking the enter date and the value of the counter.

What if we would like to set the date only - without stopping the time? 🤔

That’s a great question. Sometimes we would like to override the Date object only, leaving the rest untouched (setTimeout, etc.). In this case, we need to pass a second argument to the cy.clock - an array of timing functions that we want to override.

cy.clock(Date.UTC(2020, 3, 22), ["Date"])

In this example we set the date/time to 22th April 2020 00:00 UTC (yeap - months in Date starts from 0 that's why April = 3 🙂). In the same time we don't override the setTimeout and the rest time functions.

That's all for today. I hope that with this knowledge you can go now and stop the time in your tests 😉

Good luck!

3 Steps to Awesome Test Reports with Cypress

Wed, 18 Dec 2019 00:00:00 GMT

In this article, you will learn how to generate informative test reports with Cypress and how to enrich them with some screenshot context. This will help you to fix your potential bugs way faster 😄 All you need is three simple steps.

At Egnyte we ❤️ to test

Keeping the highest possible quality of the product is one of our top priorities at Egnyte. That's why we love to test. But our applications are rather large and relying on manual testing would be exhausting for us. That's why test automation and Continuous Integration techniques are our best friends. We write a lot of tests: unit, integration, end-to-end, module, etc. The most important part is that, at the end of the day, if our Jenkins pipeline is green, we are sure that we didn't break any parts of the system.

So where is the problem? Didn't you know that tests not always pass? And that's fine :) We don't need to panic right away. First, let's calm down, get into the test report on Jenkins, check what is broken, and fix it. That's it. The problem is that the test report is very often just a plain error message plus a stack trace. And it's enough for unit tests or integration tests for our React components, redux connections, and so on. On the other hand, this is not always helpful for tests that are run in the browser. Let's imagine the following result from a test:

Jenkins console output

I took this failed test report from our data governance product (Egnyte Protect), which is one of our core products. For writing integration-UI tests, we use an awesome tool called cypress.io. I must admit that Cypress and cypress-testing-library are doing an excellent job in terms of error messages. Judging by the test report shown above, it is clear that we cannot find an element with matching text. Of course. But what is the visual state of the app? As a developer of Egnyte Protect, I know that this message should appear in a dialog. Has this dialog been opened? Or maybe it is only a typo? So many questions and no answers. If we wanted to check it, we would need to run the test locally once again and see what the visual state of the app is. Only then we would know (spoiler alert) that we have a typo :).

What if we displayed the visual state of the app right in the Jenkins report?

Screenshot from the app

Wow! Now we know that the dialog is opened, and that the subheader text is incorrect! We have some valuable context just from reading the test report enriched with a single screenshot.

So how we could add screenshots to our test reports? Let's find out!

HTML reports to the rescue!

Cypress is based on mocha.js. And this is great because mocha.js is a very mature project with many custom extensions. Test results can be generated within elements called reporters. We can write our custom reporter or use an existing one, for example, mochawesome. As the name suggests, it generates AWESOME reports! Badum tsss.

And now, I would like to show you how to integrate mochawesome with cypress to generate HTML reports with a screenshot context for failed tests. For the sake of this blog post, I've used an example repo cypress-example-kitchensink. We will do it in 3 simple steps. Let's get our hands dirty!

Step 1 - set up the reporter

First, we need to install proper reporters. Yes, that's right - plural - reporters. We still want to see test results in the console. Maybe you also want to have a JUnit XML report. We need to have one reporter per expected outcome (console, HTML, XML). In order to set up many reporters, we will use the cypress-multi-reporters package. On top of that, we also need mocha and, of course, mochawesome.

npm install --save-dev mocha cypress-multi-reporters mochawesome

Or if you use yarn:

yarn add -D mocha cypress-multi-reporters mochawesome

Then, in the cypress.config file, we need to specify which reporter we want to use:

{
  "reporter": "cypress-multi-reporters",
    "reporterOptions": {
      "configFile": "reporter-config.json"
    }
}

The configFile field points to the reporters configuration file. We need to add this file to our repository. For each of the reporters we can specify some options. Let's do that for the mochawesome reporter:

{
    "reporterEnabled": "mochawesome",
    "mochawesomeReporterOptions": {
        "reportDir": "cypress/results/json",
        "overwrite": false,
        "html": false,
        "json": true
    }
}

In this fragment of config, we specify an output directory for the results file. We want to collect only the JSON files for each spec file. That's why the html flag has been set to false. Because cypress is able to run tests in parallel, we need to set the overwrite flag to false. It means that for each spec file, we will generate a separate file. In our case, these will be JSON files.

Let's try to run our tests via npm run local:run command.

Running:  examples/location.spec.js                                                      (9 of 19)
Location
    ✓ cy.hash() - get the current URL hash (169ms)
    ✓ cy.location() - get window.location (101ms)
    ✓ cy.url() - get the current URL (78ms)
3 passing (1s)
[mochawesome] Report JSON saved to /Users/przemuh/dev/cypress-example-kitchensink/cypress/results/json/mochawesome_008.json

As you can see, after the spec reporter results, we received information that the mochawesome_008.json file has been created. Each of the spec files generated a JSON with results.

List of generated results

We are ready to go to the next step.

Step 2 - generate the report

We've collected the test results. Now, we need to merge them into one file and generate an HTML report based on it. We will use the mochawesome-merge tool to merge result files. Let's install it.

npm i --save-dev mochawesome-merge
yarn add -D mochawesome-merge

Now, let's add an npm script which will be responsible for running the merge tool.

"report:merge": "mochawesome-merge --reportDir cypress/results/json > cypress/results/mochawesome-bundle.json"

The reportDir flag specifies where we keep results files. The output of the command is passed from stdout to the mochawesome-bundle.json. One caveat here: the result of the merge needs to be put in a different folder than where the single results file is.

After merging we are ready to generate a final HTML report. In this case, we will use mochawesome-report-generator.

npm i --save-dev mochawesome-report-generator
yarn add -D  mochawesome-report-generator

Let's create an npm script for that action:

"report:generate": "marge cypress/results/mochawesome-bundle.json -o cypress/reports/html"

Marge is a short form of MochawesomeReportGEnerator in case you've been wondering :)

Once the script has run, our awesome HTML report should appear in the cypress/results/html folder.

HTML report view

There is one more thing to do. Add a screenshot to tests that have failed.

Step 3 - add screenshot context

Cypress automatically generates screenshots for failed tests in the cypress/screenshots folder. You can disable this behavior if you want. Screenshots are collected within the following folder structure:

path-to-the-specfile/spec.file.js/context - describe - describe - testTitle (failed).png

For example, the following test placed in examples/actions.spec.js:

context('Actions', () => {
  context("nested context", () => {
      it('.type() - type into a DOM element', () => {})
   })
})

will generate something like this on fail:

Folder with screenshot from failed test

Ok, so how we can connect these two elements: a screenshot generated by Cypress and a test result generated by a mochawesome reporter?

First, let's copy our generated screenshots to the folder where we keep the HTML reports. In order to do this, we will use an npm script:

"report:copyScreenshots": "cp -r cypress/screenshots cypress/results/html/screenshots"

Next, we will use the cypress/support/index.js file and write some code that will be listening on the test:after:run event.

Cypress.on("test:after:run", (test, runnable) => {
    if (test.state === "failed") {
        // do something
    }
});

For adding the screenshot to the test result, we need to use the addContext method from the mochawesome/addContext package. This method takes two arguments: an object with the test, and the context. If the context is a valid URL (could be a local path) to the image, then that image will be displayed. To see more details, visit the documentation page.

import addContext from 'mochawesome/addContext'

Cypress.on("test:after:run", (test, runnable) => {
    if (test.state === "failed") {
        const imageUrl = "?";
        addContext({ test }, imageUrl);
    }
});

Ok - but how to define the imageUrl? This is a time for magic to happen.

Just kidding :) we will use the runnable object. As we saw earlier, Cypress generates the name of the screenshot based on the test suite structure. We need to re-create that.

Cypress.on('test:after:run', (test, runnable) => {
  if (test.state === 'failed') {
    let item = runnable
    const nameParts = [runnable.title]

    // Iterate through all parents and grab the titles
    while (item.parent) {
      nameParts.unshift(item.parent.title)
      item = item.parent
    }

    const fullTestName = nameParts
            .filter(Boolean)
            .join(' -- ')           // this is how cypress joins the test title fragments

    const imageUrl = `screenshots/${
      Cypress.spec.name
    }/${fullTestName} (failed).png`

    addContext({ test }, imageUrl)
  }
})

From now on, if our test fails, a context field with a local URL to the image will appear in the JSON results file:

{
  "title": ".type() - type into a DOM element",
  "fullTitle": "Actions .type() - type into a DOM element",
  "timedOut": null,
  "duration": 10395,
  "state": "failed",
  "speed": null,
  "pass": false,
  "fail": true,
  "pending": false,
  "context": "screenshots/examples/actions.spec.js/Actions -- .type() - type into a DOM element (failed).png",
}

What is more, the image itself will be attached to the HTML report.

HTML report with screenshot context

TADA 🎉 We got it!

You can check all necessary code changes that we have done in the following pull request: https://github.com/przemuh/cypress-example-kitchensink/pull/1/files

Optional steps

You might want to add cypress/results and cypress/reports folders to your .gitignore.

It would be good to remove screenshots, results, and reports before the next test run. It can be done by a simple npm script. In our example repo, I've added:

"precy:run": "rm -rf cypress/screenshots cypress/results cypress/reports"

"Pre" means that this script will be run before every cy:run. See npm docs for more details.

In the example repo, there is a npm-run-all package installed. We could use it to run in sequence: merge, generate report and copy screenshots scripts in one command:

"report": "run-s report:*",
"report:merge": "mochawesome-merge --reportDir cypress/results/json > cypress/results/mochawesome-bundle.json",
"report:generate": "marge cypress/results/mochawesome-bundle.json -o cypress/reports/html",
"report:copyScreenshots": "cp -r cypress/screenshots cypress/reports/html/screenshots"

There is also one caveat. The file name in most systems is limited to 255 characters. So what will happen when we have a very nested structure of a test suite with long descriptions? It's simple - our file name will be truncated. Cypress truncates the full test name to 220 characters. So we could also do the same in our code:

const MAX_SPEC_NAME_LENGTH = 220;
const fullTestName = nameParts
    .filter(Boolean)
    .join(" -- ")
    .slice(0, MAX_SPEC_NAME_LENGTH);

But this is an implementation detail. We don't know whether Cypress devs are about to change that number. So, a better option would be to read an article from Kent C Dodds about avoiding nesting when you are testing.

Wrap-up time

I hope that this article will help you to set up awesome HTML reports in your project. It helps us a lot when it comes to quick investigations of why a given test is failing. Let's recap what we did here:

Install and set up the mochawesome reporter.
Collect test results and generate an HTML report based on the merged JSON file
Add screenshot context with an addContext function.

You can check all code changes here in this pull request. And of course, after you generate the HTML report you need to connect it somehow to your Continuous Integration tool. But this is a story for a separate post. :)

Now…are you ready to create your own Cypress HTML reports?