DEV Community: Chihab Otmani

Announcing @ngx-env/builder

Chihab Otmani — Sat, 21 Aug 2021 16:29:08 +0000

Have you ever wanted to consume variables declared in your environment inside your Angular application?

# GitHub Action command
NG_APP_GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} ng build

Environment variables can be useful for:

displaying information conditionally based on where the project is deployed
consuming data (potentially sensitive) that lives outside of version control

@ngx-env/builder

With @ngx-env/builder the environment variables will be defined for you on process.env, just like in Node.js applications.

For example, having an environment variable named NG_APP_API_BASE_URL will be exposed in your TS/JS as process.env.NG_APP_API_BASE_URL.

The environment variables are embedded during the build time.

Add @ngx-env to your CLI project

ng add @ngx-env/builder

Define Environment Variables in `.env`

NG_APP_ENABLE_ANALYTICS=false
NG_APP_VERSION=$npm_package_version

Use in TS and HTML

@Component({
  selector: "app-footer",
})
export class FooterComponent {
  version = process.env.NG_APP_VERSION;
  branch = process.env.NG_APP_BRANCH_NAME;
  token = process.env.NG_APP_GITHUB_TOKEN;
}

<!-- Same output -->
<span> {{ 'process.env.NG_APP_BRANCH_NAME' | env }} </span>
<span> {{ 'NG_APP_BRANCH_NAME' | env }} </span>
<span> {{ branch }} </span>

<!-- index.html -->
<head>
  <title>NgApp on %NG_APP_BRANCH_NAME%</title>
</head>

Run your CLI commands

npm start
# Command Line environment variable
NG_APP_BRANCH_NAME=`git branch --show-current` NG_APP_GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} npm run build

Variables defined in .env file or in the command line are injected into your Angular Application.

Build Your Own RxJS - Operators - (Part 2)

Chihab Otmani — Sun, 08 Aug 2021 08:06:40 +0000

Introduction

On the previous post of the series we built our own Observable class.

class Observable {
  private _subscribe;
  private _unsubscribe;
  private _stopped = true;
  constructor(subscribe) {
    this._subscribe = subscribe;
  }
  _stop() {
    this._stopped = true;
    setTimeout(() => {
      this._unsubscribe();
    });
  }
  subscribe(observer) {
    this._stopped = false;
    this._unsubscribe = this._subscribe({
      next: (value) => {
        if (!this._stopped) {
          observer.next(value);
        }
      },
      complete: () => {
        if (!this._stopped) {
          observer.complete();
          this._stop();
        }
      },
      error: () => {
        if (!this._stopped) {
          observer.error();
          this._stop();
        }
      },
    });
    return { unsubscribe: this._unsubscribe };
  }
}

Let's see now how to build and compose operators in RxJS.

Definition

An operator is a function that takes a source Observable as a parameter and returns a new destination Observable. It reacts on the three events from the source observable and depending on the operator logic sends specific events to the destination Observable.

Custom Operators

Let's build a custom operator that filters out odd numbers.

function even(source: Observable) {
  const destination = new Observable((observer: Observer) => {
    const subscription = source.subscribe({
      next: (value) => {
        if (value % 2 === 0) {
          observer.next(value);
        }
      },
      error: (e) => {
        observer.error(e);
      },
      complete: () => {
        observer.complete();
      },
    });
    return () => {
      subscription?.unsubscribe();
    };
  });
  return destination;
}

Let's apply the operator directly on an Observable without using the pipe function (we'll come back to this later), this is fundamental to understanding operators and how data flows from one to another.

const even$ = even(interval$);
const subscription = even$.subscribe({
  next: (event) => console.log(event),
});

// later
subscription.unsubscribe();

even$ is the inner destination Observable created and returned by the even function.
When we unsubscribe from even$, we have to unsubscribe from the source Observable, it is our responsibility to add this logic.

Configurable custom operators

Now we want to have a mulitply operator that takes the number to multiply by as a parameter. We create a higher order function that, when invoked, returns the actual operator.

