Gherkin jako droga do lepszej dokumentacji analitycznej?

Dodany w dniu 21/12/2021

Dobra dokumentacja analityczna powinna być zrozumiała dla klienta, zespołu programistów i testerów. Grupy te mają różne zakresy kompetencji i dlatego używają różnych kodów językowych.
 

Dobra dokumentacja analityczna powinna być zrozumiała dla klienta, zespołu programistów i testerów. Grupy te mają różne zakresy kompetencji i dlatego posługują się różnymi kodami językowymi. Dużym wyzwaniem dla zespołów analitycznych jest opisanie wymagań w taki sposób, aby żadna z tych grup nie miała wątpliwości co do celu projektu/zmian oraz aby nie pozostawić miejsca na swobodną interpretację. Sprostanie tym wymaganiom często nie jest łatwym zadaniem i stawia przed analitykami specyficzne wyzwania.

Czy język Gherkin może pomóc analitykom w ich pracy?
Zacznijmy od pytania o niedoskonałości klasycznych i powszechnie stosowanych metod: Use Case, czy User Stories stosowanych w metodach zwinnych. Przecież za ich pomocą można stworzyć doskonałą analizę, która nie pozostawia miejsca na wątpliwości, a Use Case pięknie integruje się z notacją UML.

Należy jednak zaznaczyć, że metody te pozwalają na dość dużą swobodę w skalowaniu precyzji, co dotyczy zwłaszcza User Stories, dla których szablon opisu jest bardzo ogólny. Dlatego też wiele zależy tutaj od doświadczenia analityka, który musi ocenić, które aspekty powinny być opisane szczegółowo, a które mogą pozostać bardziej ogólne, gdyż ich precyzja nie jest aż tak istotna dla powodzenia projektu.
Ten aspekt może więc stanowić pewien problem dla mniej doświadczonych analityków, którzy nie zawsze są w stanie poprawnie przewidzieć, jak inny członek zespołu zrozumie dany scenariusz i gdzie faktycznie można sobie pozwolić na mniej precyzyjne opisy. Dlatego też nowicjuszom czasami udziela się następującej rady:
"jeśli nie wiesz, gdzie możesz oszczędzić szczegółów, to po prostu opisz wszystko ze szczegółami
lub w podejściu iteracyjnym:
"na razie opisz wszystko ogólnie, a potem zobaczymy, co trzeba doprecyzować".
Wracając więc do pytania postawionego w tytule - zastanówmy się, czy i w jakim stopniu język Gherkin może pomóc w tworzeniu lepszej dokumentacji?

Co to jest Gherkin?
Jest to język naturalny, pod wieloma względami podobny do swoich większych braci wspomnianych powyżej. Wprowadza jednak dość wąskie ramy i określa, w jaki sposób powinny być one wypełnione treścią. Posiada słowa kluczowe, które definiują szablon języka:
Cecha - nazwa opisywanej funkcjonalności
Scenariusz - nazwa rozpatrywanego scenariusza (odpowiednik nazwy przypadku użycia/opowieści użytkownika); pod tytułem warto czasem dodać ogólny opis scenariusza, aby nadać mu pewien kontekst
Given - definiuje warunek początkowy, bardzo konkretny, np. jakie właściwości ma obiekt przed rozpoczęciem scenariusza (w pewnym stopniu jest to odpowiednik warunku wstępnego z przypadku użycia. User story nie ma swojego odpowiednika).
When - definiuje warunek uruchomienia scenariusza (odpowiednik triggera w przypadku użycia) - Then - akcja scenariusza, opisuje co dzieje się w scenariuszu (odpowiednik Basic flow w przypadku użycia)
And - słowo kluczowe, które może występować w połączeniu z Given, When i Then, które może być użyte do połączenia warunków w ciąg oznaczony znakiem "and". Czyli, jeśli definicja wymaga, aby kilka warunków miało miejsce jednocześnie, możemy użyć "And".

Do tego momentu, jak widać, nie jest to właściwie nic nowego, gdyż podobne odpowiedniki istnieją już w metodzie Use Case. Różnica tkwi jednak w szczegółach, na których oparty jest język Gherkin. Aby je lepiej zrozumieć, warto wspomnieć o historii tego języka. Gherkin został stworzony niekoniecznie dla analityków, a raczej dla testerów. Jego pochodzenie wywodzi się z wydanej w 2018 roku aplikacji Cucumber, która służy do automatyzacji testów akceptacyjnych opartych na procesie Behavior-Driven Development (BDD). Język Gherkin został wymyślony z myślą o tym rozwiązaniu właśnie po to, aby testy były bardziej zrozumiałe dla wszystkich zainteresowanych.
Pochodzenie to zobowiązuje nas do używania notacji Gherkin w taki sam sposób, w jaki byłaby ona używana w aplikacji Cucamber. Każdy scenariusz musi być oparty o precyzyjny opis, gdyż nie możemy napisać po prostu np. "Jeżeli produkt X jest dostępny to...", gdyż w scenariuszu testowym to nie zadziała, bo co to właściwie znaczy, że "jest dostępny"? W tym przypadku zapis musi być precyzyjny np. "Gdy produkt X ma status aktywny i jego dostępna ilość jest >= 1 to...". Tak będzie lepiej, prawda? Taki opis, jak widzimy, jest nadal opisem naturalnym, zrozumiałym dla klienta, ale ma tę właściwość, że jest również automatycznie jednoznaczny dla testera jak i programisty. Oczywiście same nazwy właściwości, jak np. "dostępna ilość" niekoniecznie muszą być tożsame z nazwą kolumny w bazie danych, czy nazwą pola w klasie aplikacji, ale jest on na tyle precyzyjny, że nie pozostawia wątpliwości co do swojego znaczenia i w tym sensie spełnia oczekiwania dobrej analizy.

