Exploring Node Modules for Test Automation

Hello, everyone, my name is Kat Kniotek. I work as a quality engineer at Houseful, previously known as Zoopla. Thank you for joining my talk today.

I will be talking about exploring node modules for test automation. I will talk you through the process of building your own library, publishing to npm, and then using it.

So, we may start with the question, why? Why would you create your own library for test automation? So, I was working with two approaches for the tests. First one, the test framework would live in a separate repository. Would be a single place to manage test dependencies. The test would be sharing helpers and setup methods. Tests would be maintained by the QA team. You could have separate frameworks for UI and for the API tests, but mainly QA team would be responsible for updating it, adding it, debugging flaky tests. The second approach I worked with, and I'm being honest, favor is that tests live with the project, with the application project. And then they can be maintained by developers. So, let's say I would set up this framework and the developers would be adding tests, updating tests as required. However, this approach introduced lots of code duplication. Every time we're creating new API, new service, I would find myself copying, pasting from one project to another helpers, the setup configuration for the project. And also when I had to update one of the dependencies, test dependencies, I had to update in the five places. It wasn't really a way to go. That's why I decided to look into building my own library that would include all the helpers that I copy-paste from repository to repository. I could just install this library in a project and then use helpers as and when required.

So today, I will be talking about creating a module project with PMPM and VIT. I will be talking about test-driven development, testing it. As automation engineers, not often do we have opportunity to practice TDD. This is the opportunity. I will be talking about selecting NPM registries, so where you will publish your package. I will show you example of the GitHub pipeline workflow used to publish a new release, but also pre-releases. I will be talking about the versioning of the project is really important and importance of adding Readme. Those are a few checkbox that I will be talking about. But before we start to dive into how to build your own library, I would like to ask the question, and maybe discuss first, what this library would include? What sort of helpers? You find yourself often copy-pasting from project to project, so what helpers would be good to be in this test library? I often find myself using WAIT helpers. It doesn't matter if you work with Playwright, Cypress, Selenium.

We all have our custom WAIT helpers that are probably particular for the application we work on, and they can be stored within our new test library. Maybe you created your custom matchers and assertions, and you really like the way how they work, and you want to use them in other projects. So instead of copy-pasting, you can place them in this test library.

Configuration of your test, that can be shared as well. Authentication methods, so let's say that you work with, you test API, and the authentication for the service is CognitoToken, and each of the APIs, each of the projects use the same authentication method. So you have this helper to calculate base64 token from credentials. This can go to the helpers library as well. Page object models, maybe each of your tests interact with the login page, and the login page is the same for all applications. Maybe this login page, page object model could live in the library. And API client helpers and setup, setting up custom headers and so on.

So when we are starting the command line, instead of like doing all the project setup and so on, we can use the command line tool for pnpm and create the bit project. You will be prompted to answer a few questions around the framework. We are not using any react view or anything. We're just using other. Runtime to select will be library. That's really handy because that's what we are building. Language, I selected TypeScript to make our library type safe. If you ever used that sort of command line tool, like NPX, create React app or similar, you know that that's what will build for you like the project structure with lots of boilerplate. Code.

In our example, we can remove everything that is related to HTML. We won't be running our application in the browser. So HTML, CSS, SVG, they won't be useful in our project. Then you can start installing your favorite libraries. So let's say playwright, let's say Cypress, FakerJS or similar ones. And all your helpers should go to the lib directory, to main TS file. And here is an example how my main TS file looks like. It has a few methods, a few functions. The first one is the one that I mentioned, I like to use a custom wait helper. This is for playwright. I wait for a particular particularly response in the network tab, and then carry on with my tests. The one I mentioned as well, calculating cognito token from environment variables and returning the string, and demo helper to just print hello, name. So something fairly easy, easy to test. And then once you have all your helpers defined, well, you can start with one or a few. You need to export them in a index.d.ts This file is by default in your root of your project. So then here you export those functions that will be available from the library.

Okay, so what then? Testing. You can install vtest. Let's say you can add your unit tests for your methods, and of course make sure that the test stage is included in the pipeline in the workflow. But how we actually test our solution? So, we build the project, and, in theory, it's all good because we just copy the code over, work somewhere else, how we test it, we can actually install it and access those methods that are publicly accessible once the package is built. So, we will build the project, and then we will pack it. So something that will happen in the pipeline, in the pipeline we'll build, and then we'll publish. Published by default packs our project. And as the output of the PMPM pack command, there will be a file created, that is basically a name of the project from package.json with the version number. And this is our library. How we can test it. We can create the separate project and just install it. Something that I learned as part of the working on this project is that you can actually install the library from the file. So if you would run pmpm install path to your file, as you can see on the example, that will be installed in your package.json. It's fantastic.

