Methods Annotations | Bondar Academy
Course: Cypress UI Testing with JavaScript
Module: Page Object Design Pattern
Instructor: Artem Bondar
Lesson Summary
In this lesson, the focus is on enhancing the clarity of page object methods in your code, making it easier for others to understand their functionality. Key Concepts Method Clarity: It's important that method names clearly describe their actions, but parameters can often be confusing. Using Annotations: Adding test annotations or method annotations can significantly improve the understanding of methods and their parameters. Steps to Add Annotations Place the cursor above the method name. Type / followed by ** and hit Enter . This will create a documentation block. Provide a description of the method and its parameters. Example For a method named submitUsingGridForm , you can describe it as: /** * Method to submit using the grid form with valid user credentials. * * @param {string} email - Valid user email. * @param {string} password - Valid user password. * @param {number} optionIndex - Index of the option radio button (starts from zero). */ Benefits of Annotations Improves readability and understanding of the method's purpose. Provides data types for parameters, which helps during development. Assists in auto-completion features in IDEs like Visual Studio Code. By consistently adding such annotations, you make your code more understandable for yourself and others, enhancing collaboration and maintenance. Remember, clear documentation is key!
Video Transcript
Hey guys, in this lesson, I will show you how you can make your page object methods more understandable, so it's gonna be clear what method is doing, all right? So let's jump into it. So currently, we have several methods and form layouts page and date picker page. And when you're reading the method name, it's kind of clear what is it doing. Submit using the grid form, it's clear, right? But for the arguments of this method, especially if the person who doesn't know this framework reading the test, sometimes it's not really clear what the first argument, what welcome is. Is it some kind of text or anything else, or what one means? It's also not clear at all. So to improve the clarity of the test and description of the methods, you can add test annotations or method annotations to the methods. So how to do this? So for example, this is the method submit using the grid form. So you put the cursor right above the method name. Then you put forward slash, double star, and hit Enter. And Visual Studio Code automatically creates for you block with the section where you can provide description for the method and for your parameters inside of this method. So for example, I provide the description methods to submit using the grid form with valid user credentials. Credentials, like this. And then three parameters automatically added. So this is star means what's the type of the data that we expected to use for our parameters. So email will be a string. Password also is a string, and the option index is the number. So like this. And also you can add the description for each of the parameters, what those parameters are about. For example, email is about valid user email. Password, we also can type something like valid user password, like this. And for option index, we can say something, provide index of the option radio button. Button start from zero, like this. So now it is a lot more understandable and descriptive what option index actually means. So when this information is shown after that. So if I go back to the test and just hover over this method, look. Right now, everything is clear and descriptive. So first of all, method to submit using the grid form, from. Okay, sorry, I need to update to form, like this. So method to submit using the grid form with valid user credentials and all three parameters. And also we provided here the data types and also when I hover over, look, it also email string, password string, and option index is number. For example, if I hover over the method where we don't have data types, since the JavaScript don't have a strict typing, it will show as any password, and is checkbox selected in any as well. But with provided annotation, we have a typing as well. And what is even more important when you, for example, start typing this method from scratch, for example, on form layouts page, submit using the grid form. And I put the method in parentheses. And then VS Code telling me, okay, the first argument should be, look, valid user email, and like, all right, and I know that it should be a string. And I put, okay, string, and then, for example, test at test.com. Then the second argument, I put the comma. And then VS Code telling me, okay, the second argument should be a valid user password. Okay, some password, something like this. And then I put a third argument, and then I see description again, provide index of the option radio button, start from zero. Now it is also meaningful what I should provide here, 0, 1, or 2, and so on. And for example, 1 or 0, and so on. So if you add annotations like this to all of your page objects with a clear description what method is doing, what parameters are expected, and what types of data expected for those parameters, it makes the page objects method significantly more understandable and clear for you and for other people who will use your framework. So don't be lazy to create those annotations, they are very helpful. All right, that's it, guys, and I'll see you in the next lesson.