תיעוד בדיקות - למה זה טוב?What's the purpose of test documentation?

Today's post is a response to something I read online. Since the writer of that article probably doesn't read Hebrew, I will change the regular order and start this time with the English version.

In her post, Nicola Owen presents an interesting question: What's the purpose of test documentation? Her answer to this is simple - Test documentation is meant to communicate information.
Out of this simple statement she then continues on to examine the possible audiences of such communication efforts and provides an interesting insight to the way each audience is changing her mindset and focus points while writing the documentation.
However, while very interesting, I could hear my inner voice revolt. "I don't document test cases in order to communicate! at least not only for that" . So, I took a moment or so to stop and think "what do I use test documentation for?" and what was it in "communicating information" that got me ticked off?
Before I start, I would like to clarify a point that was a bit ambiguous for me - what is "test documentation"? It might be just my poor control of English that led me to understand it this way, but I differentiate "documentation" from "documents". The first is a term borrowed from the programming context, where it usually refers to the comments that explains what is being done in that weird piece of code just next to it. The latter is a bit more general and refers to any type of document produced during any of the testing phases. So, "documents" will contain everything - test plans, requirements, bugs, detailed test cases and possibly also my grocery store latest receipt (ok, that might be stretching it a bit too far). Test documentation, however, are mostly the step-by-step description of test cases performed, along with their run status. One might also debate whether filed bugs are part of it (Which, as far as I was able to judge, are referred to in the original post) but in order to keep things simple, I will exclude them.
Anyway, to the list of what I do with test documentation:

1. Communication with my future self or with my testing teammates.
   Yes, even though it's not the only thing I do, it is still very important for me. Those documents will later help me to recall how to use a feature I have not used for a year, or recall which configuration parameter controls what functionality and sometimes even whether some peculiar behavior of the system is intentional or not.
   Communicating outside of the test team is usually not done with test documentation but rather with an oral discussion, or filed bugs (that may or may not contain steps to reproduce the issue, according to the specific context of this bug). 
2. Organizing and formalizing data - I don't work well with fine details, I can focus on them from time to time, but I need to sit down explicitly and rephrase them in order to truly understand them and not be distracted by the bigger picture. Forcing myself to write down every tiny details drawn my attention to it: I notice what data is being written to which table in the database, which lines are relevant in the log files and I formalize a way to use the software. When I do that, I get more familiar with the software I am testing. 
3. Think a bit more about my tests - This is probably strongly related to the previous bullet: I can't recall the last time I wrote my test cases and did not find something that needed changing or that should be added to the test. 
4. review and control over what I am doing - yes, it is a bit similar to the communication part, only I do not intend to pass information, but rather to verify that I have covered everything I intended to cover and did not forget anything important as I was performing the tests. 

From those goals I derive my way of writing the test steps: Since I will be using them as a reference in the future, or someone new to the team will use them to learn about this feature, I write extensive descriptions that rely on the reader being generally familiar with the system, but otherwise will be very detailed, sometime up to the point of "Copy/Paste" commands.
As I use test cases in order to rethink my testing and to review the gaps I may have left, I also add to each step a title explaining its intention and providing me with a short way of understanding the step, or test case.

Finally, I would like to note that while writing test cases is one of the most hated tasks in our team, writing them down is proving useful again and again and again.


Edit - I just got to read this post I really liked it, because it emphasizes an important point that I only half mentioned in my third bullet - while writing down a test case I often find some bugs just because I stopped to think about it.
-----------------------------------------------------------------------------

בפוסט הזה מציגה ניקולה אוון שאלה מעניינת - מה מטרתם של מסמכי בדיקות? התשובה הבסיסית שהיא מספקת שם היא "מסמכי בדיקות משמשים כדי להעביר מידע", ומפנה את תשומת הלב לכך שיש קהל די מגוון שיכול לקרוא את המסמכים האלה - כולל הבודק עצמו, זמן מה בעתיד. 

