Forem: Renato Ruk

Benefits of using Cypress in GitHub actions

Renato Ruk — Mon, 12 Oct 2020 15:40:42 +0000

If you work with anything related to frontend and you haven’t tried Cypress yet, I highly suggest you give it a try.
But, if you use Cypress and don’t have a CI/CD pipeline set up yet, read forward for the reasons why using GitHub actions for it might be valuable.

GitHub actions

The docs say:

Automate, customize, and execute your software development workflows right in your repository with GitHub Actions.

Cypress GitHub action - installation

Read these:

Benefits of integration

Prevention of merging broken code into the target branch

by leveraging code status checks of GitHub, there is the potential to list run Cypress checks and block PR merge if all checks are not passing

Image source: cypress docs

Software stability

as the status checks prevent merging broken code, there is potentially greater awareness across the development team towards software quality and stability
another potential outcome is that the team write more (and meaningful) tests because they see how much their code and tests have an impact on the complete codebase

Tracking code coverage

although code coverage can be misused, it can be a valuable metric in determining which code flows are hit or missed
plugin: https://github.com/cypress-io/code-coverage

Easier onboarding of new developers to project standards

if a new team member has not used Cypress before, he/she will potentially see the value of tests sooner if they're visible in the CI and they're not required to be run manually

Developer’s ownership of CI/CD

In some organizations, CI/CD pipelines are the responsibility of the DevOps team
Delegating some complex pipelines or asking help from the DevOps team is great for collaboration, but it's also really valuable skill knowing setting up the basic CI/CD flows
I personally think this is really important because the developer can then tweak the CI/CD pipeline to the project's needs and potentially easily experiment with new features of relevant technologies on the projects (e.g. Cypress GitHub actions)

Summary

This post focuses (on very high level) on the integration of Cypress and GitHub actions, but can easily be applied to other testing frameworks such as Jest and other CI/CD services such as CircleCI or TravisCI.

I personally found it very convenient to use it with GitHub actions because it's baked in the GitHub itself, but you can freely use other services that support this kind of automated flows.

Happy testing!

How to start with JavaScript library development

Renato Ruk — Mon, 24 Aug 2020 15:59:29 +0000

Software development is about solving problems. Sometimes the problems are tightly coupled with the domain and other times they are generic, not related to a specific business or field.

To avoid repetition in solving problems, we as developers have the ability to abstract & extract our solutions to self-contained modules, most often called libraries or packages.

JavaScript is no exception to this, and therefore we currently have a plethora of options available.

Despite the fact that there are currently more than a million packages available on NPM, there is still potential and value in creating your own.

What makes a good library?

There are different kinds of libraries in terms of size and purpose. Whole frameworks could fall into an umbrella term of software libraries, but there are also one-liner functions wrapped in packages that are by definition, also considered libraries. Their context is often different, but some common rules can be applied to all of them.

solves a specific problem
has good documentation
easily extendable
well tested

Why even bother making a library when you can copy and paste?

Abstracting a problem has its own costs. Sometimes, making an abstraction too early or without a defined plan can lead to accidental complexity or incorrect implementation. Therefore, using good old copy and paste strategy is oftentimes preferred solution, until we know the problem deeper.

But, if the code is copied too much, it can become difficult to maintain and upgrade. The reason behind this is often because the copied code relies on repeating some patterns in a certain way and if we don't repeat the same structure, bugs can occur.

Knowing the right timing for abstraction is an art of its own, but a general rule of thumb is that a piece of code is a good candidate of abstraction after being copied for two or three times.

JavaScript library anatomy

After we've identified our candidate for abstraction, the next step is to learn about the structure of javascript libraries.

To be considered a JS package that can be published to NPM or Yarn, it should have the following set up:

valid package.json
exported JavaScript modules in one or multiple formats
- Universal Module Definition
- CommonJS
- Asynchronous Module Definition
- ES2015 Modules

This is a minimum requirement and, depending on the complexity of the software, there could be many more parts to it.

Local development

The best way to develop a library is to treat as a realm of its own, if possible. That means that it has its own testing strategy and its own system for running the project in isolation.

In scenarios when this is not possible or we just want to test our package in a real-world application before publishing it, there are ways to use them in locally.

Npm / Yarn Link
Local development can be achieved by linking our packages to a single local source stored on the disk. So, if we're using Yarn, we can use yarn link command, and for the NPM there is an equivalent command.