function multiply(by) {
  return function (observable: Observable) {
    return new Observable((observer: Observer) => {
      const subscription = observable.subscribe({
        next: (value) => {
          observer.next(value * by);
        },
        error: (e) => {
          observer.error(e);
        },
        complete: () => {
          observer.complete();
        },
      });
      return () => {
        subscription?.unsubscribe();
      };
    });
  };
}

pipe

Let's say we want to display only the odd numbers from a interval stream that we have multiplied each value by 3.

const interval$ = interval(1000);
const intervalBy3$ = multiply(3)(interval$);
const even$ = even(intervalBy3$);
even$.subscribe({
  next: (event) => console.log(event),
});

In one line, composing the two function calls.

const even$ = even(multiply(3)(interval$));

Pipe is just a utility function that pipes functions together, it is not specific to operator functions, it can be used to compose any functions.

import { pipe } from "rxjs";

pipe(multiply(3), even)(interval$) === even(multiply(3)(interval$));

Preferably we'd want to have the pipe method in our Observable class.

import { pipe } from "rxjs";

class Observable {
  constructor(subscribe) {
    this._subscribe = subscribe;
  }
  subscribe(observer) {
    return this._subscribe(observer);
  }
  pipe(...operators) {
    return pipe(...operators)(this);
  }
}

interval$.pipe(multiply(3), even).subscribe({
  next: (event) => console.log(event),
});

At this point you should have got the whole picture, let's have some practice on the remaining operators: map, take and switchMapTo.

map

map is easy, we subscribe to the source observable and emit the values using the passed in projection function.

function map(projection) {
  return function (source) {
    return new Observable((observer) => {
      const subscription = source.subscribe({
        next: (value) => {
          observer.next(projection(value));
        },
        error: (e) => {
          observer.error(e);
        },
        complete: () => {
          observer.complete();
        },
      });
      return () => {
        subscription?.unsubscribe();
      };
    });
  };
}

take