And then you can just test it like import print hello from my test helpers, and it works. Well, didn't work with the first time. So don't discourage yourself if it won't work with the first time. You can just update the methods. Maybe you forgot to export it in the index file, rebuild it and publish it again, pack it again. It's obviously a trial and error and it's a great learning.

So once we have our project built, we know that it works because we can install it in another project. We need to start thinking how we will make it available across repositories and in other teams. One of the solutions for publishing our package would be to store it in npm. You can sign up to npm and publish your package there. If you are using free account, you are allowed to publish public packages. However, if you feel that your project, your module contains something related to the application, you don't want to expose this to outside world or something, you just don't want to make it public, you would need a paid account or enterprise level. Because I don't have it, I decided to publish my package with GitHub feed. It's also npm registry. You just specify a different registry URL that is pointing to your GitHub registry. You can also create the package on the organization level. You can make it private, public. Here's just an example. I was using my own GitHub account.

So we could use all the commands like build, pack, publish locally. We could log into registry locally and publishing it from there. However, from maintenance point of view, we wanted to be controlled by source control, by version control. So here is the example of a GitHub workflow that will be publishing our package. It will be publishing pre-release package. I'll be talking about it later. But what you can see here is a trigger. So this workflow will be triggered every time there is a pull request created against the main branch. This will check out our code and will create a .npmrc file. This file is used to authenticate your login to the npm registry. Because as you can see on the second line, 19, it includes the secret.

I didn't want to commit it to the repository. That's why I write to the file as a pipeline step and I have access to my secret here. There is the repository secrets. So I create this npmrc file. Install dependencies, run my tests and build the project, and then can publish, as I said, to my GitHub registry that includes my username as well.

When you run the pipeline, the output looks more or less like this. It is on line 12, you have your index.d.ts file, so the file that exports actually methods and functions that are used. But also on line 17, you have exactly the file name that we were testing locally when we were running pnpm pack method. Again, same as previously, it didn't work the first time. Didn't work the second time. When I was trying to publish to my GitHub feed, often, I was getting 404 or 405. And I figured out the way how to authenticate it, so as I was saying, .npmrc file needs to include the secret and correct registry URL. However, name of your package also needs to include your GitHub username. That was interesting learning. If you get 405, make sure that your package is named properly.

OK. So, once you publish it, your package is available on GitHub. You have info how to install it, how to add it to packet.json, you have information about the previous releases. On the right-hand side, you have readme as well, and link to repository. It's really nice, isn't it? So, as you can see here, there are different versions, recent version, there's alpha and so on. Let's talk about versioning now. So, standard for versioning is the major, minor patch format. That translates to, let's say, major one, minor three and patch is zero. So, when you will be releasing a breaking change, you want to communicate to the user that they may need to update the usage of your library, and you do it by releasing major versions. So, let's say bump the major number to two, you will have version 2.0.0. If you release this small change to your application, maybe just add additional helper function, you would just bump the minor version. So, 1.4.0. And when you work with patches, so, like the small fixes, maybe you updated readme or something like this, you would just update the patch version. However, when you work with the package, and you create the PR, you update the code, and you release this package, you would probably create just a patch update 1.3.1. And this is commonly known as the egg and chicken problem.

Because your PR might be, your pull request might be creating the breaking change for the user, or your pull request code might not be completed, might not be working as user would expect. But if they have in their package.json, version pinned this way, instead of my test helpers being pinned to version 1.3.1, they allow all versions above this version to be installed. So if you're introducing the breaking change, they would consume this code as part of installing dependencies. That's why when we work with pull releases, we would often use, we'll be adding, let's say, hyphen alpha, hyphen beta, or RC release candidate, to make sure we are not publishing real release, like the full release. And we market with either conversion is used in the project.

So you may ask, okay, so why do we even publish it if that could be breaking change? Maybe we shouldn't be publishing yet if we still work on pull request, if it's not merged. But in the same time, you want to be able to test it. You want to publish this pre-release alpha, and then you want to install it in another project. And you can use it by just adding alpha dot zero and npm install.

Another learning as part of this project was to find out that there's lots of tools that can help you with controlling versioning of your project. This can be done via package.json. There's an attribute version. This can be done by a Git version, actually a tool. This can be done by GitHub actions or maybe by the GitHub tags. There's lots of ways to do it. What I would recommend is to pick one of them and go into the documentation and figure out how to use it. I got myself confused a little on the way when I was working on it. So yeah, check documentation of the tool that you decide to use. And read me. So who is your user? Your user is another quality engineer and your user is developer. They need to know how to install your project, how to contribute to it and how to use it. So both helpers are available for them. So an example, how installation process and contribution guide. And that's all. I hope that you enjoyed this talk, that you learned something new. Maybe you will decide to take this learning away and build something for your team as well. And I hope that you will enjoy other talks at Test.js.