Yalc
Yalc is a great tool to achieve more control of local package installation and dependencies. It behaves as a local repository and simulates the behaviour of having a remote repository like npm.

Monorepo

Some libraries may be too big to be contained in a single package. Such libraries may be architected as a mono-repository, by storing multiple smaller packages in a single repository.

This can result in better control of source code and better modularity, especially if many parts of the system depend on different independent modules or consumers of the library don't need to use everything that the library contains.

An example of monorepo is babel repository that's developed with lerna.

Best practices

General software development practices can be applied to library development. Most notable elements are:

tests
- https://jestjs.io/
- https://www.cypress.io/
documentation
- https://docusaurus.io/
commitlint
(auto)changelog
semantic versioning
linting

Zero-config solutions

Setting up a JavaScript library with all the requirements mentioned can be a bit overwhelming. After the initial development of the library, it calls for maintenance of dependent packages and upgrade of features and procedures.

To simplify the package development we can use CLI-s that solve most of the common problems of the library set up so we can focus on the code itself.

Possible options:

TSDX
- Zero-config CLI for TypeScript package development
Microbundle
- Zero-configuration bundler for tiny modules

Summary

JavaScript libraries are self-contained software modules that export reusable code for usage in different projects and scenarios. We learned about some general guides which can improve the quality of packages and what are the common parts of every package. To simplify the package development, we can use zero-config CLI-s which allow us to focus on the code, but it's important to understand what these tools do for us so we can have better control and knowledge on how to fix something if it's beyond the zero-configuration method.

Happy packaging!

10 principles of scalable frontend projects

Renato Ruk — Mon, 30 Mar 2020 08:38:22 +0000

A common problem

Web apps have come a long way since their initial appearance. We all now know how powerful JavaScript on the web is, and how many endless possibilities exist in terms of framework and technology choices. Different frameworks have their pros and cons, but some core methodologies can be applied to almost every framework. Tools such as create-react-app, next.js, vue-cli, etc., are really helpful for bootstrapping a project and its structure, but after that, you're free to form an application to your preferences and project's requirements.

I've collected some principles I found valuable when building web applications with React and Vue that can help you in defining a direction and keeping things tidy and sound. Most of the principles can be applied to all software, but this list is a bit specific to web apps.

Principles

Developing components, not screens
- try to encapsulate all the logic of a component in isolation, so it can be rendered everywhere with ease, for example, in different screens and sections
- all the CRUD operations go inside the controllers / providers for the data it needs, and that data is passed to presentational components
  - one common scenario is redux/vuex - data is persisted to a store and is treated as a single source of truth, and container components extract the relevant data
Separating presentational and business / controller layer
- not all components need to be connected to stores, backend API or some other service
- by making components "data source agnostic", reusability is greatly increased
Using a standardized way of fetching the data
- rest-hooks is a great example of this principle as it encourages a predictable and readable structure for API calls
- for some projects, using explicit fetch calls may be sufficient, but if you're dealing with a lot of resources and relationships, having an abstraction over backend API can be helpful
Having a common user input strategy
- forms, select tags, validations, error states all fall into this category
- UI component libraries such as antd provide a solution for this out of the box
- if you're creating an app without a UI library, consider putting a bit more emphasis on standardizing these elements for better UX
Writing automated tests
- components are, in my experience, best tested with integration tests, specifically with Cypress
- business logic should be thoroughly covered with unit tests
- e2e are valuable for smoke testing larger user flows; they can help detect regressions between the client and the API
Using storybook for creating reusable components
- https://storybook.js.org/
- great way to collaborate with designers and discuss functionality
- serves as a "living style guide" for your app
Using linters and formatters
- examples of linters: ESLint, stylelint
- most of the bootstrap tools such as create-react-app pre-install linters for you, but if you're on a legacy codebase, they might not be applied
- they can help you catch bugs, but they can also be used in defining code style for your team — this can help in reducing mental load when developing upon a feature that you've inherited from your colleague
- sonarJS eslint plugin can help improve code quality as it checks for logical structure
- prettier is an awesome code formatter that you set up only once, and never think about it again — very useful when working in a team
Avoiding global styles
- overrides and resets can be made global
- CSS modules or CSS-in-JS are some of the technologies that can help in achieving scoped, isolated styles
- local styles can often lead to better component reusability
Using structured version control
- using a branching model
  - e.g. gitflow — "a branching model for Git, created by Vincent Driessen"
  - having a structure in your version control is indispensable for working in a team, but it is helpful even when working on your own