interval$
  .pipe(
    take(5),
    map((val) => val * 2)
  )
  .subscribe({ next(value) { console.log(value), complete() => console.log('End of stream') });

In the example above we're interested only on the first 5 interval events, on the fifth event take(5):

completes the source observable (interval$)
completes the observer otherwise which also completes its observer otherwise the complete in our subscribe will never occur.

function take(maxEvents) {
  return function (source: Observable) {
    return new Observable((observer) => {
      let counter = 0;
      const subscription = source.subscribe({
        next(value) {
          observer.next(value);
          if (++counter === maxEvents) {
            subscription?.unsubscribe();
            observer.complete();
          }
        },
        error(e) {
          observer.error();
        },
        complete() {
          observer.complete();
        },
      });
      return () => {
        subscription?.unsubscribe();
      };
    });
  };
}

switchMapTo

In switchMapTo, we are interested in the source observable only to know that a new event has occurred.
Each time we receive an event from the source observable, we switch to the destination observable, the inner observable, subscribe to it, and send value to the destination Observable.

When a new event is emitted by the source observable, we unsubscribe from the internal observable and create a new subscription. This "unsubscription" is very important because in our case we do not want to have any timers still active.

If we receive an error from the source observable or the innrer observable we pass it down to the observer right away.

If we receive a completion from the source observable we wait until the active inner observable completes then we complete the observer.

function switchMapTo(destination: Observable) {
  return function (source: Observable) {
    return new Observable((observer) => {
      let innerSubscription;
      let innerCompleted = true;
      let isComplete = false;
      const checkCompletion = () =>
        isComplete && innerCompleted && observer.complete();
      const subscription = source.subscribe({
        next: (value) => {
          innerSubscription?.unsubscribe();
          innerSubscription = destination.subscribe({
            next(value) {
              observer.next(value);
            },
            error(e) {
              observer.error();
            },
            complete() {
              innerCompleted = true;
              checkCompletion();
            },
          });
        },
        error: (e) => {
          observer.error(e);
        },
        complete: () => {
          isComplete = true;
          checkCompletion();
        },
      });
      return () => {
        innerSubscription?.unsubscribe();
        subscription?.unsubscribe();
      };
    });
  };
}

Resources

Practice

You might have noticed that the timer does not start right away when you click on the button. To fix that we can use startWith operator.

It is your turn to implement it here.

Summary

Understanding the internal mechanisms of RxJS allowed us to develop robust operators. An operator can be considered as a helper function that is not really bound to a specific domain and that we can reuse in several applications.

In the next article, we will discuss Unicast and Multicast Observables.

Support

If you like the article, let me know, I hardly ever write, it will motivate me to produce more content.

Build Your Own RxJS - Observables - (Part 1)

Chihab Otmani — Sat, 07 Aug 2021 20:04:10 +0000

Introduction

One of the effective ways to better know a technology is to get an idea of the underlying implementation and ideally try to build your own.

Our journey throughout this series is to build some of the core RxJS features from scratch, namely:

The Observable class to create and subscribe to an Observable stream
Observable creation utilities like fromEvent and interval
Operators like take, map and switchMapTo
The pipe utility method which simplifies the composition of several operators applied to an Observable

Consider the code below that starts a new countdown every time the user clicks on the Reset button.

<button id="start">Start</button>
<div id="text"></div>

import { interval, fromEvent } from 'rxjs';
import { switchMapTo, map, take, startWith } from 'rxjs/operators';

const countdownElem = document.getElementById('text');

function countdown(init, delay = 1000) {
  return interval(delay).pipe(
    take(init),
    map(val => init - val - 1),
    startWith(init)
  );
}

const click$ = fromEvent(document.getElementById('start'), 'click');
const countdownFrom10$ = countdown(10);
const countdownFrom10OnClick$ = click$.pipe(switchMapTo(countdownFrom10$));

const text = document.getElementById('#text');
countdownFrom10OnClick$.subscribe({
  next: text => {
    countdownElem.innerHTML = `${text}`;
  }
});

Here is a preview of the final result.

At the end of the article, all RxJS imports can be replaced by ours for the same result.

import { interval, fromEvent } from "./rxjs-dev";
import { switchMap, map, take } from "./rxjs-dev/operators";

Creating Observables

fromEvent

Let's start with the fromEvent function.

import { fromEvent } from "rxjs";

const clicks$ = fromEvent(document, "click");
clicks$.subscribe({
  next: (event) => console.log(event.clientX, event.clientY),
});

Behind the scenes we can imagine that fromEvent uses addEventListener, let's make a first version of it.

function fromEvent(target, eventName) {
  return function (listener) {
    target.addEventListener(eventName, listener);
  };
}

const click$ = fromEvent(document, "click");
click$((event) => console.log(event.clientX, event.clientY));

Notice that fromEvent does not directly call target.addEventListener but it returns a function that calls it.

This is one of the key differences with Promises.

A Promise is eager, it is executed immediately, without the need to call the then method on it.
An Observable is lazy, it is constructed and later its logic is executed when we subscribe to it.

Let's adapt our code to get it closer to the fromEvent api:

function fromEvent(target, eventName) {
  return {
    subscribe: (observer) => {
      target.addEventListener((event) => {
        observer.next(event);
      });
    },
  };
}

const click$ = fromEvent(document, "click");
click$.subscribe({
  next: (event) => console.log(event.clientX, event.clientY),
});

We have made two updates:

fromEvent no longer returns a function but an object containing a method subscribe that calls target.addEventLister when invoked. This is the beginning of an Observable.
we replaced the listener function with an object literal having a next method. This is an Observer.

Essentially, we've just replaced callback functions with objects that have these specific contracts.

class Observable {
  subscribe: (observer: Observer) => {
    const data = []; // some logic here
    observer.next(data)
  };
}

interface Observer {
  next(event: any): void;
}

Observable

Now, rather than returning an object literal, we want to create the Observable instance from the Observable class we shaped earlier.

function fromEvent(target, eventName): Observable {
  // return {
  //   subscribe(observer: Observer) {
  //     target.addEventListener(eventName, (event) => {
  //       observer.next(event);
  //     });
  //   },
  // };
  return new Observable((observer: Observer) => {
    target.addEventListener(eventName, (event) => {
      observer.next(event);
    });
  });
}

Notice that the callback function passed to the Observable constructor is exactly the subscribe method we put in the object literal, we just need to store it for a later use; when the method subscribe is actually called.

class Observable {
  private _subscribe;
  constructor(subscribe) {
    this._subscribe = subscribe;
  }
  subscribe(observer: Observer) {
    this._subscribe(observer);
  }
}

const obs$ = new Observable((observer: Observer) => {
  observer.next('some data');
});
const anObserver: Observer = {
  next: (value) => console.log(value)
}
obs$.subscribe(anObserver);

So basically, the purpose of an Observable is to wrap our usual callbacks with specific contracts so that we can compose them and build utilities around them as we will see next.

interval

Let's create the interval utility that creates an Observable that emits sequential numbers every specified interval of time.

const interval = (period) => Observable {
  return new Observable((observer: Observer) => {
    let tick = 0;
    setInterval((event) => {
      observer.next(tick++);
    }, period);
  });
};

const interval$ = interval(1000);
interval$.subscribe({
  next: (tick) => console.log(tick),
});

Pretty straightforward, right?

unsubscribe

Unsubscribing from an observable means we're no longer interested on its future events. This is how we unsubscribe from an Observable in RxJS.

const subscription: Subscription = interval$.subscribe({
  next: console.log,
});

// Later
subscription.unsubscribe();

Unsubscribing from interval Observable means clearing the interval which has been set by setInterval earlier because we're no longer interested on its data.

const interval = (period) => {
  return new Observable((observer) => {
    let tick = 0;
    const timer = setInterval((event) => {
      observer.next(tick++);
    }, period);

    return () => {
      clearInterval(timer);
    };
  });
};

The teardown function returned on line 8 should be returned to be called using subscription.unsubscribe(). subscription.unsubscribe is our teardown function on line 8.

Let's adapt our Observable accordingly:

interface Subscription {
  unsubscribe(): void;
}

class Observable {
  private _subscribe;
  constructor(subscribe) {
    this._subscribe = subscribe;
  }
  subscribe(observer: Observer): Subscription {
    const tearDownFunction = this._subscribe(observer);
    return {
      unsubscribe: tearDownFunction
    }
  }
}

Subscribing similiraly in fromEvent:

function fromEvent(target, eventName): Observable {
  return new Observable((observer: Observer) => {
    const listener = observer.next;
    target.addEventListener(eventName, listener);
    return () => {
      target.removeListener(listener);
    };
  });
}
const subscription: Subscription = fromEvent(document, "click").subscribe({
  next: console.log,
});

// Later
subscription.unsubscribe();

Observable contract

There are three types of values an Observable Execution can deliver:

"Next" sends a value
"Error" sends an error and stops the observable
"Complete" does not send a value and stops the observable

interface Observer {
  next(data: any): void;
  complete(): void;
  error(error: any): void;
}

The Observable contract stipulates that whenever a complete or error messages are sent to the Observer, the Observable stops, wich entails the following:

The Observable unsubscribe method is called
All the future calls to the observer methods are ignored

Given the code below:

new Observable((observer: Observer) => {
  observer.next("Message 1");
  observer.error();
  observer.next("Message 2");
  observer.complete();
  return () => {
    console.log("Unsubscribed!");
  };
}).subscribe({
  next: (value) => console.log(value),
  complete: () => console.log("Complete"),
  error: () => console.log("Error"),
});

The expected output according to the Observable contract is:

Message 1
Error
Unsubscribed

whereas the current output is:

Message 1
Error
Message 2
Complete

To fix our Observable, we have to hook into the observer methods and, depending on the state of the Observable, decide whether to call its methods or not and unsubscribe in case of an error or completion.

class Observable {
  private _subscribe;
  private _unsubscribe;
  private _stopped = true;
  constructor(subscribe) {
    this._subscribe = subscribe;
  }
  _stop() {
    this._stopped = true;
    setTimeout(() => {
      this._unsubscribe();
    });
  }
  subscribe(observer) {
    this._stopped = false;
    this._unsubscribe = this._subscribe({
      next: (value) => {
        if (!this._stopped) {
          observer.next(value);
        }
      },
      complete: () => {
        if (!this._stopped) {
          observer.complete();
          this._stop();
        }
      },
      error: () => {
        if (!this._stopped) {
          observer.error();
          this._stop();
        }
      },
    });
    return { unsubscribe: this._unsubscribe };
  }
}

And that's it!

Summary

We have seen that by passing some functions around we can build a minimalist version of an RxJS Observable. It goes without saying that it is not ready for production. ☠️

Resources

Practice

You might have noticed that the timer does not start right away when you click on the button. To fix that we can replace interval with timer`.

It is your turn to implement it here.

On the next article we're going to re-implement some of the most used RxJS operators.

If you like the article, let me know, I hardly ever write, it will motivate me to produce more content.

E2E tests with Cypress - Beyond the Basics

Chihab Otmani — Sat, 01 Feb 2020 05:54:25 +0000

Cypress allows full-stack end-to-end testing with ease. The API is well documented and the core concepts are totally straightforward. Still, I've found myself having to deal with some issues and strategies that are documented here and there. This post is a summary of the most common ones.

Capture fetch requests

One of the trade-offs of Cypress is that it only captures XHRs (not fetch).

If you have a fetch request in your application (I am sure you do), no request would get captured without the workaround below.

cy
  .visit('/some-url-that-fetches-data', {
    onBeforeLoad: (win) => {
      win.fetch = null
    }
  })

Ship a fetch Polyfill

The workaround code above removes fetch from the window object in the global context of the tested application. Since you still have fetch requests present in your application code, you have to ship a polyfill in your application bundle that will detect that fetch is missing in window (because you've enforced it in your cypress test) and will mutate the global context (window) with a fetch that uses XHR call underneath. (if (!window.fetch) { window.fetch = functionThatUsesXHR; ... })

whatwg-fetch does exactly that.

React example

// index.js
require('whatwg-fetch');

Unless you'd want to run your tests against production, you wouldn't want to ship that polyfill in your production bundle. You condition that using an environment variable.

// index.js
if (process.env.REACT_APP_ENV === 'e2e') {
  require('whatwg-fetch');
}

And have a specific build that sets the variable for E2E:

  "scripts": {
    "build:e2e": "REACT_APP_ENV=e2e react-app build",
  }

Overwrite cy.visit()

To avoid adding the workaround to all your page visits, you can overwrite the visit command.

Cypress.Commands.overwrite('visit', (visit, url) => {
  return visit(url, {
    onBeforeLoad: (win) => {
      win.fetch = null
    }
  });
});

Decide your testing Strategy

When your application interacts with a backend, you have to choose one of this two strategies to deal with the outgoing requests:

Interact with the real backend
Intercept request to your real backend and return mock responses

The latter is faster, it does not need the backend to be seeded with data and it gives you full control of request and responses. However, this is not real full end-to-end testing and you're never sure if the mocks match the real backend responses.

If you go with interacting with the real backend you can use cypress tasks to seed/clean your backend data before every test.

The general rule is that result of a test should not depend on the test position in the test suite.

Authenticate using 3rd Api (Cross-origin domain)

If you use a third party authentication provider (google, auth0...) to authenticate your users then you will probably deal with the cross-origin domain issue.

Basically Cypress (because of a browser security spec) does not let you control a different origin from the one you initially cy.visit()ed.

You just can't fill google authentication form inputs with credentials and you would agree that it makes no sense to do so because you have no idea on how the provider's html is structured and how it could change over time, making your tests eventually fail.

The only solution you have is to use the provider's authentication api to authenticate your user, by making an async request to your auth provider with a server apikey for example to authenticate a specific user. You can create a specific user for that with different roles depending on what you are willing to test.

Now if your application is using a private company SSO that do does not offer an authentication API, I am very sad for you :(, you'd have to eitheir:

Disable the browser security flag so that Cypress can handle redirects.
Authenticate the user using Pupeeter for example as a task and run the test using the token received by pupeeter.

Something like:

on("task", {
    authenticate: (args) => {
      return (async () => {
        const browser = await puppeteer.launch({ headless: true })
        const page = await browser.newPage()
        await page.goto('https://<your site with login')
        // Authenticate user here
        // ...
        let cookies = await page.cookies();
        cookie = cookies.find(o => o.name === 'AUTH_COOKIE_FROM_PROVIDER')
        return cookie;
      })();
    }
  });

describe('Your test suite', () => {
  beforeEach(() => {
    cy.task("authenticate")   
    .then(cookie => {
      cy.setCookie(
          cookie.name, 
          cookie.value, 
          { domain: '<your domain>' }
      );
    });
  });
}

Run your tests in CI

The whole thing about E2E tests is that they need to run on CI (Travis, GitLab CI, CircleCI...)

Deploying the develop branch in a staging environment and then running your tests against that environment is wrong because well you've already deployed!, QA guys might do their tests on a broken environment, unless it is a temporary environment dedicated to cypress automated tests.

The pipeline workflow should be the following:

Build the application (ship the fetch polyfill)
Serve the application inside the CI (using serve, http-server...)
Run your tests against the served application (CYPRESS_baseUrl or cypress.json)

"scripts": {
  "build:e2e": "REACT_APP_ENV=e2e react-app build",
  "e2e": "CYPRESS_baseUrl=http://localhost:5000 start-server-and-test 'serve -s build' http://localhost:5000 cypress:run"
}

start-server-and-test used above is a tool that executes the command serve -s build, waits until it is ready on http://localhost:5000 then runs cypress:run which runs cypress tests against the url set to CYPRESS_baseUrl environment variable.

An (incomplete) sample of CircleCI pipeline configuration

build:
    docker:
      - image: cypress/base:10
    working_directory: ~/repo
    steps:
      - checkout
      - run: yarn install
      - run: yarn lint
      - run: yarn test
      - run: yarn build:e2e
      - run: yarn e2e

Use a robust selector

Avoid using classes or ids when targeting elements in a page because they're coupled to CSS selectors and these are traditionally used for styling and are subject to be changed at any time.

<Button label="Submit" data-cy="login-submit" />
// or
<Button label="Submit" data-testid="login-submit" />

test(() => {
  cy.get('[data-cy="login-submit"]')
    .should('have.text', 'Submit')
})

The choice of the selector name has to be thought from a user perspective rather than a styling/structuring perspecting.

With a custom command

Cypress.Commands.overwrite('get', (get, selector) => 
  return selector.startsWith('d:')
    ? get(`[data-testid="${selector.substr(2)}"]`)
    : get(selector);
);

We can use a simpler syntax

cy.get('d:submit-button').click();

Use Cypress Testing Library

If you want to stay consistent with the way you query elements in your unit tests, you can use Cypress Testing Library

cy.queryByLabelText('Submit').should('exist')

Cypress chain of commands

Cypress manages a Promise chain on our behalf. Cypress commands are asynchronous and get queued for execution at a later time. Cypress commands don’t do anything at the moment they are invoked, but rather enqueue themselves to be run later.


it('submits the form when.....', function() {
  cy.visit('/') // Nothing happens, command is chained
  cy.get('[data-cy="submit"]') // Nothing happens, command is chained
    .click()  // Nothing happens, command is chained
})

When test function has finished executing, all commands have been queed and Cypress will run them in order.

Because of that you cannot assign the commands call to a variable.

// BAD, This won't work.
it('submits the form when.....', function() {
  const button = cy.get('[data-cy="submit"]')
  button.click();
})

If you don't want to repeat yourself, use aliases.

That's all I've got!

DEV Community: Chihab Otmani

Announcing @ngx-env/builder

@ngx-env/builder

Add @ngx-env to your CLI project

Define Environment Variables in .env

Use in TS and HTML

Run your CLI commands

Links

Build Your Own RxJS - Operators - (Part 2)

Introduction

Definition

Custom Operators

Configurable custom operators

pipe

map

take

switchMapTo

Resources

Practice

Summary

Support

Build Your Own RxJS - Observables - (Part 1)

Introduction

Creating Observables

fromEvent

Observable

interval

unsubscribe

Observable contract

Summary

Resources

Practice

E2E tests with Cypress - Beyond the Basics

Capture fetch requests

Ship a fetch Polyfill

React example

Overwrite cy.visit()

Decide your testing Strategy

Authenticate using 3rd Api (Cross-origin domain)

Run your tests in CI

Use a robust selector

Use Cypress Testing Library

Cypress chain of commands

Define Environment Variables in `.env`