Co zyskujemy poza jednoznacznością opisaną powyżej? Szczegółowość. Szczegółowość, która czasem może być też wadą tego rozwiązania. Nie da się zrobić scenariusza testowego w Gherkinie, który byłby jednocześnie ogólny i zgodny z regułami języka. Czy w takim razie nadal jedynym rozwiązaniem jest opisywanie wszystkiego w szczegółach? Niekoniecznie. Tu znów warto wrócić do źródła. Czy każdy, nawet drobny, obszar aplikacji wymaga scenariuszy akceptacyjnych? Nie, przecież testerzy niekoniecznie badają, czy np. sam przycisk reaguje na kliknięcie, chodzi przecież o pewne zachowanie (Behavior-D.D.). Jeśli więc chcemy używać tego języka podczas tworzenia analizy, nie powinniśmy w ogóle tworzyć scenariuszy dla nieistotnych funkcji. W tym przypadku warto rozważyć pozostawienie ogólnego opisu zamiast budowania scenariusza.

Doświadczony analityk zwróci teraz zapewne uwagę, że taki sposób dokumentowania z pewnością będzie wymagał więcej czasu - i będzie miał rację. Gherkin jest znacznie bardziej absorbujący. To, co w Use Case można zawrzeć w jednym scenariuszu jako Alternative Flows, w Gherkinie wymaga osobnego scenariusza. Ale w sumie ten nakład pracy zwróci się z nawiązką. Jeśli analityk przygotuje wcześniej scenariusze zgodne z BDD, tester nie będzie musiał tego robić. Dodatkowo, testerzy będą testować dokładnie to, co jest napisane w dokumencie analitycznym, zamiast stosować własną interpretację, co może zaoszczędzić wielu nieporozumień.Poniżej znajduje się przykładowy scenariusz wykorzystujący notację Gherkin.

Cecha 1: Kody promocyjne

Scenariusz 1: Walidacja-kodu aktywna, dodaj kod promocyjny do zamówienia

Biorąc pod uwagę, że klient znajduje się na stronie z podsumowaniem zamówienia
A w <STATUSIE> aktywny jest <KOD PROMOCYJNY> w systemie
Gdy użytkownik wprowadzi w polu Kod promocyjny <KOD PROMOCYJNY>.
I potwierdza operację
Następnie system sprawdzi, czy posiada on <KOD PROMOCYJNY>.
I potwierdzi, czy <KOD PROMOCYJNY> ma aktywny <STATUS>.
I pobierze informacje o <WARTOŚĆ KODU>.
I wyświetli, że <KOD PROMOCYJNY> dla <WARTOŚĆ KODU> został dodany do zamówienia.

Przykłady: (Wartości odpowiednich kolumn należy podstawić pod "placeholdery" oznaczone symbolem <COLUMN NAME>. )
| KOD PROMOCYJNY | WARTOŚĆ KODU | STATUS |
| Promocja1 | 10.00 | AKTYWNY |
| AZK6IKT21MCM | 20.00 | AKTYWNY |

Scenariusz 2: Validation-Code nie jest aktywny, komunikat błędu.

Streszczenie

  • Każda metoda, w tym Gerkhin, ma pewne zalety, ale i wady, dlatego jej wybór powinien zależeć od konkretnego przypadku.
  • Zalety wprowadzenia notacji Gherkin:
  • Bardziej precyzyjny opis wymagań w dokumencie analizy
  • Większa pewność, że powstający projekt spełni oczekiwania klienta
  • Mniej czasu poświęconego na uszczegóławianie wymagań podczas realizacji projektu
  • Możliwość wykorzystania na etapie odbioru tych samych scenariuszy, co w dokumencie analitycznym

Wady notacji Gherkin:

  • Bardziej pracochłonna faza analizy
  • Trudniejsze do nauczenia się notacji i zasad poprawnego formułowania scenariuszy
  • Kiedy użycie notacji Gherkin może być dobrą alternatywą w projekcie?
  • Czy obecna analiza jest na tyle ogólna, że różne grupy pracowników różnie interpretują jej zapisy?
  • Czy projekt posiada obecnie zautomatyzowany proces testów akceptacyjnych?
  • Czy w projekcie występują procesy o wyjątkowej złożoności, które muszą być bardzo szczegółowo opisane na etapie analizy?
  • Czy trudno jest formalnie zmienić ustalenia po etapie analizy?

Odpowiedź twierdząca na powyższe pytania jest wskazaniem do zastosowania metody Gherkina.