- linting commit messages - commitlint
  - useful in creating a changelog and finding bugs as the project develops
  - angular's commit message rules are often applicable to any software project, and commitlint can help you in keeping those messages consistent with the ruleset
Keeping a changelog
- on the beginning of every project, it's usually easy to keep track of all the changes in your mental context
- as the project grows, the changelog can serve as a central place for discovering notable changes to a codebase, even months and years into development

The never-ending list

That's all folks! There could surely be many more items added to the list, depending on the project domain and technology, but I find these can improve many frontend apps radically. Almost all of the principles can be applied progressively and by priority defined by you and your team, so no need to worry of applying them all of once.

What principles do you find super important when creating web apps? Share these below in the comments! ⬇️

Thanks for reading. 🙏

TypeScript compile-time interface validation with tagged unions

Renato Ruk — Mon, 09 Mar 2020 09:09:09 +0000

If you work with TypeScript, you probably love the static type checking it provides. It’s a very powerful programming tool that helps us detect bugs before they can even run, by showing us compile errors.

Using interfaces is by itself very effective technique for writing code that is correct by a specified contract. But, what if we have similar contracts that define some intrinsic behaviour of a class or a function and we want to combine their definitions?

Let's image we're building a table with React that shows a list of records from the backend API. The component receives columnData of type TableColumnData[] as a prop, which is an array of config objects that determine how each column should be built and how it should behave. The content of the column is specified with the dataIndex field of the interface, which renders the value of matching key from each record passed to the table. As the data is passed from the backend API, it can have thousands of records, therefore we need to add the ability to search only the ones we need.

We can then add a filter property on the column that will, if not left empty, render a text input in our column header. By submitting the search, the table will do a request on the API with the new value of the specified field.

The overly simplified version of the TableColumnData interface could look like this:

export interface TableColumnData {
    dataIndex: string;
    title: string;
    filter?: TableColumnFilter;
}

and the interface for the filter can be specified like this:

export interface TableColumnFilter {
    field: string;
}

Finally, table should be used similarly to this (pseudo-react-code):

const MyTable: React.FC = (props) => {
    const columnData = [
        {
            title: "name",
            dataIndex: "name",
            filter: {
                field: "name",
            },
        },
        {
            title: "birthday",
            dataIndex: "birthday",
        },
    ];

    return <ResourceTable {...props} columnData={columnData} />;
}

The filtering made the user experience of our table richer, but what if we want to add new types of filters, such as, for example, date filter?

We can create another interface for that filter type, rename the TableColumnFilter to TableColumnTextFilter and combine the two filter types together in a union.

export interface TableColumnDateFilter {
    field: string;
    showHours: boolean;
}

Now, TableColumnFilter can be defined like this:

export type TableColumnFilter = TableColumnTextFilter | TableColumnDateFilter;

Our table still works, but now there is no way of knowing we used the proper interface for the filter type.

const MyTable: React.FC = (props) => {
    const columnData = [
        {
            title: "name",
            dataIndex: "name",
            filter: {
                field: "name",
                // does not make much sense
                showHours: true,
            },
        },
        {
            title: "birthday",
            dataIndex: "birthday",
            filter: {
                field: "birthday",
            },
        },
    ];

    return <ResourceTable {...props} columnData={columnData} />;
}

We can then narrow the types further by creating an enum. That enum will tell the TypeScript compiler which filter type is used, and therefore it will hint us what the rest of the interface should look like.

export enum ColumnFilterType {
    Text = "text",
    Date = "date",
}

export interface TableColumnTextFilter {
    type: ColumnFilterType.Text;
    field: string;
}


export interface TableColumnDateFilter {
    type: ColumnFilterType.Date;
    field: string;
    showHours: boolean;
}

This pattern is called discriminated union, aka tagged union or algebraic data type.

In our scenario, the discriminant is the type field, which will be used to differentiate the types.

Now, expanding our table example with the type field, we get a compile error when using enums.

const MyTable: React.FC = (props) => {
    const columnData = [
        {
            title: "name",
            dataIndex: "name",
            filter: {
                field: "name",
                showHours: true,
                type: ColumnFilterType.Text,
            },
        },
        {
            title: "birthday",
            dataIndex: "birthday",
            filter: {
                field: "birthday",
                type: ColumnFilterType.Date,
            },
        },
    ];

    return <ResourceTable {...props} columnData={columnData} />;
}