אבל, תוך כדי קריאה, משהו בי התקומם. "אני לא מתעד בדיקות כדי לתקשר! לא רק בשביל זה, בכל אופן". ואז עצרתי לחשוב מה עוד אני עושה עם תיעוד בדיקות, ולמה המילה "תקשורת" כל כך הקפיצה אותי. 

בגדול, יש כמה דברים בהם תיעוד בדיקות עוזר לי (נשים לב להפרדה שנדמה לי שהייתה במקור - אנחנו לא מדברים על "מסמכי בדיקות", ובפרט לא על מסמכי תכנון בדיקות, אלא על "תיעוד בדיקות" - רישום פחות או יותר מדוייק של צעדי הבדיקה שבוצעו. 

ולהלן הרשימה: 

1. תקשורת עם עצמי העתידי ועם שאר צוות הבדיקות. כן, למרות שזה לא כל מה שאני עושה, מסמכי הבדיקות ישמשו אותי בעתיד כשאנסה להיזכר איך בדיוק להפעיל משהו, או כשאנסה להבין אם התנהגות מסויימת נעשית בכוונה או לא. תקשורת עם גורמים מחוץ לצוות הבדיקות לא נעשית דרך מסמכי תיעוד הבדיקות אלא במקומות אחרים - באגים שאנחנו פותחים, מסמכי תכנון בדיקות, או סתם לקום ולומר מה שיש לנו לומר. 
2. ארגון מידע - הפרטים הקטנים מבחינתי תמיד היו משהו חמקמק מאוד - אני מסוגל להתמקד בהם מדי פעם, אבל בדרך כלל אני רואה את התמונה הגדולה. כשאני מכריח את עצמי לשבת ולכתוב את הדרים ברזולוציה נמוכה - אילו ערכים יכולים להיכנס לאיזה משתנה, לאילו טבלאות במסד הנתונים דברים נכתבים, איך בדיוק להפעיל כל דבר - אני מקבל תמונה שלמה הרבה יותר של מה שאני בודק ולפעמים גם מגלה קשרים במקומות שלא בהכרח ראיתי אותם קודם. 
3. חשיבה מחדש על מקרי הבדיקה - זה קשור מאוד למה שקורה בסעיף 2: אני חושב שלא הייתה פעם אחת בה ישבתי לכתוב את צעדי הבדיקה - ולא משנה אם זה קרה יחד עם ביצוע הבדיקה, מייד אחריה או חודש אחר כך - ולא גיליתי עוד מקרה בדיקה שכדאי שאכסה. 
4. בקרה על מה שאני עושה - כן, זה קצת דומה לתקשורת, אבל אני נעזר במערכת ניהול הבדיקות שלנו כדי לוודא שמה שתכננתי לעשות אכן בוצע ושלא שכחתי שום דבר תוך כדי ביצוע הבדיקות עצמן. 

מהמטרות האלה נובע גם אופי מקרי הבדיקה שאני כותב - הם יהיו מפורטים למדי: משתני סביבה, טבלאות במסד הנתונים, התנהגות צפוייה וכיוצא באלה, אבל הם גם יכילו כותרת שתסביר מה המטרה של כל צעד.

והערה קטנה לסיום:

בסופו של יום - למרות שכתיבה של צעדים מפורטים היא אחת המשימות ממנה כולם משתדלים להתחמק, הערך של ביצוע הפעולה הזו מוכיח את עצמו בכל פעם מחדש. 

נוסף בעריכה - 

בדיוק קראתי את הפוסט הזה, והוא מאוד מצא חן בעיני כי הוא מדגיש נקודה חשובה שלא התייחסתי אליה מספיק בנקודה השלישית שלי: תוך כדי כתיבה של תרחישי בדיקה מפורטים אני מוצא באגים גם בלי להריץ שום דבר, פשוט כי עצרתי לחשוב.