The error is Type 'ColumnFilterType' is not assignable to type 'ColumnFilterType.Date'. This is expected as TypeScript thinks we use ColumnFilterType as a value for the type field.

We can prevent this by using const assertion and prevent further type widening.

const MyTable: React.FC = (props) => {
    const columnData = [
        {
            title: "name",
            dataIndex: "name",
            filter: {
                field: "name",
                type: ColumnFilterType.Text as const,
            },
        },
        {
            title: "birthday",
            dataIndex: "birthday",
            filter: {
                field: "birthday",
                type: ColumnFilterType.Date as const,
                showHours: true,
            },
        },
    ];

    return <ResourceTable {...props} columnData={columnData} />;
}

Now, using the interface incorrectly will result in a compile error, which may help you prevent runtime errors if that internal behaviour is determined by a correct interface. To me, this ability to have pre-compile validation of implementation is what makes typed languages really stand out. They are especially helpful in collaboration and refactoring.

Have you had a chance to used tagged unions before? Do you have a TypeScript feature that you could not live without? Share those in the comments below! ✌🏻

Configuring Cypress for multiple testing environments

Renato Ruk — Mon, 17 Feb 2020 08:18:35 +0000

Cypress is a great tool for front-end testing. It provides features such as mocking HTTP responses, stubbing objects and methods and simulating user interaction.

It can be used as a fully-fledged front-end testing framework for unit, integration and e2e tests. This post assumes you are already somewhat familiar with Cypress and its methodologies, and it serves as a guide for advanced configuration which can help you structure and organize your tests. So, let's get straight to the point.

When first installing and running Cypress with npm or yarn, it will generate some default tests and configuration for you.

At the time of writing, these files and directories are:

// configuration
./cypress.json 

// directories with respective files / tests
./cypress/fixtures/ 
./cypress/integration/examples/
./cypress/plugins/
./cypress/support/

The default command for running Cypress in interactive mode is ./node_modules/.bin/cypress open and it will by default use cypress.json as a configuration file.

An example of a configuration file:

{
    "baseUrl": "http://localhost:3000",
    "integrationFolder": "cypress/integration",
}

Cypress will also by default run all tests from the integration directory, supporting nested directories. We could add all our unit, integration and e2e tests to the integration directory, but we want to configure some things differently, depending on our environment. For example, we could avoid some API calls from the app by completely blocking the host from the configuration file.

Let's say we want to mock the response for the foo resource from our API. In our Cypress test, we'll do something like this:

describe("foo", () => {
    it("should fetch and render foo", () => {
      cy.server();
      // load fixture and mock response
      cy.fixture("foo").then((response) => {
        cy.route({
          method: "GET",
          // you can also setup base url in cypress config
          // it can be used as Cypress.env('BASE_API_URL')
          url: "https://api.my-app.com/foo/**",
          response: response,
        });
     });
     // ...rest of the test
}));

By specifying the same host of our backend API in blacklistHosts, Cypress will allow creating mock responses for the blocked domain, but it will intercept and disallow any other response to that same domain. This could be a handy setup for integration testing, where you want to test a feature in a very specific scenario, mocking all the requests and data the application needs. This is a powerful configuration, but for e2e tests, we don't want to block the real API because we need to test front-end with the real back-end services. Therefore, we need to split our configs.

We'll first create a cypress-integration.json file and place it inside auto-generated cypress directory. Then, we specify another path for the location of the tests. For our use-case, that is cypress/tests/integration. Notice the change from integration to tests naming. The naming is not needed to be replicated; feel free to use directory names which suit you and your team.

Example cypress-integration.json file:

{
    "baseUrl": "http://localhost:3000",
    "integrationFolder": "cypress/tests/integration",
    "blacklistHosts": ["api.my-app.com"]
}

Now, to run only those tests suites for integration tests, we need to add commands in our package.json. "cypress:open:integration" is for "interactive" mode, and cypress:run:integration is for running in "CI" mode.

{
 "scripts": {
   "cypress:open:integration": "cypress open --config-file cypress/cypress-integration.json",
   "cypress:run:integration": "cypress run --config-file cypress/cypress-integration.json"
 }
}

Now, you can repeat this process for other environments, such as e2e, storybook or unit tests, and provide different configurations for them. 🚀

Thank you for reading! 🙏