Ramona-Schwering_square

Ramona, a Developer Advocate at Auth0, bridges roles as a tester and developer. She's a Google Dev Expert in Web Tech, Women Techmaker Ambassador, and Cypress Ambassador, building trust in test automation and identity topics.

Developer Advocate

Ramona Schwering

Many applications utilize Auth0 in their login procedures. However, how do you deal with that in testing? Let's learn how to cover the default login process in test automation with Cypress.

In this post, you’ll explore leveraging the Cypress testing framework to enhance security and user experience. This article is the first post of a series, which will closely examine one of the most crucial aspects: the login form and the standard login procedure.

## Why Do We Need to Mind Auth0 in Testing?

You might wonder why you should write login tests. After all, you log in to your application daily. In addition, evem more significant, Auth0's Univeral Login, thus its Login form, is already tested by the responsible teams, right? 

Well, while that's true, it's important to mind the Auth0 integration inside your application - so you're confident it's working with your application's code flawlessly. Moreover, testing the login functionality is crucial for quality assurance due to its frequent use and the significant damage that login failures can cause. Everything protected behind the login needs to be covered by tests, too. And to reach those parts of your application, you need to get through authentication via your tests as well. 

> Disclaimer: When testing Auth0’s functionality and running automated tests in a pipeline, be aware that you might use actual users, affecting your plan’s [monthly active users (MAUs)](https://community.auth0.com/t/understanding-monthly-active-users/116379). This fact is particularly relevant when registering users via automated tests. Use one dedicated test user to avoid creating too many test users and consuming your plan’s capacity.

### API Testing and Password Grant 

So, we agree that we need a solution to test the login—or at least to have a command to log in to test the behavior of your application afterward. You can imagine that this process of logging in is something you’ll do a lot when writing tests for your application, correct? In the usual case, I’d recommend including repetitive steps, such as logging in inside a [custom command](https://docs.cypress.io/api/cypress-api/custom-commands) and avoiding clicking through it, to save time. Cypress advocated for it as well. As a result, in such cases, I’d normally advocate **logging in via API and avoiding using UI through such shortcuts**. An excellent example of this approach is provided by [Cypress itself](https://docs.cypress.io/guides/end-to-end-testing/auth0-authentication#Programmatic-Login). 

However, this recommendation would require using the Password grant, which is no longer defined as OAuth 2.1, as OAuth discourages its use. These changes have significant implications for API testing, as it may no longer be a practical approach. Despite the potential time investment, we are advised to use the UI method, as we aim to avoid endorsing practices disapproved by OAuth.

## Setting Up Your Example Project

For this blog post, you'll use Cypress as the framework for your examples because it offers a robust, user-friendly solution for end-to-end testing. With its real-time reloading, detailed error messages, and intuitive API, Cypress simplifies the process of writing and running tests. Its ability to operate directly in the browser provides a clear view of how your application behaves in real-world scenarios, making it an excellent choice for ensuring your login functionality is reliable and secure. One critical approach is guiding Cypress through login forms, which is the typical method for testing this crucial feature. Fortunately, Cypress provides built-in support for handling such tests, making the process straightforward and efficient.

To help test login functionality, I recommend using a GitHub repository that hosts a clean Cypress project on the main branch. I prepared a [sample repository](https://github.com/oktadev/auth0-cypress-sample) for this blog post, which you can use for reference. 

This project is built using Cypress Version 13, ensuring you have access to the latest features and improvements. You can set up the project by cloning the repository and following the setup instructions provided, making it easy to get started with your login testing.

### Choosing a Test Base

To write a test, you naturally need some test base—something to write a test against. For this blog post, I decided to use the demo app for our virtual developer day event—[dev_day](https://developerday.com/). It took place on September 24 and offered a variety of talks, games, and other sessions, especially [labs](https://developerday.com/events/devday24/labs). Those labs are a workshop-like format, actually a guided experience to teach you Auth0's features. 

![Dev_day Demo App](https://images.ctfassets.net/23aumh6u8s0i/5uKOqkX3aDOvdODdNxMkqQ/758129b7f53b3235d9676d20b4e33bdb/Dev_day_Demo_App.png)

For those labs, we provide a Demo App showcasing all its features, which makes it perfect as a test base for our blog post.

<div className="alert alert-info alert-icon">
  <i className="icon-budicon-487"></i>
  <strong>Our Demo App's Tech Stack:</strong><br> 
The Demo app, built in React, uses NextJS to power  Frontend and Backend. The application is kept as simple as possible, e.g., by running a database based on JSON files. Of course we'll use Auth0 inside this application, together with [OpenFGA](https://openfga.dev/) <br> 
</div>

## The Standard Way of Testing Login UI

When it comes to testing your login processes, whether you’re using Auth0 or not, what comes to mind? It’s probably filling out a login form and submitting it, as this is how you’re used to login and, thus, testing it manually while coding. It might not be the most efficient way of automated testing, but let’s use it as our first example. Spoiler alert: there will be a more efficient way, but it’s essential to understand the gist of it. 

As a result, before diving into a "default" login test, let's define what we mean by "default." The typical login process consists of a form containing two input fields: an email address or username and a password. These credentials are single-factor authentication. They are sent to the server for verification; the user is granted access if successful. This is what we consider the "default" login. In testing, the user is replaced by a computer in a typical end-to-end test that clicks through a login form as a human would.

<div className="alert alert-info alert-icon">
  <i className="icon-budicon-487"></i>
  <strong>Hint:</strong><br> 
When covering a login form with tests and running them in a pipeline, know rate limits to avoid triggering them and hindering your testing efforts. Mocking responses or increasing the delay between login attempts can help circumvent this issue.<br> 
</div>

Let's start writing the test! Like any Cypress test, you'll begin with a basic test skeleton as a foundation. The following code snippet defines a test suite using Cypress to verify your application's default login flow.

```javascript
describe('Default Login Flow', () => {
    it('logs in', () => {
        cy.visit('/');
        cy.contains('Log in').click();
        cy.get('input#username').type(username);
    })
})
```

This snippet outlines a basic login flow test, ensuring the login button can be clicked and the username can be entered into the appropriate field. However, this marked line won’t work because Auth0 changes to a new domain, requiring [multi-domain testing](https://www.cypress.io/blog/cypress-9-6-0-easily-test-multi-domain-workflows-with-cy-origin) for Cypress to proceed. This kind of testing allows you to handle authentication flows that span multiple domains, which is helpful for modern web applications with third-party authentication providers.

First, set environment variables to work with Auth0’s credentials more comfortably. For this, we’ll use [dotenv](https://www.npmjs.com/package/dotenv): Install `dotenv`, and create a `.env` file in your root folder, as follows:

```
AUTH0_USERNAME=exampleusername
AUTH0_PASSWORD=examplepassword
DOMAIN=exampledomain
CLIENT_ID=examplecliendid
```

Then, you can use your environment variables and set them in `cypress.config.ts` as follows:

```javascript
import { defineConfig } from 'cypress';
import dotenv from "dotenv";

dotenv.config({ path: `.env.local` });

export default defineConfig({
    env: {
        auth0_username: process.env.AUTH0_USERNAME,
        auth0_password: process.env.AUTH0_PASSWORD,
        auth0_domain: process.env.DOMAIN,
        auth0_client_id: process.env.CLIENT_ID,
    },
    e2e: {
        // other configurations
    }
});
```

After these steps, you’re ready to start! As login steps are probably used in multiple tests, using Custom Commands to avoid duplication and keep code clean is a good practice. Create the custom command as follows:

```javascript
Cypress.Commands.add('loginToAuth0', (username, password) => {
    cy.origin(
        Cypress.env('auth0_domain'),
        { args: { username, password } },
        ({ username, password }) => {
            cy.get('input#username').type(username);
            cy.get('input#password').type(password, { log: false });
            cy.contains('button[value=default]', 'Continue').click();
        }
    );
    cy.url().should('contain', Cypress.config('baseUrl'));
});
```

Next, you'll write the custom command - where the magic's happening. 🪄 Therefore, go to `cypress/support/e2e.ts`. In it, let's create the following command stub:

```javascript
Cypress.Commands.add('loginToAuth0', (username: string, password: string) => {
  // Your custom command's steps go here...
})
```

The `cy.origin` command is used for [multi-domain testing](https://docs.cypress.io/api/commands/origin). This command will enable Cypress to handle the switch to the domain handling the login, even if it's the default Auth0 one. Let's include it inside your custom command:

```javascript
Cypress.Commands.add('loginToAuth0', (username: string, password: string) => {
  // Origin for Multidomain
  cy.origin(
    Cypress.env('auth0_domain'),
    { args: { username, password } },
    ({ username, password }) => {
      // There goes the login part
    }
  );

  cy.url().should('contain', Cypress.config('baseUrl'));
})
```

This way, we can treat the login page like our own domain - so we can make Cypress interact with it as we're used to. So finally, let's continue with our login steps we tried before:

```javascript
Cypress.Commands.add('loginToAuth0', (username: string, password: string) => {
  // Origin for Multidomain
  cy.origin(
    Cypress.env('auth0_domain'),
    { args: { username, password } },
    ({ username, password }) => {
      cy.get('input#username').type(username);
      cy.get('input#password').type(password, { log: false });
      cy.contains('button[value=default]', 'Continue').click();
    }
  );

  cy.url().should('contain', Cypress.config('baseUrl'));
})
```

Returning to your test file, use the new custom command and add assertions to check if the test logs in correctly. Here’s an example:

```javascript
describe('Default Login Flow', () => {
    it('logs in', () => {
        cy.visit('/');

        // Make sure the Login button is completely rendered and visible before interacting
        cy.get('.bg-secondary').should('be.visible');
        cy.get('.bg-secondary').click();

        cy.loginToAuth0(
            Cypress.env('auth0_username'),
            Cypress.env('auth0_password')
        );

        // Validate if the user is completely logged in
        cy.get('[href="/my-courses"]').should('be.visible');
        cy.get('.aspect-square').should('be.visible');
    });
});
```

Did you notice? I added some more assertions to make the test more stable. I'll assert on things a real user would pay attention to:
* You make sure the Login button is wholly rendered and visible before interacting to avoid flakiness
* At the end of the test, you assert two elements that are only visible if you're logged in.

Now, let's run our test and see if it's passing. 🥁

![Test is passing](https://images.ctfassets.net/23aumh6u8s0i/43XLZDtl4CX61ew9YZFdLI/21a78acffd2af12a9444dcb89bae9045/Test_is_passing.png)

That’s it! You've written a multi-domain test covering a default login process with Auth0. 🚀

### Common Issue: Hydration Errors in Cypress

As of September 2024, there's still an open [GitHub issue](https://github.com/cypress-io/cypress/issues/27204) on an error I encountered myself when working with Cypress and our dev_day Demo App:

```bash
(uncaught exception)Error: Hydration failed because the initial UI does not match what was rendered on the server. See more info here: https://nextjs.org/docs/messages/react-hydration-error.

(uncaught exception)Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
```

This error is thus a known issue in Cypress, and we'll adjust the test to include a workaround to execute our test. It's partly based on [this response](https://github.com/cypress-io/cypress/issues/27204#issuecomment-1894217901), providing a test-wise workaround. You start by adding the following code snippet to your `cypress/support/e2e.ts` file:

```javascript
Cypress.on("uncaught:exception", (err) => {
  if (
    /hydrat/i.test(err.message) ||
    /Minified React error #418/.test(err.message) ||
    /Minified React error #423/.test(err.message)
  ) {
    return false;
  }
});
```
<div className="alert alert-danger alert-icon">
  <i className="icon-budicon-487"></i>
  <strong>Hint:</strong><br> 
It's important to mention again that it's a workaround and not an ideal one, as it conceals an error message completely - thus, it could also hide valid errors. As soon as the issue is fixed, it's highly recommended that this workaround be removed.<br> 
</div>

After applying the snippet to `cypress/support/e2e.ts`, there are still some edits we need to do in our test itself: 
We need to wait for the error to be present. This way, we time the test execution just right to have the click on the right time, targeting this error.

> (uncaught exception)Error: Hydration failed because the initial UI does not match what was rendered on the server.

To get the timing right, you can intercept the error's request and wait for it just before you click "Log In": 

```javascript
    it('logs in', () => {
      cy.intercept('/oauth/token').as('token');

      // Intercept the error message's request
      cy.intercept('/__nextjs_original-stack-frame?*').as('nextjs');
    
      cy.visit('/');

      // Wait for the error message to pop up
      cy.wait('@nextjs').its('response.statusCode').should('equal', 200);

      // Proceed with your test...
    });
```

## Some Words on Mocking

So, is there only the possibility of using UI-based end-to-end (e2e) tests, you might wonder? This does look very bleak, doesn't it? You could look at another alternative when working with third-party dependencies inside your test, including Auth0. Right, I'm talking about mocking.

Mocking in e2e tests is a practice that isolates the system under test from external dependencies. It ensures your tests run reliably, quickly, and independently of external services. However, it has a significant downside: Overuse of mocks in e2e tests could defeat the purpose of end-to-end verification by not truly reflecting real-world scenarios. Because of that, a balanced approach is vital. You need to weigh those options accordingly; it always depends on your project to decide if mocking is okay. I might answer this question in a later article regarding mocking Auth0.

## Recap

That's it. You wrote a test on Auth0's login form and workflow. Well, to be more precise, you've learned...
* ... why it's essential to consider your login inside your test, even if covered by a third party like Auth0 or you'll use it all the time
* ... About the discouragement of using password grants and the implications on API testing
* ... what Multi-Domain Testing is and how to utilize it to get through Auth0's login workflow 
* How to deal with Hydration issues inside your Cypress test in case they arise

Thanks for reading, and may your tests always stay green. 💚

How to Cover Auth0’s Login Form with Tests

sam-yapkowitz

I began my career in enterprise software development and got exposure to lots of different frameworks and methodologies. I quickly realized my passion was in the architecture and design of solutions to unique problems. I now get to use these skills to help my customers build high-quality experiences using Okta. When not at work you can find me on the golf course, playing Rocket League or watching football with my friends.

Specialist Solutions Engineer

Sam Yapkowitz

Learn how to perform A/B testing on the Universal Login page using Liquid templates and custom parameters.

There is no way to natively A/B test the Universal Login as of today. But, it can be achieved with the use of the [Liquid](https://shopify.github.io/liquid/basics/introduction/) templates that power the Universal Login, custom parameters passed from the client side, and an A/B testing platform such as [Split.io](http://split.io/), [Google Optimize](https://marketingplatform.google.com/about/optimize/), or [LaunchDarkly](https://launchdarkly.com/).  A/B testing, also known as split testing, refers to a randomized experimentation process wherein two or more versions of a variable (web page, page element, etc.) are shown to different segments of website visitors at the same time to determine which version leaves the maximum impact and drives business metrics.

## What Is the Universal Login?

Auth0 Universal Login (UL) defines your login flow, which is the key feature of an authorization server. Whenever a user needs to prove their identity, your applications redirect to Universal Login, and then Auth0 will do what is needed to guarantee the user's identity.

When using Universal Login, you don't have to do any integration work to handle different methods of authentication. You can start off using a simple username and password, and then add other features, such as social login and multi-factor authentication (MFA).

Configuring Universal Login is dynamic (and does not require application-level changes) because all functionality is driven by the web pages served by the centralized Authentication Server. Your applications benefit from any improvements Auth0 makes in the login flow without the need for you to change your code.

You can create a consistent, branded login experience by customizing the login page appearance and behavior from the Auth0 Dashboard. For advanced use cases, you can even change the code of each page.

To learn more about the differences between Universal Login and embedded login, read [Centralized Universal Login vs. Embedded Login](https://auth0.com/docs/authenticate/login/universal-vs-embedded-login).

## Universal Login Liquid Templates

The UL can be modified through the use of Liquid [templates](https://auth0.com/docs/customize/universal-login-pages/universal-login-page-templates).  To work with these Liquid templates, you will need to configure a [Custom Domain](https://auth0.com/docs/customize/custom-domains). These templates allow you to define the HTML, CSS, and JS that are shipped to the client when making an `authorize` request. These Liquid templates allow you to run conditional logic based on the Liquid syntax. This functionality allows you to provide a unique UX based on things such as application, organization, tenant, locale, and specific screen. There is the ability to pass specific query parameters during an `authorize` request that can be accessed inside the Liquid template syntax for even further customization options. These parameters must be prefixed with `ext-` to be honored by the UL. These can be accessed through `transaction.params.ext-{param}`. With these parameters, we can now specify different versions of the UL to render for a user. Here is a Liquid template example of conditionally branding the UL based on one of the custom query parameters. This example leverages the param `ext-alt-brand`:

```html
<!DOCTYPE html>
<html lang="{{locale}}">

  <head>
    <title>Welcome to {{ application.name }} </title>
    {%- auth0:head -%}
    <style>
      {% if transaction.params.ext-alt-brand == "portal_0" %}
      body {
        background-image: radial-gradient(blue, rgb(200, 200, 200));
      }
      #custom-prompt-logo {
        background-image: url('https://banner2.cleanpng.com/20180328/roq/kisspng-circle-logo-symbol-font-templates-5abbf957bfda53.1977074015222685037859.jpg');
      }
      {% elsif transaction.params.ext-alt-brand == "portal_1" %}
      body {
        background-image: url("https://images.unsplash.com/photo-1592450865877-e3a318ec3522?ixlib=rb-1.2.1&auto=format&fit=crop&w=2255&q=80");
        background-size: cover;
        background-position: center;
        background-repeat: no-repeat;
      }
      #custom-prompt-logo {
      background-image: url('https://bootstraplogos.com/wp-content/uploads/edd/2017/11/logo-51.png');
      }
      .prompt-wrapper {
        position: relative;
        display: flex;
        align-items: center;
        width: 480px;
        height: 100%;
        justify-content: center;
        background-color: rgb(247, 198, 233);
      }
      {% else %}
      body {
        background: linear-gradient(-45deg, #ff44dd, #3885ff, #3ec6eb, #1bc99f);
        background-size: 100% 100%;
      }
      #custom-prompt-logo {
        background-image: url('https://cdn.auth0.com/blog/auth0rta/theme/logos/auth0-logo-black.png');
      }
      {% endif %}
      {% if organization != null && organization != undefined %}
        #custom-prompt-logo {
            background-image: url({{ organization.metadata.logo_url }});
        }
        body {
            background: linear-gradient({{ organization.metadata.linear_gradient }})
        }
      {% endif %}

  </style>
  </head>
  <body class="_widget-auto-layout _use-custom-prompt-logo">
      <div class="prompt-wrapper">
        {%- auth0:widget -%}
      </div>
  </body>
</html>
```

When the value of the param `ext-alt-brand` is `portal_0`, the following version of the login page (say, version A) will be shown:

![Universal Login test page version A](https://images.ctfassets.net/23aumh6u8s0i/HaEPIJiEdF8m9l9XI96i2/a2b427c463052ef25e8e1395d83497ab/universal-login-test-a.png)

When the value of the param `ext-alt-brand` is `portal_1`, version B of the login page is shown:

![Universal Login test page version B](https://images.ctfassets.net/23aumh6u8s0i/5hWtq9COZWNfSAXgvzwB4r/ad29b45a10bd7d3f3843f87c8c93eeba/universal-login-test-b.png)

> Note: You can see the domain and application are the same, yet we have a unique UX for an A/B test.

## Client-Side Implementation

There are many ways to accomplish an A/B test with the Universal Login now that we understand how to render separate versions of the UX. A traditional A/B test will have equal weights between all of the options, and upon a user entering one of these flows, the first step would be to check the browser for a cookie indicating whether a particular user has entered into the experiment already.

If the user is new, they will be assigned one of the pathways for the experiment and then be delivered the content for the item. If a user has previously entered the experiment, we can examine their cookie to determine which pathway they belong to and continue delivering them that same content to provide a consistent UX for the lifetime of the experiment.

This can be implemented manually, but many providers offer this service OOTB, such as Split and LaunchDarkly, to help you make this piece more flexible as you run more experiments or implement feature flagging from a deployment perspective. For this writeup, I have built out examples leveraging both Split and Google Optimize.

To put the final piece in place, my application is built with Next.JS and deployed on Vercel to take advantage of their [Edge Middleware](https://vercel.com/docs/concepts/functions/edge-middleware) capability. This piece is purely preference, and is very dependent on your current implementation of CIC. The Edge Middleware functionality on Vercel allows you to intercept requests on the edge and rewrite URLs extremely quickly. This allows you to decouple the A/B test from your client-side authentication logic. For instance, any place in my application can continue to leverage the same login route without needing more logic to be added. The Edge Middleware then interfaces with my A/B provider to read/write cookies as well as modify the login route to supply the proper parameter during the `authorize` request. You can view the source code for the [Google Optimize](https://github.com/samyap4/auth0-ab-testing-optimize) example and the [Split](https://github.com/samyap4/auth0-ab-testing-split) example on my GitHub.

## Live Examples

Here are snippets of the live examples in action on [Split](https://auth0-ab-testing-split.vercel.app/). The cookie being set here is called `flag-universal_login`. This is version A in action:

<AmpContent>
<amp-youtube
    data-videoid="dnjnnIVDp-Q"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>

<NonAmpContent>
<div
  class='embed-container'
  style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;">
    <iframe
      style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
      src='https://www.youtube.com/embed/dnjnnIVDp-Q'
      frameborder='0' allowfullscreen>
    </iframe>
</div>
</NonAmpContent>

Here is version B in action:

<AmpContent>
<amp-youtube
    data-videoid="zgj5SpiRuVo"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>

<NonAmpContent>
<div
  class='embed-container'
  style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;">
    <iframe
      style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
      src='https://www.youtube.com/embed/zgj5SpiRuVo'
      frameborder='0' allowfullscreen>
    </iframe>
</div>
</NonAmpContent>

You can see the application is the same, and I can generate a different UX based on the cookie being set by my [Split.io](http://split.io/) configuration.

## Implementing Analytics

Now that we have demonstrated how to deliver different experiences to different users, the final step of the A/B testing journey will be to start gathering metrics about how users are interacting with your content. We already discussed that we can leverage the templates to bring in custom scripts to your Universal Login screens. You can use whatever service you like for tag management, such as [Google Tag Manager](https://marketingplatform.google.com/about/tag-manager/).

## Conclusion

At Auth0, we aim to provide a high-quality service and developer experience for our customers. The first interaction with your customers is often times a login screen, so we understand how important it is for the user experience to be top-notch. With our hosted Universal Login, we take away the burden of deploying and maintaining these highly secure workflows. With the capabilities of our templates outlined in this post, we are able to help your teams iterate more quickly and customize the experience to be sticky for your brand and ultimately help your business grow.


Universal Login A/B Testing

square-2

I develop software for a living, and then I go home and continue thinking about software because I just can’t get enough. I’m a full-stack engineer with infrastructure skills. I’ve led multiple agile delivery teams, being an individual contributor, driving architecture topics, and coaching and supporting other team members.<br>
I believe in high-quality software and advocate for Continuous Delivery, Test-Driven Development, and quick iteration. I <a href="https://hceris.com/blog">write</a> and <a href="https://hceris.com/talks">speak</a> about my experience regularly. Needless to say, all the opinions expressed in this blog are mine and only mine.

Staff Engineer

Mario Fernandez

carla_urrea

I've been working as a software engineer since 2014, particularly as a backend engineer and doing system design. I consider myself a language-agnostic developer but if I had to choose, I like to work with Ruby and Python.  

After realizing how fun it was to create content and share experiences with the developer community I made the switch to Developer Advocacy. I like to learn and work with new technologies. 

When I'm not coding or creating content you could probably find me going on a bike ride, hiking, or just hanging out with my dog, Dasha. 

Senior Developer Advocate

Carla Urrea Stabile

Learn how to secure a Rails API with Auth0 by letting you drive by tests.

How to Add Authorization to a Rails API Following TDD

I stream, blog, and make youtube videos about tech stuff. I love coding, I love AI, and I love building stuff!

Staff Developer Advocate

Juan Cruz Martinez

This tutorial will guide you in building a React application protected by Auth0 following a tests-first approach.

Testing your React application is important to ensure your code works as intended. But what if you're using Auth0 to protect your application?

In this blog post, you'll learn to follow TDD (Test-Driven Development) to protect a React application with Auth0. We'll go over what you need to do to set up your tests and provide some tips on how to get the most out of them.

So if you're ready to learn how to unit test your Auth0-protected React app, read on!

## Why Should You Use Auth0 to Protect Your React Application?

Auth0 is an identity and access management service that helps you protect your application by providing user authentication, authorization, and security.

Auth0 eliminates needing to be an expert on identity protocols such as [OAuth 2.0](https://auth0.com/docs/protocols/protocol-oauth2) or [OpenID Connect](https://auth0.com/docs/protocols/openid-connect-protocol) and helps you secure your web application stack. With Auth0, integrating authentication and authorization with your app is a breeze - users are redirected to a [customizable login page](https://auth0.com/docs/authenticate/login/auth0-universal-login) when they want to log in. Once successful authentication occurs, [JWTs](https://auth0.com/docs/tokens/concepts/jwts) containing user information is sent back for verification.

Since Auth0 handles all of the authentication and authorization processes on the back end, you don't have to worry about coding your own login system. This makes it much easier to unit test your protected application as well.

## Bootstrap a React Application

Before the actual testing, you'll need to bootstrap a React application. To do this, you'll use Create React App. This tool is great for quickly getting a React development environment up and running.

To get started, open a terminal window and run:

```bash
npx create-react-app react-auth0-tdd
```

While NPM does its thing, you can start with the next step.

## Connect React with Auth0

The best part of using Auth0  is the ease of use. All you have to do to secure your application is follow these steps:

### Sign up and create an Auth0 application

If you haven't already, <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free Auth0 account</a>.

A free account offers you the following:

- 7,000 free active users and unlimited logins.
- [Auth0 Universal Login](https://auth0.com/universal-login) for Web, iOS & Android.
- Up to 2 [social identity providers](https://auth0.com/docs/identityproviders) like Google, GitHub, and Twitter.
- Unlimited [Serverless Rules](https://auth0.com/docs/rules/current) to customize and extend Auth0's capabilities.

During the sign-up process, you create something called an [Auth0 Tenant](https://auth0.com/docs/getting-started/the-basics#account-and-tenants), an isolated environment representing the product or service to which you are adding authentication.

After that, you need to create an Auth0 application.

Go to the Applications tab in your [Auth0 Management Dashboard](https://manage.auth0.com/) and click the "Create Application" button. Select "Single Page Web Applications" as the type of application you want to create.

### Configure your application

Once you create the application, go to its Settings tab. You'll need to configure three URLs in there:

- **Allowed Callback URLs**: The URL of your React app that users will be sent after they authenticate. This is typically `http://localhost:3000/` for local development. 
- **Allowed Logout URLs**: The URL where users will be redirected after they log out. This is usually `http://localhost:3000` for local development.
- **Allowed Web Origins**:  If you don't register your application URL in this field, your application will be unable to silently refresh the authentication tokens, and your users will be logged out the next time they visit the application or refresh the page. For development, you'd typically add `http://localhost:3000`

Once you save these settings, you can move on to the next step.

### Install the Auth0 React SDK

Now, we're ready to install the Auth0 React SDK. To do this, open a terminal window, navigate to your project directory, and run:

```bash
npm install @auth0/auth0-react
``` 

Now you're all set to start writing your application's code and tests.

## Using TDD to Build Your Application

Test-driven development (TDD) is a powerful and popular methodology for building software. It's based on the idea that you should write tests first, then write code to ensure those tests pass. This process helps developers create better code by designing test cases up front and streamlining the coding process.

In this section, you'll use TDD to build a simple application that uses Auth0 to authenticate and display information about a user.

You'll start by checking the UI renders a "Log In" button, so head to your `App.test.js` file and replace it with the following code:

```javascript
// src/App.test.js

import { render, screen } from '@testing-library/react';
import App from './App';

test('When the app starts it renders a log in button', () => {
  render(<App />);
  const loginElement = screen.getByText("Log In");
  expect(loginElement).toBeInTheDocument();
});
```

Next, you'll run the tests using the following command:

```bash
npm run test
```

And it should be no surprise if the test fails; after all, you haven't implemented the "Log In" button yet. But no worries, you'll do that next.

Replace the file `App.js` with the following content:

```javascript
// src/App.js

import './App.css';

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <button>
          Log In
        </button>
      </header>
    </div>
  );
}

export default App;
```

With the button implemented, you can re-run the tests. This time the result should be `1 passed, 1 total`.

But the "Log In" button isn't doing anything yet. Let's make sure it works by using Auth0.

Head back to your `App.test.js` and replace the file with the new contents:

```javascript
// src/App.test.js

import { render, screen, waitFor } from "@testing-library/react";
import App from './App';

import { useAuth0 } from "@auth0/auth0-react";

jest.mock("@auth0/auth0-react");

describe("The Application Component in logged out state", () => {

  beforeEach(() => {
    useAuth0.mockReturnValue({
      loginWithRedirect: jest.fn(),
    });
  });

  afterEach(() => {
    jest.clearAllMocks();
  });

  test('When the app starts it renders a log in button', () => {
    render(<App />);
    const loginElement = screen.getByText("Log In");
    expect(loginElement).toBeInTheDocument();
  });

  test('It redirects the user to the Auth0 Universal Login page when the Log In button is pressed', async () => {
    const { loginWithRedirect } = useAuth0();

    render(<App />);
    const loginElement = screen.getByText("Log In");
    loginElement.click();

    // Expect that if we click the "Log In" button, the loginWithRedirect function gets called
    await waitFor(() => expect(loginWithRedirect).toHaveBeenCalledTimes(1));
  });
});
```

This time we added a new test "It redirects the user to the Auth0 Universal Login page when the Log In button is pressed", which validates that the function `loginWithRedirect` from the Auth0 React SDK is called at least one time after pressing the "Log In" button.

In this code snippet, we introduced a few new concepts; I recommend the following read if you want to familiarize yourself with [jest and mocking functions](https://jestjs.io/docs/mock-functions).

As it is required by `jest`, we had to first mock the Auth0 API using `mockReturnValue` at the beginning of each test suite.

Now if you run the test, you'll receive:

```text
The Application Component in logged out state
    ✓ When the app starts, it renders a log-in button (15 ms)
    ✕ It redirects the user to the Auth0 Universal Login page when the Log In button is pressed (1015 ms)

  ● The Application Component in logged out state › It redirects the user to the Auth0 Universal Login page when the Log In button is pressed

    expect(jest.fn()).toHaveBeenCalledTimes(expected)

    Expected number of calls: 1
    Received number of calls: 0
```

Which is exactly what we expected. Next, you'll make that "Log In" button work.

## Implementing Login with Auth0

Under the hood, the Auth0 React SDK uses [React Context](https://reactjs.org/docs/context.html) to manage the authentication state of your users. One way to integrate Auth0 with your React app is to wrap your root component with an Auth0Provider that you can import from the SDK.

Head to your `index.js` file and update its content as the following:

```javascript
// src/index.js

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';
import { Auth0Provider } from "@auth0/auth0-react"; // 👈 New code

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    {/* 👇 New code */}
    <Auth0Provider
      domain="{auth0-domain}"
      clientId="{auth0-clientid}"
      authorizationParams={{
        redirect_uri: window.location.origin
      }}
    >
    {/* 👆 New code */}
      <App />
    {/* 👇 New code */}
    </Auth0Provider>
    {/* 👆 New code */}
  </React.StrictMode>
);

// If you want to start measuring performance in your app, pass a function
// to log results (for example reportWebVitals(console.log))
// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
reportWebVitals();
```

The `Auth0Provider` requires you to provide the domain for your Auth0 tenant and the clientId for your Auth0 application. Both values are present in your [Auth0 Application's Dashboard](https://manage.auth0.com/#/applications), as shown below:

![You can retrieve the Auth0 domain and client id from the application's settings](https://images.ctfassets.net/23aumh6u8s0i/3y36XLQcKi70jWZBbROCBj/a4d6e4584cc7d29159893f9a7c56e51b/react-tdd-config.png)

After setting those two values in the code, all we have to do is to change the "Log In" button to enable the `onClick` event.

```javascript
// src/App.js

// 👇 New code
import { useAuth0 } from "@auth0/auth0-react";
// 👆 New code
import './App.css';

function App() {
  // 👇 New code
  const { loginWithRedirect } = useAuth0();
  // 👆 New code

  return (
    <div className="App">
      <header className="App-header">
        {/* 👇 Updated code */}
        <button onClick={() => loginWithRedirect()}>
        {/* 👆 Updated code */}
          Log In
        </button>
      </header>
    </div>
  );
}

export default App;
```

Now if you run your tests once more, you'll see both of them passing.

```text
 PASS  src/App.test.js
  The Application Component in logged out state
    ✓ When the app starts, it renders a log in button (11 ms)
    ✓ It redirects the user to the Auth0 Universal Login page when the Log In button is pressed (4 ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
```

## Displaying the User’s Profile

So far, we have been able to test the application while in a logged-out state, but how would we go about testing the application after the user signs in, for example, to test if the user name is displayed correctly on the screen?

The simple answer is to continue mocking the `useAuth0` hook, altering the different properties we need for our test.

Let's start by writing a new test to validate if the "Log Out" button is present after the user signs in. Change the content of your `App.test.js` file by adding the following code:

```javascript
// src/App.test.js

...
// 👇 New code
describe("The Application Component in logged in state", () => {
  beforeEach(() => {
    useAuth0.mockReturnValue({
      isAuthenticated: true,
    });
  });

  afterEach(() => {
    jest.clearAllMocks();
  });

  test('When the app starts it renders a log out button', () => {
    render(<App />);
    const logoutElement = screen.getByText("Log Out");
    expect(logoutElement).toBeInTheDocument();
  });
});
// 👆 New code
```

Running the tests will now fail until we add the new "Log Out" button to the screen.

```javascript
// src/App.js

import { useAuth0 } from "@auth0/auth0-react";
import './App.css';

function App() {
  const { loginWithRedirect, logout, isAuthenticated } = useAuth0(); // 👈 Updated code

  return (
    <div className="App">
      <header className="App-header">
        {/* 👇 Updated code */}
        {isAuthenticated ? (
          <button onClick={() => logout()}>
            Log Out
          </button>
        ) : (
          <button onClick={() => loginWithRedirect()}>
            Log In
          </button>
        )}
        {/* 👆 Updated code */}
      </header>
    </div>
  );
}

export default App;
```

And when you check the tests again, all of them are passing.

```text
 PASS  src/App.test.js
  The Application Component in logged out state
    ✓ When the app starts, it renders a log in button (11 ms)
    ✓ It redirects the user to the Auth0 Universal Login page when the Log In button is pressed (4 ms)
  The Application Component is logged in the state
    ✓ When the app starts, it renders a log-out button (1 ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
```

Finally, we'll validate that the user's name and email address are shown on the screen.

```javascript
// src/App.test.js

...
  beforeEach(() => {
    useAuth0.mockReturnValue({
      isAuthenticated: true,
      // 👇 New code
      user: {
        name: "Juan",
        email: "jc@example.com",
        picture: "https://avatar.com",
      },
      // 👆 New code
    });
  });
  
  ...

  test('When the app starts it renders a log out button', () => {
    render(<App />);
    const logoutElement = screen.getByText("Log Out");
    expect(logoutElement).toBeInTheDocument();
  });

  // 👇 New code
  test('It renders the user name and email address', () => {
    render(<App />);
    const userNameElement = screen.getByTestId("user-name");
    expect(userNameElement).toHaveTextContent('Juan');

    const userEmailElement = screen.getByTestId("user-email");
    expect(userEmailElement).toHaveTextContent('jc@example.com');
  });
  // 👆 New code
});
```

For the logged-in state, not only do we need to mock the authentication status with the `isAuthenticated` flag, but we also need to set the user information.

Once that's done, we can fix the UI to display such values and get the test passing.

```javascript
// src/App.js

import { useAuth0 } from "@auth0/auth0-react";
import './App.css';

function App() {
  const { loginWithRedirect, logout, isAuthenticated, user } = useAuth0(); // 👈 Updated Code

  return (
    <div className="App">
      <header className="App-header">
        {isAuthenticated ? (
          // 👇 Updated code
          <div>
            <h2>User:</h2>
            <p data-testid="user-name">{user.name}</p>
            <h2>Email:</h2>
            <p data-testid="user-email">{user.email}</p>
            <button onClick={() => logout()}>
              Log Out
            </button>
          </div>
          // 👆 Updated code
        ) : (
          <button onClick={() => loginWithRedirect()}>
            Log In
          </button>
        )}
      </header>
    </div>
  );
}

export default App;
```

Now the application displays the user name and email as well as the logged-out button.

Let's run the tests and see the final results.

```text
 PASS  src/App.test.js
  The Application Component in logged out state
    ✓ When the app starts, it renders a log in button (12 ms)
    ✓ It redirects the user to the Auth0 Universal Login page when the Log In button is pressed (4 ms)
  The Application Component is logged in the state
    ✓ It renders a log-out button (2 ms)
    ✓ It renders the user name and email address (3 ms)

Test Suites: 1 passed, 1 total
Tests:       4 passed, 4 total
```

Congrats! But before you leave this tutorial, there's another more thing you'll have to do, and that is user testing.

So far, all tests you run on the application are unit tests. Even though they are great for validating functionality, they don't verify that the integrations are working or set up correctly. For example, we mocked the Auth0 API to return the data we would expect if everything was fine. Still, we don't validate if the given Auth0 Domain or Client ID is correct or if the configuration on the Auth0 dashboard is appropriately set.

For that, you can write integration tests or perform manual tests by running the application on the browser.

To test your application manually, go to your terminal and start the app by running the following:

```bash
npm run start
```

Visit `http://localhost:3000`, click the login button, and sign up for a new test user if you don't have one. After you're done, you'll be redirected back to the application where your name is displayed.

| ![Application's start page](https://images.ctfassets.net/23aumh6u8s0i/1ueiE6uYH8ig9Vs6EJ0HVd/5a5f5598a90b091c68ced31c0c163cfe/react-tdd-1.png)|![Auth0 Universal Login Screen](https://images.ctfassets.net/23aumh6u8s0i/7h6l4mzkJvj4SMgIPxqq8J/12ee1f571be10baf746ba5404e0232d2/react-tdd-2.png) | ![Application's user information screen](https://images.ctfassets.net/23aumh6u8s0i/1ZUiCCpbIYKAtsKapLnSB5/9a623efc3daa63d0018be195808a5b7e/react-tdd-3.png) |
| --- | --- | --- | 

## Conclusion

In this tutorial, you have implemented user authentication to identify your users and get user profile information in React following the TDD process to ensure that our code is well-tested.

This tutorial covered the most common authentication use case for a React application, and to keep it simple, we took some shortcuts, like working off a single component.

If you want to learn more about the possibilities of Auth0 with React, please check the [React Authentication by Example Guide](https://developer.auth0.com/resources/guides/spa/react/basic-authentication).

Let me know in the comments below what you think of this tutorial.

Thanks for reading!

Unit Testing Your Auth0 Protected React Application

dan-lourenco

Guest Author

Dan Lourenco

Learn how to programmatically authenticate against Auth0 in your Cypress tests in a manner that adheres to both Cypress and Auth0 best practices.

<div class="alert alert-info alert-icon">
  <i class="icon-budicon-487"></i>
  <strong>Important Announcement</strong><br> 
  <b>This blog post is no longer maintained and it may be out of date</b>. Please use the following resources created by the Cypress team to learn how to use Cypress to test a Single-Page Application (SPA) that uses Auth0: 

  * <a href="https://cypress.io/blog/2022/04/25/cypress-9-6-0-easily-test-multi-domain-workflows-with-cy-origin/">Cypress 9.6.0: Easily test multi-domain workflows with cy.origin</a> (Blog post)
  * <a href="https://www.youtube.com/watch?v=Fohrq5GZSD8">How to test multiple domains or origins with Cypress</a> (Video) <br>

<br />
<iframe width="560" height="315" src="https://www.youtube.com/embed/Fohrq5GZSD8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</div>

**TL;DR:** This post discusses how to authenticate against Auth0 in your Cypress end-to-end tests successfully. You will use a small sample React application to illustrate patterns you can use to programmatically log your user into Auth0 while running Cypress tests, in a manner that adheres to most Cypress and Auth0 best practices. To see a working example of the techniques described in this article, please feel free to clone [this repo](https://github.com/dlo83/auth0-cypress-demo).

<include src="TweetQuote" quoteText="Learn how to perform end-to-end integration tests on SPAs secured with Auth0."/>

## Prerequisites

As mentioned, you will be using a React application written with modern JavaScript language features (ES2015+), so a good understanding of modern web technologies is recommended. If you’re not quite there yet, there are a wealth of fantastic resources for modern JS development, including courses from [Wes Bos](https://es6.io/), [Tyler McGinnis](https://tylermcginnis.com/), and others.

You will also need to have Node.js and NPM installed. [Check out the Node.js website](https://nodejs.org/en/download/) for download links and an installation guide.

You are also expected to have an Auth0 account and have valid user permissions so that you can authenticate into your application. So, if you don't have an Auth0 account yet, <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free now</a>.

<include src="SignupCTA" text="Try out the most powerful authentication platform for free." linkText="Get started →" />

Lastly, a basic understanding of what Cypress is and why it’s useful is expected. If you do not know Cypress, check out [this article](https://auth0.com/blog/cypress-write-automated-tests-to-validate-web-applications/) for more.

## Auth0 Setup & Configuration

To see the whole process in action, you will need to create an Auth0 Application on your Auth0 dashboard. To do so, head to [the Applications section of your dashboard](https://manage.auth0.com/#/applications) and click on the _Create Application_ button. When you click on this button, you will see a dialog. On this dialog, you will have to add a name for your application (e.g., "Cypress E2E Testing") and you will have to select _Single Page Web App_ as its type.

Now, clicking on the _Create_ button will make Auth0 redirect you to the _Quick Start_ page of your new application. From there, you can head to the _Settings_ tab and configure it as follows:

* Scroll down to the _Allowed Callback URLs_ field and enter in the following value: `http://localhost:3000/callback`. After user authentication occurs, Auth0 will only redirect successfully if the route in question is listed here.
* Enter `http://localhost:3000` into the **Allowed Web Origin** field.
* Enter `http://localhost:3000` into the **Allowed Logout URLs** field.
* Scroll down to the bottom of the **Settings** page and click **Show Advanced Settings**.
* Click on the **Grant Types** tab, and check the **Password** grant.
* Click **Save Changes**.

Now, you can create a user account for the end-to-end testing scripts. To do so, head to [the _Users_ section of your dashboard](https://manage.auth0.com/#/users) and click on _Create User_. On the dialog shown by Auth0, fill the form as follows:

* _Email_: Enter a random email address (e.g., `e2e-testing@mydomain.com`)
* _Password_: Enter a random password (e.g., `s#m3R4nd0m-pass`)
* _Repeat Password_: Enter the same password.
* _Connection_: Use the `Username-Password-Authentication`

After that, click on _Save_ to finish the process.

Lastly, you will have to go to [your tenant's settings](https://manage.auth0.com/#/tenant) and set `Username-Password-Authentication` as the value of the _Default Directory_ property. As mentioned in this page, this field defines the "name of the connection to be used for Password Grant exchanges". In this case, the `Username-Password-Authentication` value comes from the default the default [_Database Connections_](https://manage.auth0.com/#/connections/database) that Auth0 adds to all new tenants.

![Auth0's default database connection.](https://images.ctfassets.net/23aumh6u8s0i/WIYNDHA9YBusXqhZJn13E/f3750b39784c88804197a33f7b728e5b/auth0-default-database-connection)

Just don't forget to save the changes made to your tenant.

## The Sample App

First things first, clone [this repo](https://github.com/dlo83/auth0-cypress-demo) and check out the `base` branch:

```bash
# clone the repo
git clone https://github.com/dlo83/auth0-cypress-demo.git

# move into it
cd auth0-cypress-demo

# checkout the base branch
git checkout base
```

> **Note:** You can also refer to the finished product on the `master` branch. Then, be sure to `npm install` and `npm run start` in your terminal to spin up the application.

This app will be quite simple: it is a React application with a few routes, powered by React Router 4. One of the routes will be protected — that is, only accessible for authenticated users — and the other, public.

There will be one other route which serves an important purpose: the `/callback` route. This route is where the user is redirected after successfully entering their Auth0 credentials. When this route is hit, the application checks to ensure that the state information in the URL's query string matches the state stored in the persisted cookie.

If these protected route patterns are unfamiliar to you, I highly recommend checking out [Bruno Krebs' article](https://auth0.com/blog/react-tutorial-building-and-securing-your-first-app/) for more.

## Cypress

Cypress is a modern front-end testing tool that makes writing integration tests a breeze. This tool is, essentially, a one-stop shop for all your end-to-end testing needs, combining a _fast_, state-of-the-art testing framework, graphical and headless test runners, and easy-to-use assertion library in one package.

### Authentication with Cypress

So you’re sold on Cypress and you’re using Auth0 for your authentication needs. Now, it is time to see how you can make the two play nicely together!

Imagine that you want to write a test to ensure that a user can visit a page only available behind authentication. How would you do this?

The naive approach would be to:

* Visit the web application and invoke a redirect to the Auth0 login page (via a button click, route change, etc.)
* Enter in your Auth0 username and password
* Submit the form
* Wait for the redirect to your web application and proceed as needed

There’s a problem with this, though. To paraphrase co-founder of Cypress, [Brian Mann](https://github.com/cypress-io/cypress/issues/1342#issuecomment-366747803):

> The best practice is never to visit or test third-party sites over which you have no control.

Then, since you don’t have control over the Auth0 website, it doesn’t make sense to try and mimic a user’s login flow through the UI.

So what do you have to do?

<include src="TweetQuote" quoteText="Don't waste time covering services that you do not control on your end-to-end tests."/>

### Cypress Best Practices

Thankfully, a Cypress contains an [example recipe](https://github.com/cypress-io/cypress-example-recipes/tree/master/examples/logging-in__single-sign-on) that can help you. The general pattern for dealing with Single Sign-On authentication is as follows:

*  Use Cypress’ `cy.request()` command to make an HTTP request to your authentication service (in this case, Auth0)
*  Parse the tokens in the response
*  Set tokens on local storage

> **Note:** Auth0 now recommends [using cookies in lieu of local storage](https://auth0.com/docs/security/store-tokens#don-t-store-tokens-in-local-storage). Not a problem. You will adhere to this recommendation in your implementation.

Now that you have a strategy in place, you can get started.

### Cypress Commands

As stated above, your first course of action is to make an HTTP request against Auth0 using Cypress `cy.request()` command. A request with Cypress would look something like this:

```javascript
const options = {
  method: 'POST',
    url: 'https://my.url.com/endpoint',

    body: {
      username: 'my_username'
      password: 'my_password'
      ...
    }
}

cy.request(options)
```

That's great and all, but you can imagine that having to write the code above every time you want to log in could be quite cumbersome and violate DRY (Don't Repeat Yourself) principles. Thankfully, Cypress has a feature called [Custom Commands](https://docs.cypress.io/api/cypress-api/custom-commands.html#Syntax) that allow you to encapsulate this code and make it reusable across your tests.

So, insert the following code to the end of the `cypress/support/commands.js` file:

```javascript
Cypress.Commands.add('login', (overrides = {}) => {
  Cypress.log({
    name: 'loginViaAuth0',
  });

  const options = {
    method: 'POST',
    url: Cypress.env('auth_url'),
    body: {
      grant_type: 'password',
      username: Cypress.env('auth_username'),
      password: Cypress.env('auth_password'),
      audience: Cypress.env('auth_audience'),
      scope: 'openid profile email',
      client_id: Cypress.env('auth_client_id'),
      client_secret: Cypress.env('auth_client_secret'),
    },
  };
  cy.request(options);
});
```

Now, when you want to trigger a request to authenticate against Auth0, you simply have to call `cy.login()` from your code. The custom command name to use in your consuming code (in this case, `login`) corresponds to the first argument given to the `add()` method.

OK, so you have your custom Cypress login command, but what's with the `Cypress.env` values for the keys in the body object?

### Cypress Environment Variables

Because you re providing sensitive information in your Cypress request to Auth0, you need to authenticate. And, it's imperative to store this information outside of your test suite.

At the root of your project, create a file called `cypress.env.json` and, before populating this file, add this line to your `.gitignore` file:

```gitignore
cypress.env.json
```

This ensures that you do not accidentally commit any sensitive details to your Git repository. _Please, **do not forget** this step!_

Now, back in your `cypress.env.json` file, add the following code to it:

```json
{
  "auth_audience": "https://my_tenant.auth0.com/api/v2/",
  "auth_url": "https://my_tenant.auth0.com/oauth/token",
  "auth_client_id": "my_client_id",
  "auth_client_secret": "my_client_secret",
  "auth_username": "my_username",
  "auth_password": "my_password"
}
```

You will have to update each one of the properties above with your own Auth0 values:

- `auth_audience`: For this one, you will have to replace `my_tenant.auth0.com` with your own Auth0 domain (e.g., `blog-samples.auth0.com`). You can find this information on the Auth0 application you created before.
- `auth_url`: Here, you will have to do the same thing. You will have to replace `my_tenant.auth0.com` with your own Auth0 domain.
- `auth_client_id`: In this case, you will have to use the _Client ID_ property of the Auth0 Application you created before.
- `auth_client_secret`: Lastly, for this property, you will have to use the _Client Secret_ property of the Auth0 Application you created.

![Copying the Auth0 Application properties to configure your Cypress end-to-end testing scripts.](https://images.ctfassets.net/23aumh6u8s0i/1zI1K62EuZ5hEcDcV3BgzK/f72c67890bb1f3358df8f731429806e6/copying-auth0-application-properties)

For the last two properties (`auth_username` and `auth_password`) you will have to use the credentials used while creating the end-to-end testing user.

### Configure React App Environment Variables

Cypress isn't the only tool in your application that has to take environment variables. You will have to define environment variables for your React application as well, albeit in a different file.

* Rename the `.env.sample` file in the root of the project to simply `.env`.
* Replace the `my-tenant.auth0.com` value (on the `REACT_APP_AUTH0_DOMAIN` variable) with your tenant domain (e.g., `blog-samples.auth0.com`).
* Insert your _Client ID_ for the `REACT_APP_AUTH0_CLIENT_ID` variable. Unlike the `cypress.env.json` file, there should be no quotes around this value here.

### Grant Strategies

While creating your Auth0 Application, you enabled the Password grant. But what exactly is a grant, anyway?

[Auth0](https://auth0.com/docs/applications/application-grant-types) defines a grant as follows:

> OAuth 2.0 supports several types of grants, which are methods by which you can gain access tokens. Different grant types allow different types of access and, based on the needs of your app, some grant types are more appropriate than others.

That last sentence is the key here. Normally, when authenticating with Auth0, you are redirected to log in through Auth0's hosted login page. *But*, since you are in a testing environment (and again, you don't want to test what you don't control), you have to find some other way to authenticate against Auth0 without redirecting away from your application. That's where the Password Grant comes in. The Password grant relies on authenticating a user via provided username and password credentials.

## Writing tests using Cypress Login Command

OK. You have created your Cypress Custom Command for login. Also, you have configured your Auth0 account and you have updated your Cypress environment variables. Now, you will see how you can take advantage of everything you've done to log into Auth0 programmatically using Cypress!

In your project, create a new directory called `integration` inside `cypress`. Then, add a file called `login.js` to it with the following code:

```javascript
describe('login', () => {
  it('should successfully log into our app', () => {
    cy.login()
      .then((resp) => {
        return resp.body;
      })
      .then((body) => {
        const {access_token, expires_in, id_token} = body;
        const auth0State = {
          nonce: '',
          state: 'some-random-state'
        };
        const callbackUrl = `/callback#access_token=${access_token}&scope=openid&id_token=${id_token}&expires_in=${expires_in}&token_type=Bearer&state=${auth0State.state}`;
        cy.visit(callbackUrl, {
          onBeforeLoad(win) {
            win.document.cookie = 'com.auth0.auth.some-random-state=' + JSON.stringify(auth0State);
          }
        });
      })
  });
});
```

Now, in your terminal, run the following commands from the root directory of your React project:

```bash
# install all dependencies
npm install

# run the React app on the background
npm start &

# run cypress
npm run cypress:open
```

This will make the Cypress dashboard open.

![Cypress dashboard](https://images.ctfassets.net/23aumh6u8s0i/1JdvnCY4VmEIXOFCmuoFqo/bdcdf89014bc58b285c1b2fc08ec6a21/running-the-cypress-dashboard)

From there, you can click on the `login.js` integration test in the Cypress test runner. You should now see an instance of Chrome launched, with your user automatically logged in to Auth0! Click on the **Profile** page to see your logged in user's email address for verification.

![Running the E2E testing scripts with Cypress and Auth0.](https://images.ctfassets.net/23aumh6u8s0i/4ZSK4oPQf8PXPlld8b81bI/d3a85580fa2ebc214bcab7df9d43d484/running-the-e2e-testing-scripts-with-cypress-and-auth0)

<include src="TweetQuote" quoteText="I just learned how to perform end-to-end integration tests on SPAs secured with Auth0."/>

## Wrap Up

In this article, you started by learning about one of Cypress' core tenets when it comes to testing: avoid testing sites over which one does not have control. Next, you took a quick look on _Cypress Custom Commands_ and how they make your lives easier by encapsulating repetitive testing logic. Then, you learned about _Grant Strategies_, which are methods by which you can gain access tokens. More specifically, you learned about the _Resource Owner Password Grant_ strategy, which allows you to receive a token by providing username and password credentials, thereby circumventing the need to visit the Auth0 login page.

> **Note:** Keep in mind that you must not use this grant on your public clients. This is an exception to this rule because it is an end-to-end test that won't be used by real users.

Finally, you learned about how you can use your custom login command in a test, set your access token in memory, and successfully log into your application as part of your Cypress test.

I hope you've enjoyed reading this article, and have gained an understanding of how you can incorporate Cypress into your Auth0 application. If you have any questions or concerns, please feel free to leave a comment down below.

Thanks for reading!


End-to-End Testing with Cypress and Auth0

jekayinoluwa

I love to deal in the intersection of software, hardware, and human interaction. My strength lies in the seamless combination of my top skills - design, software development, and strategic management.

Software Developer & Technical Writer

Jekayinoluwa Olabemiwo

A tutorial to learn how to write unit tests and integration tests for REST APIs in AWS Chalice. Additionally, we will see how to measure test coverage.

Testing AWS Chalice Applications

arthur-bellore

I’m a tech content creator. I enjoy breaking up seemingly complicated topics into easy-to-understand pieces for people to read. When I’m not in front of a computer, you’ll usually find me reading books.

Cybersec Writer

Arthur Bellore

With modern computers capable of testing millions of password combinations per second, securing your online accounts with only a password may not be sufficient anymore.

The Working Principles of 2FA (2-Factor Authentication) Software

facundo-giuliani

Facundo is a Systems Engineer from Buenos Aires, Argentina with 15+ years of experience in software development. Full Stack Developer. Auth0 Ambassador. GitKraken Ambassador. Cloudinary Media Developer Expert. He is also an open-source contributor.

Systems Engineer, Full Stack Developer

Facundo Giuliani

Automating web browser interactions is a great way to test the functionalities of our web application. Let's see how to create UI tests in C# using Playwright Sharp, a browser automation library.

While creating web applications, we want to release them with as few errors as possible. We also want to make sure that the new functionalities we add to our apps don't break the existing behavior and workflows. The only way we can do that is by testing the different scenarios our apps support.

While our code base gets bigger and bigger, it gets pretty hard to manually go through the different paths our app offers every time we apply changes and edits. And even if we are coding a small web application, manual testing executed by a person may not always be the best solution. That is why having automated tests that run periodically through our apps is always a recommended idea.

We talk about User Interface testing when we want to test the visual aspects of an application. We do this to verify that the parts of our product that users will interact with are working as expected, and they meet the performance and functionality requirements.

We can create automatic processes and algorithms, probably using mock data, that execute [unit and integration tests](https://auth0.com/blog/xunit-to-test-csharp-code/) across our codebase. Doing this, we verify that everything is working as expected, and we are supporting all the logical scenarios and business rules our application handles. But if we want to test visual elements from our apps, we will need the help of a web browser.

## What Is Browser Automation?

As developers, we (should) always try to automate things. We make things faster, we save work time, we spend less money, we depend less on human assistance, we get consistent results over iterations.

If we want to create and run UI tests for our web apps, we should automate actions related to web browsers. We will need to simulate interactions using input devices (keyboard, mouse, etc.), and we will verify that visual elements are working and displayed correctly.
"Browser automation" is automating the usage of a web browser. The goal is to achieve efficiency and speed at a certain level that wouldn't be possible if we depend on human interaction.

There are different tools available to accomplish browser automation, implemented in different programming languages and with different features. Today we will talk about Playwright and the .NET implementation: Playwright Sharp.

## What Is Playwright?

[Playwright](https://playwright.dev/) is an [open-source](https://github.com/microsoft/playwright) browser automation library. It is a JavaScript-based library created to be used with Node.js. One of the main differences with other browser automation tools is that Playwright is cross-browser. It can automate tasks using Chromium (Google Chrome, Microsoft Edge), WebKit (Apple Safari), and Mozilla Firefox browsers, all with the same API.

Playwright was created by Microsoft. It was developed based on [Puppeteer](https://pptr.dev/), and it was improved to perform automatic UI testing.

Some of the benefits Playwright offers are:

- Support for all browsers
- Test for mobile using device emulation
- Cross-platform WebKit testing
- Headless and headful execution: while automation is being executed, you can hide (headless) or show (headful) the web browser UI. Headful is usually selected for debugging, while headless is the preferred option for continuous integration or cloud executions.

<include src="TweetQuote" quoteText="Playwright Sharp ports the power of browser automation to .NET." />

## What Is Playwright Sharp?

[Playwright Sharp](https://github.com/microsoft/playwright-sharp) is a .NET porting for Playwright. It works close to the product, so we have all the features from the original library available to be used in .NET.

Playwright Sharp has been built with C#, so developers can get the advantage of .NET features such as dependency injection, "Async" suffixes, etc.

The NuGet package has two required dependencies: the Playwright driver and the browsers that we can use. Playwright drivers will be copied to the bin folder at build time. The browsers are installed in different ways depending on the use we give to the library. If we want to use Playwright Sharp in test projects, browsers will be installed at build time.

Let's create an example project to use some of the features Playwright Sharp offers.

## Playwright Sharp in Action

To get acquainted with Playwright Sharp methods and features, we will create a small end-to-end test. End-to-end testing is a technique that tests a complete workflow, from beginning to end, to ensure the flow behaves as expected. The idea is to test real scenarios to verify that everything is working as expected.
For this article, we will test part of the [Auth0 website](https://auth0.com/). Let's say that we want to test if a particular Quickstart guide is working, and the link to the GitHub repository where the sample code lives is correct. Let's pick ["Regular Web App" for ASP.NET Core](https://auth0.com/docs/quickstart/webapp/aspnet-core).

If you want to see the final code of the project we are going to create, download it from [this GitHub repo](https://github.com/auth0-blog/playwright-sharp-auth0).

First of all, we need to create a project using a testing library to code and run our tests. You can choose any testing library you want that works with .NET Core and C#. For this example, let's create a new [NUnit](https://nunit.org/) Test Project.

![NUnit Test Project in Visual Studio for Mac](https://images.ctfassets.net/23aumh6u8s0i/5I32SOweWF4ndmTeapbNP9/82198c8a017365acd1e69073c86f1f77/nunit-test-project.png)

Once the project is created and the standard files are generated, let's add the "PlaywrightSharp" NuGet package to the project.

![Playwright Sharp Nuget Package in Visual Studio for Mac](https://images.ctfassets.net/23aumh6u8s0i/6DO9jJ8OSwyKPMGDrtTSNa/2e6740b35a1e5c562619b5b3af37abfb/playwright-sharp-nuget.png)

We will create only one test, so we will use the `UnitTest1.cs` file already generated and replace its content with the following:

```csharp
// UnitTest1.cs

using System.Threading.Tasks;
using NUnit.Framework;
using PlaywrightSharp;

namespace PlaywrightSharpAuth0
{
    public class Tests
    {
        [Test]
        public async Task Auth0RegularWebAppASPNETCoreLinkWorks()
        {
            using var playwright = await Playwright.CreateAsync();
            await using var browser = await playwright.Chromium.LaunchAsync(headless: true);

            // Go to Auth0 home page
            var page = await browser.NewPageAsync();
            await page.GoToAsync("https://auth0.com/");

            // Click on the cookie policy acceptance button if it exists
            if ((await page.QuerySelectorAsync("#truste-consent-button")) != null)
            {
                await page.ClickAsync("#truste-consent-button");
            }

            // Hover on Developers
            await page.HoverAsync("li[aria-labelledby='nav-item-Developers']");

            // Click on Quickstarts
            await page.ClickAsync("a[href='https://auth0.com/docs/quickstarts/']");

            // Hover on Regular Web App
            await page.HoverAsync("div[data-type='webapp']");

            // Click on Launch Quickstart
            await page.ClickAsync("div[data-type='webapp'] button.btn-success");

            // Search for ASP.NET Core
            await page.TypeAsync("div.quickstart-search-input input", "ASP.NET Core");

            // Click on ASP.NET Core logo
            await page.ClickAsync("div[data-name='aspnet-core']");

            // Look for "View on Github" button and get the href property
            var gitHubLink = await page.EvalOnSelectorAsync<string>("a.btn-transparent.btn-block", "e => e.getAttribute('href')");

            Assert.AreEqual(gitHubLink, "https://github.com/auth0-samples/auth0-aspnetcore-mvc-samples/tree/master/Quickstart/01-Login");
        }
    }
}

```

Let's talk about the different methods used in the test.

- We create a Playwright instance that allows us to launch a web browser.
- For this example, we launch Chromium, the core of browsers like Google Chrome and Microsoft Edge. `LaunchAsync` method has several parameters. We use `headless: true` because we don't want to see how the browser operates while executing the test. If we set `headless: false` instead, a new browser window will be opened, and we will see how each step of the test is executed. This could be helpful in case we want to debug our tests.
- We open a new page in the browser, and we go to a specific URL. In this case, the Auth0 homepage.
- We hover some elements to display different menus. We also click on links to go to other pages. `HoverAsync` and `ClickAsync` accept [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to look for specific elements in the web page.
- We can also type text inside an input with `TypeAsync`.
- With `EvalOnSelectorAsync`, we execute an expression and get its result. In this case, we look for the `href` property value of an `<a>` element with the specified CSS selector. We compare that value with the URL we expect, so we can say the test passed correctly.

If we run the test, it should pass (if the Auth0 page didn't change since this article was written).

![Successful Test](https://images.ctfassets.net/23aumh6u8s0i/8IlLz1hcJmRQRkMtRJX2z/d2b1104b3c134af53b4ecd19fdb5b44e/playwright-successful-test.png)

## What's Next?

We created a simple end-to-end test, so we saw how to use some of Playwright Sharp main features. If we want to create more complex UI tests or to automate another kind of browser-based task, we can take a look at the [Playwright GitHub repository](https://github.com/microsoft/playwright-sharp) for some examples. We also have the [official Playwright documentation site](https://playwright.dev/docs/intro), where we can read about different concepts and functions we have available to create our automation processes. There are various elements from a web page that we can interact with: dialogs, downloads, authentication, videos, etc. We can also generate screenshots of what's displayed in the browser or even generate PDF files.

## Summary

In this article, we talked about UI testing and how to implement that through browser automation using Playwright Sharp. If we want to create tests that cover the possible workflows of our web application and analyze the visual elements of them, a library like Playwright Sharp is a powerful tool. With it, we can create end-to-end tests supporting all modern web browsers.

<include src="asides/DotNetCore" />

End-To-End Testing With Playwright Sharp

olususi-oluyemi

Oluyemi is a tech enthusiast with a background in Telecommunication Engineering. He ventured into programming with a keen interest in solving day-to-day problems encountered by users. He has since directed his problem-solving skills towards building software for both the web and mobile platforms. As a full-stack software engineer with a passion for sharing knowledge, Oluyemi has published many technical articles and content on several blogs worldwide. As s tech-savvy person, his hobbies include trying out new programming languages and frameworks.

Software Engineer / Technical Content Creator

Olususi Oluyemi

Learn how to test Laravel APIs using PHPUnit.

Testing Laravel APIs Using PHPUnit

auziros:jeana-tahnk

Jeana has been in the tech industry for 15+ years, both as a communications professional and writer. As Director of Global Communications at Auth0, she works with her internal team and external agencies to amplify the company's visibility worldwide and establish its leadership in the identity industry. When she is not working, she can most likely be found on a field watching one of her three kids playing sports, or cleaning up after her one-year-old retriever who chews everything.

Senior Director, Global Communications

Jeana Tahnk

Leading laboratory testing provider seamlessly handles 25x volume increase in patient portal users during COVID-19 with Auth0



**BELLEVUE, Wash. – Dec. 10, 2020 –** The [Auth0](https://auth0.com/) Identity Platform, a product unit within Okta, today announced that it is providing [BioReference Laboratories, Inc.](https://www.bioreference.com/), an OPKO Health company and a leading provider of laboratory testing services in the U.S., with end-to-end authentication for its patient portal, giving patients HIPAA compliant and secure, direct access to their lab results and medical data. This was essential as COVID-19 hit and BioReference faced a rise in new patient portal users&mdash;including a 25x increase in volume overnight&mdash;who needed a secure and easy way to monitor their test results.

BioReference provides comprehensive diagnostic solutions to healthcare providers, clinics, hospitals, employers, government units, correctional institutions, medical groups, and more. The laboratory’s vast test menu is utilized in the detection, diagnosis, evaluation, monitoring, and treatment of disease, including COVID-19. In recent months, BioReference has made significant investments in its B2B and B2C offerings, including Customer Digital Solutions, Direct-to-Consumer Solutions, Telehealth, and Patient Empowerment. 

“COVID-19 has caused a seven to ten-year acceleration in consumer and digital trends,” said Richard Schwabacher, SVP for Digital Health and Chief Digital Officer at BioReference Laboratories. “Securing, transmitting, and authorizing patient access to health information digitally is now critical to the practice of medicine and core to what is needed from a modern digital health solution.”

Identity and access management (IAM) was a key component in BioReference’s transition to providing a more patient-centric model. The company leveraged Auth0 as the IAM in its new patient portal so that patients can securely see results and pay bills, giving patients direct access to their healthcare information. Now, patients no longer have to depend upon their healthcare provider to act as an intermediary to access this information.  

“Auth0 helps address concerns about security and user access, especially during times like the present when COVID-19 is causing a significant increase in patient demand,” said Vinny Pacione, VP of Consumer Technology and Digital Solutions at BioReference Laboratories. “Enabling delivery of this data to individuals in a self-service way using scalable, automated digital platforms was a key problem to solve. The most fundamental piece of the solution is securing the data and ensuring that only the individuals who have appropriate authorization can access it.”

“Identity management is a critical component of any digital transformation initiative, and COVID-19 has forced many companies into transition,” said Ghazi Masood, SVP of Americas for Auth0. “BioReference aspires to transform telehealth and put patients at the center of the future of medicine. We are proud to aid them in their journey and help them to deliver a secure, seamless experience for their patients.”

More details on BioReference’s implementation of Auth0 can be found [here](https://auth0.com/case-studies/bioreference/).

## About BioReference Laboratories, Inc.

BioReference provides comprehensive testing to physicians, clinics, hospitals, employers, government units, correctional institutions, and medical groups. BioReference developed and offers test services that yield high quality and accurate results, including a molecular test for helping with COVID-19 diagnosis and a serology test to help indicate possible COVID-19 exposure. The company is in network with the five largest health plans in the United States, operates a network of 11 laboratory locations, and is backed by a medical staff of more than 120 M.D., Ph.D., and other professional level clinicians and scientists. With a leading position in the areas of genetics, women’s health, maternal fetal medicine, oncology, and urology, BioReference and its specialty laboratories, GenPath and GeneDx, are advancing the course of modern medicine. For more information, visit [www.bioreference.com](https://www.bioreference.com/).

<include src="asides/AboutAuth0" />

### Media Contacts: 
Auth0 Global Communications <br />
[press@auth0.com](mailto:press@auth0.com) <br />
 
Matter for Auth0 <br />
[auth0@matternow.com](mailto:auth0@matternow.com) <br />

BioReference Laboratories Communications <br />
[media@bioreference.com](mailto:media@bioreference.com)


Auth0 and BioReference Laboratories Answer Patient Demand for Secure, Direct Access to Test Results

Dirceu-Tiegs

What I enjoy the most about being an SRE at Auth0 is that it allows me to exercise different areas such as coding, architecture, writing, training, investigations, debugging, and incident response. It's great to be able to think deeply about all aspects related to reliability and then apply it to large-scale, real-world projects.

Site Reliability Engineering Team

Dirceu Tiegs

Learn more about how Auth0 architects its services to ensure scalability and high availability to handle more than 1.5 billion logins per month.



Auth0 provides authentication, authorization, and single sign-on services for apps of any type (mobile, web, native) on any stack. Authentication is critical for the vast majority of apps. We designed Auth0 from the beginning so that it could run anywhere: on our cloud, on your cloud, or even on your own private infrastructure.

In this post, we'll talk more about our public SaaS deployments and provide a brief introduction to the infrastructure behind [auth0.com](https://auth0.com/) and the strategies we use to keep it up and running with high availability. This is an updated version of the [2014 High Scalability post about Auth0's architecture](http://highscalability.com/blog/2014/12/1/auth0-architecture-running-in-multiple-cloud-providers-and-r.html).

A lot has changed since then in Auth0. These are some of the highlights:

- We went from processing a couple of million logins per month to 2.5 billion logins per month, serving thousands of customers, including [FuboTV](https://auth0.com/learn/sports-centric-streaming-service-fubotv-sees-50-roi-just-auth0s-security/), [Mozilla](https://auth0.com/blog/auth0-mozilla-partnership/), [InterMiles](https://auth0.com/learn/jetprivilege-case-study/), and more.

- We implemented new features like [custom domains](https://auth0.com/docs/custom-domains), [scaled bcrypt operations](https://auth0.engineering/bcrypt-as-a-service-9e71707bda47), vastly [improved user search](https://auth0.com/docs/users/search/v3), and much more.

- The number of services that compose our product in order to scale our organization and handle the increases in traffic went from under 10 to over 30 services.

- The number of cloud resources grew immensely as well; we used to have a couple dozen nodes in one environment (US), now we have more than a thousand over four environments (US, US-2, EU, AU).

- We doubled-down decided to use a single cloud provider for each of our environments and moved all our public cloud infrastructure to AWS.

## Core service architecture

![Auth0.com core service architecture](https://images.ctfassets.net/23aumh6u8s0i/2mden7W7brrYGv8LHDK2Lp/5347634d4197ae655555cf93b8209c2d/auth0-core-service-architecture)

The core service is composed of different layers:

- Core applications: Auto-scaling groups of servers running different services of our stack (authentication, management API, multi-factor authentication API, and much more).

- Data storage: Clusters of MongoDB, Elasticsearch, Redis, and PostgreSQL storing a variety of datasets for different applications and features.

- Transports/Queues: Kinesis streams and RabbitMQ, SNS, and SQS queues.

- Base services: Services for rate-limiting, bcrypt clusters, feature-flags, and more.

- Routing: AWS load balancers (ALB, NLB, and ELB from AWS) and some nodes running NGINX as a proxy.

## High Availability

In 2014 we used a multi-cloud architecture (using Azure and AWS, with some extra resources on Google Cloud) and that served us well for years. As our usage (and load) rapidly increased, we found ourselves relying on AWS resources more and more.

At first, we switched our primary region in our environment to be in AWS, keeping Azure as failover. As we began using more AWS resources like Kinesis and SQS, we started having trouble keeping the same feature set in both providers. As our need to move (and scale) faster grew, we opted to keep supporting Azure with a limited feature parity: if everything went down on AWS, we could still support core authentication features using the Azure clusters, but not much of the new stuff we had been developing.

After some bad outages in 2016, we decided to finally converge on AWS. We stopped all efforts related to keeping the services and automation platform-independent and instead focused on:

- Providing a better failover story inside AWS, using multiple regions and at least 3 Availability Zones per region.

- Increasing usage of AWS-specific resources like auto-scaling groups (instead of using fixed clusters of nodes), application load balancers (ALBs), and more.

- Writing better automation: we revamped our automation, completely embracing infrastructure as code using TerraForm and SaltStack to provision new Auth0 environments (and also to replace existing ones). This allowed us to grow from partially automated environments doing ~300 logins per second to fully automated environments doing more than ~3.4 thousand logins per second; using the new tooling makes it easier to scale up (and down, whenever it makes sense). The level of automation we achieved is not perfect but is allowing us to grow to new regions and create new environments in a much more convenient way.

- Writing better playbooks: with more time and focus, we saw that besides automation we also needed better playbooks in order to understand, manage, and respond to incidents related to our ever-growing mesh of services. This vastly improved scalability and reliability while also allowing us to onboard new employees faster.

<include src="TweetQuote" quoteText="Writing better automation let us grow from partially automated environments doing ~300 logins per second to fully automated environments doing more than ~3.4 thousand logins per second"/>

Let's take a look at our US environment architecture, for instance. We have this general structure:

![Auth0 US Environment Architecture](https://images.ctfassets.net/23aumh6u8s0i/4hGMwY5n4jk2aoJyyRAhjF/0ca131b596da7068aced34ca69fbbc5c/auth0-us-environment-architecture)

And this is the structure inside a single AZ:

![Auth0 Single Availablity Zone](https://images.ctfassets.net/23aumh6u8s0i/4EtOG7to5lHmyYnU5Q3aaC/a22b74fe7b0a58d0f54a78a6b801bbd2/auth0-single-availability-zone)

In this case, we use two AWS regions: us-west-2 (our primary) and us-west-1 (our failover). Under normal circumstances, all requests will go to us-west-2, being served by three separate availability zones.

This is how we achieve high availability: all services (including databases) have running instances on every availability zone (AZ). If one AZ is down due to a data center failure, we still have two AZs to serve requests from. If the entire region is down or having errors, we can update Route53 to failover to us-west-1 and resume operations.

<include src="TweetQuote" quoteText="We achieve high availability by running all services instances on every AWS availability zone"/>

We have different maturity levels for service failover: some services, like user search v2 (that builds a cache on Elasticsearch) might work but with slightly stale data; still, core functionality keeps working as expected.

In the data layer, we use:

- A cross-region cluster for MongoDB.

- RDS replication for PostgreSQL.

- Clusters per region for Elasticsearch with automated snapshot and restores running regularly to account for the lack of cross-region clustering.

We exercise failover at least once per year, and we have playbooks and automation to help new infrastructure engineers get up to speed on how to do it and what are the implications.

Our deployments are usually triggered by a Jenkins node; depending on the service we either use Puppet, SaltStack, and/or Ansible to update individual or groups of nodes, or we update our AMIs and create new autoscaling groups for immutable deployments. We have different types of deployments for new and old services, and this has been shown to be largely ineffective as we need to maintain automation, docs, and monitoring for something that should be unified.

We are currently rolling out blue/green deployments for some of the core services, and we intend to implement the same for every core and supporting service.

## Automated Testing

Besides unit test coverage on every project, we have multiple functional test suites that run in every environment; we run it on a staging environment before we deploy to production, and we run them again in production after finishing a deployment to ensure that everything works.

The highlights:

- We have thousands of unit tests in different projects.

- We use Pingdom probes that run every minute to check core functionality.

- We use a mix of Selenium and CodeceptJS-based functional tests before and after every deployment. The functional test suites test different API endpoints, authentication flows, identity providers, and much more.

<include src="TweetQuote" quoteText="Besides unit test coverage on every project, we have multiple functional test suites that run in every environment: staging before deploying to production and again in production after finishing deployment."/>

## CDN

Until 2017 we ran our own, custom-built CDN using NGINX, Varnish, and EC2 nodes in multiple regions. Since then, we transitioned to CloudFront, which has given us several benefits that include:

- More edge locations, which means less latency for our customers.

- Lower maintenance costs.

- Easier configuration.

There are a few downsides, like the fact that we need to run Lambdas to perform some configurations (like adding custom headers to PDF files and things like that). Still, the upsides definitely make up for that.

## Extend

One of the features we provide is the ability to run custom code as part of the login transaction, either via [_authentication rules_](https://auth0.com/docs/rules/current) or [_custom database connections_](https://auth0.com/docs/connections/database/custom-db). These features are powered by [_Extend_](https://goextend.io/), an extensibility platform that grew out of Auth0 and is now being used by other companies as well. With Extend, our customers can write anything they want in those scripts and rules, allowing them to extend profiles, normalize attributes, send notifications, and much more.

We have Extend clusters specifically for Auth0; they use a combination of EC2 auto-scaling groups, Docker containers, and custom proxies to handle requests from our tenants, processing thousands of requests per second and responding fast to variations of load. For more details about how this is built and run, check out this post on [how to build your own serverless platform](https://tomasz.janczuk.org/2018/03/how-to-build-your-own-serverless-platform.html).

## Monitoring

We use a combination of different tools for monitoring and debugging issues:

- CloudWatch

- DataDog

- Pingdom

- SENTINL

The vast majority of our alerts come from CloudWatch and DataDog.

We tend to configure CloudWatch alarms via TerraForm, and the main monitors we keep on CloudWatch are:

- HTTP errors from our main load balancers.

- Unhealthy instances in a target group.

- SQS processing delays.

CloudWatch is the best tool for alarms based on AWS-generated metrics (like ones from load balancers or autoscaling groups). CloudWatch alerts usually go to PagerDuty, and from PagerDuty to Slack/phones.

DataDog is a service we use to store and act on time-series metrics. We send metrics from Linux boxes, AWS resources, off-the-shelf services (like NGINX or MongoDB), and also custom services we have built (like our Management API).

We have many DataDog monitors. A few examples:

- Increase in response times in `$service` on `$environment`.

- Running out of space on `$volume` in `$instance` (`$ip_address`).

- Issue with `$process` on `$environment` / `$host` (`$ip_address`).

- Increase in processing time for `$service` on `$environment`.

- NTP drifting off / clock issue on `$host` (`$ip_address`).

- MongoDB replica-set change on `$environment`.

As you can see from the examples above, we have monitors on low-level metrics (like disk space) and high-level metrics (like MongoDB replica-set change, which alerts us if there was a change in the primary node definition, for example). We do much more and have some pretty sophisticated monitors around some services.

DataDog alerts are pretty flexible in their outputs and we usually send them all to Slack, sending to PagerDuty only those who should "wake people up" (like spikes of errors, or most things that we are sure that are having an effect on customers).

For logging we use Kibana and SumoLogic; we are using SumoLogic to record audit trails and many AWS-generated logs, and we use Kibana to store application logs from our own services and other "off-the-shelf" services like NGINX and MongoDB.

## The Future

Our platform evolved quite a bit in order to handle the extra load and the huge variety of use cases that are important to our customers, but we still have more room for optimizations.

Not only our platform grew, but our engineering organization increased in size: we have many new teams building their own services and are in need of automation, tooling, and guidance around scalability.
With that in mind, these are the initiatives in place for us to scale not only our platform but also our engineering practice:

- Build a Platform, PaaS style: As mentioned before, today we have different automation and deployment flows; this causes confusion and creates a barrier of entry for engineers as it's hard to experiment and scale up without touching too many repositories. We are developing a PoC for a platform (currently running on top of ECS) in which engineers can configure a YAML file and just deploy it to get computing resources, monitoring, logging, backups, and much more. All of that without having to configure it explicitly. This effort is in an early stage and might still change a lot (EKS?). However, we feel we are taking the right direction given our growing size and scalability constraints.

- Implement smoke tests for every new pull request: besides unit testing (that already runs on each new PR), we want to run integration tests on ephemeral environments wherever that's possible.

- Centralize our logging solution into just one provider. This might mean moving away from Kibana and using just SumoLogic, but we still need to evaluate feature set, data volume, and more.

- Automate metrics: Too much of our metric story is manual now: adding metrics-related calls to the code while deploying, and building dashboards and monitors using the DataDog interface. If we use a standard format and naming, we could do things like building dashboards/monitors automatically, extracting metrics from logs instead of explicitly adding calls to the code, and more.

- Ensure we have auto-scaling and blue/green deployments on every core service. This should come out-of-the-box from our new Platform, but while that is being built and tested we need to improve the scaling/deployment/rollback story for the core services that are still lacking in that regard.

<include src="asides/AboutAuth0" />


Auth0 Architecture: 5 Years In

diegopoza

System Engineer, geek, foodie, technology lover, speaker.

Sr Manager, Developer Advocacy

Diego Poza

Use penetration testing and 2FA and educate citizens and employees to better anticipate and avoid cyber threats.



On April 7, 2017, at a quarter to midnight, the city of Dallas was hacked.

The perpetrators accessed the City of Dallas's emergency management system and set off 156 blaring alarms—alarms intended to warn people in case of a tornado or hurricane.

It took over an hour and a half for city administrators to understand what had gone wrong and shut the sirens down.

Amid the ongoing digitization of our urban areas, the Dallas incident highlights one of the main dangers that a smart city—for all the good it can do—brings.

Without the right precautions, and without the right security, our smart cities can be just as vulnerable to hacking as our computers and mobile devices.

What happened in Dallas may have been the first high-profile incident of “city hacking,” but it certainly won't be the last.

## Why Security Is a Problem For Smart Cities

The rise of smart cities is intimately linked to the rise in production of Internet of Things (IoT) devices—as are its inherent security problems.

Your average IoT device is relatively cheaply produced. It's not built with the kind of security features you get on a Mac or Windows laptop or tablet or in a mobile phone. It is, however, connected to the internet.

These three factors have made IoT devices incredibly fertile cybercrime targets over the last decade or so.

In 2015, millions of children's names, genders, ages, photos, and parents' records (including home addresses) were compromised through a device known as the InnoTab—a kind of WiFi-enabled tablet for kids.

IoT devices are often trivially easy to access remotely because they're already connected to the internet and not built with cybersecurity in mind. Hackers don't even need to pull information from them. They can simply sit on the device and wait for it to gather information, or even requisition it for use in a distributed denial of service (DDoS) attack or botnet.

Cybersecurity researchers have found vulnerabilities in IoT devices in smart cities, too. Aside from the Dallas incident, significant issues have occurred in smart traffic signals and smart electricity meters. The number of attacks on infrastructure in the U.S. alone went from not even 200 in 2012 to 300 in 2015.

Today, advocates of smart cities are looking much more closely into the security of smart cities and how to build devices that can ensure our cities stay safe and protected—even as they get smarter. According to Gartner, 2.3 billion connected items were used in U.S cities throughout 2017. That number is only going to get bigger and bigger.

## Ensure Security For Critical Facilities

The most vulnerable locations in any smart city are the centers of utilities and power—power plants, water processing plants, and so on.

In Kiev in 2016, hackers shut down 20% of the city's power by hacking into an electrical substation.

Penetration testing is a common method that cities and municipalities use to test for vulnerabilities with their utilities. A security firm is hired to attempt to break in and gain access to the system. Afterward, they produce a report with their findings and give [recommendations for how to avoid the a real attack](https://www.redteamsecure.com/business-insider-rides-shotgun-as-redteam-security-hacks-the-power-grid/).

![Smart city -  crime of person gaining access to a facility](https://images.ctfassets.net/23aumh6u8s0i/1n7pLxG3VH1QfPNkEFt9TX/44b26808a6ffb50c7d924a0e3d40ad18/gaining-physical-access-to-facility)

Pen testing isn't just about lurking around a facility late at night and trying to gain physical access. It might also mean dropping a USB key, loaded with a virus, in the parking lot to see whether an employee happens to pick it up and stick it in their laptop; if they do, the key can be formatted to sit on the device as a keylogger, attempt to gain remote access, or send out phishing emails.

It's about social engineering—still one of the most effective ways of gaining access anywhere.

And it means, of course, more straightforward network and application penetration testing—trying to get in by remotely compromising the system itself.

## Two-Factor Authentication

Facilities that provide critical utilities, such as power and water, need to be made absolutely secure, but so does other essential infrastructure in smart cities—like subway transportation, street lights, and security cameras.

The essential technology of any smart city must employ cryptography to protect data. Otherwise, video feeds of your citizenry can wind up being streamed on the internet, or your street lights can end up flashing on and off for hours on end.

Data should be encrypted both at rest and in transit. Any systems that allow access from any parties must accept a username and a password and should go a step forward and enable two-factor authentication. Two-factor authentication is the easiest and most effective step you can take to prevent unauthorized access because it immediately cuts out the most obvious and available attack vectors.

![Two-factor authentication example using phone device auth to grant access](https://images.ctfassets.net/23aumh6u8s0i/HWYrg3Jdj6NOgoKwz1AgN/69deef407a90c08422882ec34e06392f/two-factor-authentication-using-smartphone)

[Two-factor authentication](https://auth0.com/learn/two-factor-authentication/), at root, is about ensuring that anyone accessing your systems has two methods of proving their identity. That might mean a username, password, and something like a biometric key or a one-time password delivered through an app on their phone, like [Auth0 Guardian](https://auth0.com/docs/multifactor-authentication/guardian) or Google Authenticator.

## Education For Citizens and Leaders

Ultimately, the best way to prevent most cyberattacks (on cities or anything else) from succeeding, or at least to mitigate the damages, is education.

Emails that look like they're from a C-suite executive at your company but have an odd-looking From: address, or USB drives that look like they've been forgotten in your office's parking lot: These are highly visible red flags that indicate that some person or group has gotten access to your systems or is trying to. They're also some of the most commonly successful attacks out there because many people don't recognize the signs for what they are.

When one person falls for a phishing email, it can cause huge ripple effects down the line as their contacts are emailed en masse and compromised as well.

Educating denizens about the common forms of cyberattacks and the ways to prevent falling victim to them is the number one way that cities—if they cannot prevent attacks from happening—can ensure that the effects of malicious acts do not ripple out and cause wider damage.

## The Future of Urban Cybersecurity

The cybersecurity challenges of the future are going to look bigger and much different than many of those we have today.

As smart devices proliferate and security vulnerabilities loom larger and larger, it's on all of us to make sure that the cities we are building—no matter how smart—are secure as well.

<include src="asides/AboutAuth0" />


How Do Smart Cities Tackle Cybersecurity?

00af6e085efbc34b55b184c779601fe2?s=200 avatar

00af6e085efbc34b55b184c779601fe2?s=200

O'Brian Kimokot

Let's learn how to test Python APIs with mocks.



**TL;DR:** In this article, we are going to learn the basic features of mocking API calls in Python tests. We'll start by exploring the tools required, then we will learn different methods of mocking, and in the end we will check examples demonstrating the outlined methods. The final code can be found on [this GitHub repository](https://github.com/kimobrian/Python-API-Testing).

## Introduction

A mock is a fake object that we construct to look and act like the real one. We swap the actual object with a mock and trick the system into thinking that the mock is the real deal.

By mocking out external dependencies and APIs, we can run our tests as often as we want without being affected by any unexpected changes or irregularities within the dependencies. Mocking also saves us on time and computing resources if we have to test HTTP requests that fetch a lot of data.

<include src="TweetQuote" quoteText="By mocking external dependencies, we can run tests without being affected by any unexpected changes or irregularities within the dependencies!"/>

### Setup

For this tutorial, we will require [Python 3](https://www.python.org/download/releases/3.0/) installed. Having it on our machine, let's set up a simple folder structure:

```sh
python-api-mocks/
├── users_test/
    └── test_users.py
    └── __init__.py
├── __init__.py
├── requirements.txt
├── users.py
```

We will make use of [virtualenv](https://virtualenv.pypa.io/en/stable/); a tool that enables us to create isolated Python environments. These environments help us to manage dependencies separately from the global packages directory. Let's first install `virtualenv`, then let's create a virtual environment for our project, and then let's activate it:

```sh
$ pip3 install virtualenv
$ virtualenv -p python3 venv # Create virtual environment
$ source venv/bin/activate # Activate virtual environment
```

After that, let's install the required packages:

```sh
$ pip install nose2 requests
```

To make future installations easier, we can save the dependencies to a `requirements.txt` file:

```sh
$ pip freeze > requirements.txt
```

* The `nose2` library extends the built-in Python `unittest` module to make testing easier. You can use `unittest` or other third-party libraries such as [`pytest`](https://docs.pytest.org/en/latest/) to achieve the same results.
* The `requests` library simplifies HTTP calls in Python.

For this tutorial, we will be communicating with a fake API on [JSONPlaceholder](http://jsonplaceholder.typicode.com/).

To find tests, `nose2` looks for modules whose names start with `test` in the current directories and sub-directories. In those modules, `nose2` will load tests from all `unittest.TestCase` subclasses, as well as functions whose names start with `test`.

### Test Driven Development (TDD)

TDD is an evolutionary approach to development that combines test-first development and refactoring. We write a test before we write just enough production code to fulfill that test. We then refactor the code to make the test pass. The main goal of TDD is the specification and not validation; it’s one way to think through our requirements before we write functional code. We will follow this approach and begin by writing a simple test to check our API's response's status code.

```python
# users_test/test_users.py
import unittest
from users import get_users


class BasicTests(unittest.TestCase):
    def test_request_response(self):
        response = get_users()

        # Assert that the request-response cycle completed successfully with status code 200.
        self.assertEqual(response.status_code, 200)


if __name__ == "__main__":
    unittest.main()
```

To run this test we can issue `nose2 --verbose`. The test will fail with an error since we are missing the module we are trying to test.

![Python failing test](https://images.ctfassets.net/23aumh6u8s0i/2CDe6IWAg2cUnwXQCksg0y/72decfc45992f4ef816002fbb309ca3c/error_test)

We then refactor the functionality to make it pass.

```python
# users.py

import requests

USERS_URL = 'http://jsonplaceholder.typicode.com/users'


def get_users():
    """Get list of users"""
    response = requests.get(USERS_URL)
    if response.ok:
        return response
    else:
        return None
```

We then re-run the tests again using `nose2 --verbose` and this time, our test will pass.

![Python passing test](https://images.ctfassets.net/23aumh6u8s0i/2WRWhG2IhXUNdk6mD6rqIw/7415689bc2c964323d418de4b14ca948/pass_test_no_mock)

Up to this point, we wrote and tested our API by making real API requests during the tests.

## Utilizing Mocks

The code is working as expected because, until this point, the test is actually making an HTTP request. Real-world applications will result to increased complexity, more tests, and more API calls. If we wrote a thousand tests for our API calls and each takes a second to fetch 10kb of data, this will mean a very long time to run our tests. It will also require more computing and internet resources which eventually slows down the development process. In any case, our server breaks down and we stop the development of our client application since we cannot test it. In this section, we will learn how to detach our programming logic from the actual external library by swapping the real request with a fake one that returns the same data. Let's explore different ways of using mocks in our tests.

### Using Decorators

The first method is the use of decorators:

```python
# users_test/test_users.py
import unittest
from users import get_users
from unittest.mock import patch


class BasicTests(unittest.TestCase):
    @patch('users.requests.get')  # Mock 'requests' module 'get' method.
    def test_request_response_with_decorator(self, mock_get):
        """Mocking using a decorator"""
        mock_get.return_value.status_code = 200 # Mock status code of response.
        response = get_users()

        # Assert that the request-response cycle completed successfully.
        self.assertEqual(response.status_code, 200)


if __name__ == "__main__":
    unittest.main()
```

Running `nose2` again () will make our test pass without modifying our functions in any way.

![Mock Python test with decorator](https://images.ctfassets.net/23aumh6u8s0i/2vVOfUMlzk90mQbKraKQVg/c9b44c92b862662800fbea75d387be34/pass_mock_test_decorator)

Here is how it works. First, we import the `patch()` function from the mock library. Next, we modify the test function with the `patch()` function as a decorator, passing in a string representation of the desired method (i.e. `users.requests.get`). In the function itself, we pass in a parameter `mock_get`, and then in the body of the test function, we add a line to set `mock_get.return_value.status_code = 200`.

So what actually happens when the test is run? To answer this question, first let's understand how the `requests` library works. When we call the `requests.get()` function, it makes an HTTP request and then returns an HTTP response in the form of a response object. The `get()` function itself communicates with the external server, which is why we need to target it. We need to make the mock to look and act like the `requests.get()` function.

When the test function is run, it finds the module where the requests library is declared, `users`, and replaces the targeted function, `requests.get()`, with a mock. The test also tells the mock to behave the way the function expects it to act. Looking at `get_users()`, we see that the success of the function depends on if our response has an `ok` property represented with `response.ok` which translates to a status code of 200. That is what the line `mock_get.return_value.status_code = 200` is doing. When the `status_code` property is called on the mock, it will return 200 just like the actual object. The `get_users()` function will return the response, which is the mock, and the test will pass because the mock response status code is 200.

### Using a Context Manager

In this example, we explicitly patch a function within a block of code, using a context manager. The `with` statement patches a function used by any code in the code block. When the code block ends, the original function is restored.

```python
# users_test/test_users.py   
import unittest
from unittest.mock import patch
from users import get_users


class BasicTests(unittest.TestCase):
    # ... other tests
    def test_request_response_with_context_manager(self):
        """Mocking using a context manager"""
        with patch('users.requests.get') as mock_get:
            # Configure the mock to return a response with status code 200.
            mock_get.return_value.status_code = 200

            # Call the function, which will send a request to the server.
            response = get_users()

        # Assert that the request-response cycle completed successfully.
        self.assertEqual(response.status_code, 200)


if __name__ == "__main__":
    unittest.main()
```

### Using a Patcher

Another way to patch a function is to use a patcher. We identify the source to patch and then we start using the mock. The patching does not stop until we explicitly tell the system to stop using the mock. This is more suitable when using the `setUp()` and `tearDown()` functions in tests where we can start the patcher in the `setup()` method and stop it in the `tearDown()` method.

```python
# users_test/test_users.py
import unittest
from unittest.mock import patch
from users import get_users


class BasicTests(unittest.TestCase):
    # ... other tests
    def test_request_response_with_patcher(self):
        """Mocking using a patcher"""
        mock_get_patcher = patch('users.requests.get')

        # Start patching 'requests.get'.
        mock_get = mock_get_patcher.start()

        # Configure the mock to return a response with status code 200.
        mock_get.return_value.status_code = 200

        # Call the service, which will send a request to the server.
        response = get_users()

        # Stop patching 'requests'.
        mock_get_patcher.stop()

        # Assert that the request-response cycle completed successfully.
        self.assertEqual(response.status_code, 200)


if __name__ == "__main__":
    unittest.main()
```

<include src="TweetQuote" quoteText="I just learned about different mocking techniques on Python!"/>

## Mocking a Whole Function

In the previous examples, we have implemented a basic mock and tested a simple assertion. In this section, we focus on mocking the whole functionality of `get_users()`. When using `@patch()`, we provide it a path to the function we want to mock. The function is found and `patch()` creates a `Mock` object, and the real function is temporarily replaced with the mock. When `get_users()` is called by the test, the function uses the `mock_get` the same way it would use the real `get()` method. That means that it calls `mock_get` like a function and expects it to return a response object.

```python
# users_test/test_users.py   
import unittest
from unittest.mock import patch, Mock
from users import get_users


class BasicTests(unittest.TestCase):
    # ... other tests
    def test_mock_whole_function(self):
        """Mocking a whole function"""
        mock_get_patcher = patch('users.requests.get')
        users = [{
            "id": 0,
            "first_name": "Dell",
            "last_name": "Norval",
            "phone": "994-979-3976"
        }]

        # Start patching 'requests.get'.
        mock_get = mock_get_patcher.start()

        # Configure the mock to return a response with status code 200 and a list of users.
        mock_get.return_value = Mock(status_code = 200)
        mock_get.return_value.json.return_value = users

        # Call the service, which will send a request to the server.
        response = get_users()

        # Stop patching 'requests'.
        mock_get_patcher.stop()

        # Assert that the request-response cycle completed successfully.
        self.assertEqual(response.status_code, 200)
        self.assertEqual(response.json(), users)


if __name__ == "__main__":
    unittest.main()
```

In this case, `get_users()` function that was patched with a mock returned a mock object response. Whenever the `return_value` is added to a mock, that mock is modified to be run as a function, and by default it returns another mock object. In this example, we made it more clear by explicitly declaring the Mock object: `mock_get.return_value = Mock(status_code=200)`. The response object has a `status_code` property, so we added it to the Mock.

The response object also has a `json()` function that returns a list of users. We added it to the mock and appended it with a `return_value`, since it will be called like a function. Notice that the test now includes an assertion that checks the value of `response.json()`. We want to ensure that the `get_users()` function returns a list of users, just like the actual server does.

## Mocking Third-Party Functions

The above example has been fairly straightforward. Envision a situation where we create a new function that calls `get_users()` and then filters the result to return only the user with a given ID. In such a case, we mock `get_users()` function directly. For `get_users()`, we know that it takes no parameters and that it returns a response with a `json()` function that returns a list of users. What we care most about is not its implementation details. but the fact that `get_users()` mock returns what the actual `get_users()` function would have returned.

```python
#users_test/test_users.py   
import unittest
from users import get_users, get_user
from unittest.mock import patch, Mock


class BasicTests(unittest.TestCase):
    @patch('users.get_users')
    def test_get_one_user(self, mock_get_users):
        """
        Test for getting one user using their userID
        Demonstrates mocking third party functions
        """
        users = [
            {'phone': '514-794-6957', 'first_name': 'Brant', 'last_name': 'Mekhi', 'id': 0},
            {'phone': '772-370-0117', 'first_name': 'Thalia', 'last_name': 'Kenyatta', 'id': 1},
            {'phone': '176-290-7637', 'first_name': 'Destin', 'last_name': 'Soledad', 'id': 2}
        ]
        mock_get_users.return_value = Mock()
        mock_get_users.return_value.json.return_value = users
        user = get_user(2)
        self.assertEqual(user, users[2])


if __name__ == "__main__":
    unittest.main()
```

In the above snippet, we mock the functionality of `get_users()` which is used by `get_user(user_id)`. When we run our tests with `nose2 --verbose`, our test passes successfully with the following implementation of `get_user(user_id)`:

```python
#users.py
import requests

# ... USERS_URL and get_users definitions ...


def get_user(user_id):
    """Get a single user using their ID"""
    all_users = get_users().json()
    for user in all_users:
        if user['id'] == user_id:
            return user
```

![Mock a whole Python function](https://images.ctfassets.net/23aumh6u8s0i/2mQrIikAt60mRRfCvgYU6u/f51dabaec4a5670bfe6a2db4bbada78c/mock_whole_function)

<include src="asides/Python" />

## Conclusion

Mocking API calls is a very important practice while developing applications and, as we could see, it's easy to create mocks on Python tests. This technique introduces several advantages including, but not limited to, faster development and saving of computing resources.


Mocking API calls in Python

9d2e715baab928f5bedb837bfcb70b2b

Gabor Soos

Learn how to test Components in Angular. We will start with writing isolated tests for a component and finish with integration tests for the rendered component.



<div class="alert alert-info alert-icon">
  <i class="icon-budicon-664"></i>
  <strong>Get the "Migrating an Angular 1 App to Angular 2 book" for Free.</strong> Spread the word and <a href="https://auth0.com/e-books/migrating-to-angular2">download it now!</a>
</div>

Components enable us to display content on our website. The Angular compiler parses component templates and
displays them according to the given state. The business logic inside the components can be tested with
traditional unit tests just like services. But what happens with the displayed HTML
from the template and the interaction with other components? In this tutorial I'll show you
how to test the rendered components, starting from isolated unit tests to fully integrated ones.

This article is the third part of a series in which
I share my experiences testing different building blocks of an Angular application.
It relies heavily on Dependency Injection based testing and it is recommended that you read
[the first part](https://auth0.com/blog/angular-2-testing-in-depth-services/)
if you are not familiar with the concepts.

- [Services](https://auth0.com/blog/angular-2-testing-in-depth-services/)
- [HTTP Services](https://auth0.com/blog/angular-testing-in-depth-http-services/)
- Components (this article)
- Pipes
- Routing

### The component we'll test

The component we will test is a login form. It doesn't directly access the Authentication service,
instead it just informs the parent component about the submission through an `Output` property.
The form consists of two fields: an email and a password field.
The email address can be preloaded through an `Input` property
if it is passed down from the wrapping parent component.

<p align="center">
  <img src="https://images.ctfassets.net/23aumh6u8s0i/NefimDEZKVVWDa8hgzpEo/31fbf004d320b3262d4509cda24729a3/login-form" alt="Angular Testing Framework"/>
</p>

The two fields are handled by a reactive form created in the component.
With reactive forms, we can add validation to the fields and access their values without touching the DOM.
I've chosen reactive forms because they are more flexible and easier to test than template-driven forms.
Template-driven forms can only be tested through the DOM, making test writing harder.

If you are not familiar with reactive forms, it is recommended to read
[this part from the official documentation](https://angular.io/docs/ts/latest/guide/reactive-forms.html).

The [`FormBuilder`](https://angular.io/docs/ts/latest/api/forms/index/FormBuilder-class.html)
is created inside the constructor and adds validation to the input fields.
When the `email` input changes, the [`ngOnChanges`](https://angular.io/docs/ts/latest/api/core/index/OnChanges-class.html)
lifecycle hook passes it down to the field.
Setting the value on one of the forms control also updates its value in the HTML input element.

```typescript
import { Component, EventEmitter, Input, Output } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';

@Component({
  selector: 'login-form',
  templateUrl: './login-form.template.html'
})
export class LoginFormComponent {

  private loginForm: FormGroup;

  constructor(private formBuilder: FormBuilder) {
    this.loginForm = this.formBuilder.group({
      email: ['', [Validators.required, Validators.email]],
      password: ['', Validators.required]
    });
  }

  @Input()
  email: string;

  @Output()
  submitted = new EventEmitter();

  ngOnChanges(change) {
    if (change.email) {
      this.loginForm.controls['email'].setValue(change.email.currentValue);
    }
  }

  onSubmit({ email, password }) {
    this.submitted.emit({ email, password });
  }
}
```

The template only includes tags that are necessary for the form to function.
The value of the `formControlName` property will be the reference name
when we access our inputs inside the form controls.
With the `[formGroup]` property, we fire up the form handling with the components `FormGroup` and
listen to form submissions with `(ngSubmit)`.
When we click on the submit button, Angular will catch the event and pass it to the `onSubmit` handler function.

```html
<form (ngSubmit)="onSubmit(loginForm.value)" [formGroup]="loginForm">
    <input type="text" formControlName="email" id="login-email">

    <input type="password" formControlName="password" id="login-password">

    <button type="submit">Log In</button>
</form>
```

### Isolated tests

If we just want to focus on the business logic, we can treat and test the component as a service.
The `Component` decorator extends the `Injectable` decorator, which means it can be created as a service.
We just have to pass the component to the `providers` array in the module dependencies.
When testing in isolation, the template never gets compiled.
It only gets the required dependencies through the constructor.

```typescript
import { LoginFormComponent } from './login-form.component';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';
import { TestBed, inject, async } from '@angular/core/testing';
import { Component } from '@angular/core';

describe('Isolated', () => {
  let subject: LoginFormComponent;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [LoginFormComponent],
      imports: [FormsModule, ReactiveFormsModule]
    });
  });

  beforeEach(inject([LoginFormComponent], (loginForm: LoginFormComponent) => {
    subject = loginForm;
  }));

  it('should send credentials on submit', () => {
    subject.submitted.subscribe(({ email, password }) => {
      expect(email).toEqual(expectedEmail);
      expect(password).toEqual(expectedPassword);
    });

    subject.onSubmit({ email: expectedEmail, password: expectedPassword });
  });
});
```

The test focuses on the method that is called when the form is submitted.
It only passes the given email and password to the `EventEmitter` after destructuring the input object.
We don't have to pass Jasmine's asynchronous `done` callback to the testcase
because the `EventEmitter` acts synchronously.

Isolated tests are good when you want to focus on the component's logic.
These tests are also much faster than any other solution.
The only downsides are that it won't detect errors in the template
nor check the interactions with other components.

### Shallow tests

If we also want to detect errors inside the template, but still focus on a single component,
shallow tests are the way to go.
The key difference compared to isolated tests is that here the component is compiled.

Inside the `beforeEach` block, the component class moves to the `declarations` property instead of `providers`.
Before we can create an instance of the component, it has to be compiled.
The `compileComponents` method does the task asynchronously. It can't be synchronous,
because templates and styles can be referenced with relative urls
and the fetching of these resources is asynchronous by nature.
We have to wait for these tasks to complete. We can do the waiting with the `async` helper function.
In the background, `async` creates a new zone
and waits until every asynchronous operation is finished within that zone.
This way, we don't have to fiddle with Jasmine's `done` callback.

```typescript
describe('Shallow', () => {
  beforeEach(async(() => {
    TestBed.configureTestingModule({
      declarations: [LoginFormComponent],
      imports: [FormsModule, ReactiveFormsModule]
    });
    TestBed.compileComponents();
  }));

  it('should send credentials on submit', () => {
    let fixture = TestBed.createComponent(LoginFormComponent);
    let component: LoginFormComponent = fixture.componentInstance;
    let element = fixture.nativeElement;

    fixture.detectChanges();

    element.querySelector('#login-email').value = expectedEmail;
    element.querySelector('#login-email').dispatchEvent(new Event('input'));
    element.querySelector('#login-password').value = expectedPassword;
    element.querySelector('#login-password').dispatchEvent(new Event('input'));

    fixture.detectChanges();

    component.submitted.subscribe(({ email, password }) => {
      expect(email).toEqual(expectedEmail);
      expect(password).toEqual(expectedPassword);
    });

    element.querySelector('button[type="submit"]').click();
  });
});
```

With the `createComponent` method, we will have access to the component instance(`componentInstance`)
and the generated HTML fragment (`nativeElement`). We test the same thing as before:
what is emitted on the output at form submission.
The big difference is that we fill the inputs and click the submit button.
Filling the inputs with valid data is necessary
because the form validation leaves the submit button disabled as long as the inputs contain invalid data.

To make the component work, we have to call the `detectChanges` method after every change.
The `detectChanges` method does the synchronization of the component instance and the generated HTML.
Otherwise the component won't know that the input's value has changed.
When we modify an input, triggering the `input` event manually is also necessary
because this is the event that Angular listens for.

Also before doing anything inside the `nativeElement`, we have to call `detectChanges` first.
Calling the method does the first round of property checks on the component and fills out the template based on it.

Finally, we can use the native DOM methods and selectors on the `nativeElement` property.

With shallow tests, we gain the ability to test the templates, but it comes with a price.
These tests run much slower by including the compilation step.

### Integration tests

The next step is to test the component through its interactions with other components.
With integration tests, not only the template, but inputs and outputs will also be tested.

The setup is very similar to shallow tests. We have to set up and compile components.
The difference is that we have one more component that uses the login form component inside its template.
The wrapper component passes down the predefined email address and listens for the submit event.

```typescript
describe('Integration', () => {
  @Component({
    selector: 'site',
    template: `<login-form [email]="email" (submitted)="onFormSubmit($event)"></login-form>`
  })
  class SiteComponent {
    email = expectedEmail;

    storedEmail: string;

    storedPassword: string;

    onFormSubmit({ email, password }) {
      this.storedEmail = email;
      this.storedPassword = password;
    }
  }

  beforeEach(async(() => {
    TestBed.configureTestingModule({
      declarations: [LoginFormComponent, SiteComponent],
      imports: [FormsModule, ReactiveFormsModule]
    });
    TestBed.compileComponents();
  }));

  it('should send credentials on submit', () => {
    let fixture = TestBed.createComponent(SiteComponent);
    let component: SiteComponent = fixture.componentInstance;
    let element = fixture.nativeElement;

    fixture.detectChanges();

    expect(element.querySelector('#login-email').value).toEqual(expectedEmail);

    element.querySelector('#login-password').value = expectedPassword;
    element.querySelector('#login-password').dispatchEvent(new Event('input'));

    fixture.detectChanges();

    element.querySelector('button[type="submit"]').click();

    expect(component.storedEmail).toEqual(expectedEmail);
    expect(component.storedPassword).toEqual(expectedPassword);
  });
});
```

The modification of the input fields is the same, but the assertions are different.
This time we don't write assertions for the login form, but write them for the wrapper component instead.
This way, we ensure the bindings are correct.

There is no considerable slowdown compared to shallow tests. Integration tests need a bit more setup upfront,
but we can test the interactions between the components.

<include src="asides/Angular" />

### Summary

We have learnt three methods to test Angular components.
The first and fastest is testing the component in isolation:
we don't compile the template, just focus on the callable methods, like with a service.
If we also want to test the template, we will have to compile that component.
These are shallow tests. They are slower, but test more parts.
The last missing aspect is the interaction with other components. This can be tested with integration tests.
The extra element here is that we need to write a wrapper component around the component under test
and observe it through the wrapping component.

Either type we choose, we have to find the right balance between speed and how deeply we test the components.
It is optimal if we test business through isolation tests
and add some shallow and integration tests to ensure interactions and the template are valid.

To see the tests in action, check out
[this GitHub repository](https://github.com/blacksonic/angular2-testing-ground "Angular testing ground").


Angular Testing In Depth: Components

Learn how to test HTTP services in Angular. We will start by writing tests for requests and finish by refactoring them to a cleaner format.



<div class="alert alert-info alert-icon">
  <i class="icon-budicon-664"></i>
  <strong>Get the "Migrating an Angular 1 App to Angular 2 book" for Free.</strong> Spread the word and <a href="https://auth0.com/e-books/migrating-to-angular2">download it now!</a>
</div>

When we write a web application, most of the time it has a backend.
The most straightforward way to communicate with the backend is with HTTP requests.
These requests are crucial for the application, so we need to test them.
More importantly, these tests need to be isolated from the outside world.
In this article I will show you how to test your requests properly and elegantly.

This article is the second part of a series in which
I share my experiences testing different building blocks of an Angular application.
It relies heavily on Dependency Injection based testing and
it is recommended that you read [the first part](https://auth0.com/blog/angular-2-testing-in-depth-services/)
if you are not familiar with the concepts.

- [Services](https://auth0.com/blog/angular-2-testing-in-depth-services/)
- HTTP Services (this article)
- [Components](https://auth0.com/blog/angular-testing-in-depth-components/)
- Pipes
- Routing

### Testing our first request

<p align="center">
  <img src="https://github.com/blacksonic/articles/raw/master/img/angular2-testing-http-services/github-logo.png" alt="Angular Testing Framework"/>
</p>

To get started we will test a basic request, the GET request.
It will call a parameterized url without a body or additional headers.
The [Github API](https://developer.github.com/v3/) has an endpoint for retrieving public profile information about users.
The profile information is returned in JSON format.

```typescript
import { Injectable } from '@angular/core';
import { Http, Response } from '@angular/http';
import 'rxjs/add/operator/map';

@Injectable()
export class GithubService {
  constructor(private http: Http) {}

  getProfile(userName: string) {
    return this.http
      .get(`https://api.github.com/users/${userName}`)
      .map((response: Response) => response.json());
  }
}
```

The ```getProfile``` method sends a GET request to the API and returns the response.
Every request made with the ```HttpModule``` returns an ```Observable.```
The returned value will always be a ```Response``` object, which can return the response body.
With the help of the ```json``` or ```text``` method we can transform the value of the Observable.

The first thing we have to do is to set up the test dependencies.
The ```Http``` dependency is required.
If we don't provide it, we will get this error message: ```No provider for Http!```.

```typescript
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [GithubService],
    imports: [HttpModule]
  });
});
```

The problem with the real ```HttpModule``` is that we will end up sending real HTTP requests.
It is an absolutely terrible idea to do this with unit tests, because it breaks the test's isolation from the outside world.
Under no circumstances will the result of the test be guaranteed.
For example, the network can go down and our well-crafted tests will no longer work.

Instead, Angular has a built-in way to fake HTTP requests.

```typescript
import { MockBackend, MockConnection } from '@angular/http/testing';
import { Http, BaseRequestOptions, Response, ResponseOptions, RequestMethod } from '@angular/http';

...

beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [
      GithubService,
      MockBackend,
      BaseRequestOptions,
      {
        provide: Http,
        useFactory: (mockBackend: MockBackend, defaultOptions: RequestOptions) => {
          return new Http(mockBackend, defaultOptions);
        },
        deps: [MockBackend, BaseRequestOptions]
      }
    ]
  });
});
```

Instead of providing ```Http``` as a module,
it is better to use the factory provider and pass the ```MockBackend``` instance to the ```Http``` constructor.
This way the fake backend captures every request and can respond accordingly.

Before writing the first test it is also important to get an instance of the ```MockBackend,```
because without it we won't be able to respond to requests.

```typescript
beforeEach(inject([GithubService, MockBackend], (github, mockBackend) => {
  subject = github;
  backend = mockBackend;
}));
```

Let's write the first test that checks the result of the request.

```typescript
it('should get profile data of user', (done) => {
  let profileInfo = { login: 'sonic', id: 325, name: 'Tester' };
  backend.connections.subscribe((connection: MockConnection) => {
    let options = new ResponseOptions({ body: profileInfo });

    connection.mockRespond(new Response(options));
  });

  subject.getProfile('blacksonic').subscribe((response) => {
    expect(response).toEqual(profileInfo);
    done();
  });
});
```

Requests made are available through the ```connections``` property of the fake backend as an ```Observable.```
When it receives the request through the ```subscribe``` method we can respond with a JSON object.

In our example only the response body is set. In addition, you can set the status and the headers of the request.

Another new element is the ```done``` callback that is passed into the test function.
It is needed when writing asynchronous tests.
This way the test doesn't end when the execution of the function ends.
It will wait until the ```done``` callback is called.
Of course, there is a timeout for hanging tests that don't call this ```done``` method within a given interval.

HTTP requests are asynchronous by nature,
but the fake backend we use responds to them synchronously (it calls the ```subscribe``` method synchronously).
You may wonder what makes the test asynchronous, then.

The answer is false positive tests.
If we comment out the response to the request, the test will still pass, even though we have an assertion.
The problem here is that the ```subscribe``` callback never gets executed if we don't respond to the request.

```typescript
it('should get profile data of user', () => {
  // backend.connections.subscribe...

  subject.getProfile('blacksonic').subscribe((response) => {
    expect(response).toEqual(profileInfo);
  });
});
```
### Checking the request

Until now we haven't made any assertions for the request.
For example, what was the called url, or what was the method of the request?
To make the test more strict we have to check these parameters.

```typescript
backend.connections.subscribe((connection: MockConnection) => {
  expect(connection.request.url).toEqual('https://api.github.com/users/blacksonic');
  expect(connection.request.method).toEqual(RequestMethod.Get);

  ...
});
```

The original ```Request``` object resides on the ```MockConnection``` object.
With its ```url``` and ```method``` property, we can add the assertions easily.

### Digging deeper

GET requests are good for retrieving data, but we'll make use of other HTTP verbs to send data.
One example is POST.
User authentication is a perfect fit for POST requests.
When modifying data stored on the server we need to restrict access to it.
This is usually done with a POST request on the login page.

<p align="center">
  <img src="https://github.com/blacksonic/articles/raw/master/img/angular2-testing-http-services/auth0-logo.png" alt="Angular Testing Framework"/>
</p>

Auth0 provides a good solution for handling user authentication.
It has a feature to authenticate users based on username and password.
To demonstrate how to test POST requests, we will send a request to the Auth0 API.
We won't be using their recommended package here, because it would abstract out the actual request,
but for real-world scenarios I would recommend using it.

```typescript
@Injectable()
export class Auth0Service {
  constructor(private http: Http) {}

  login(username: string, password: string) {
    let headers = new Headers({
      'Content-Type': 'application/json'
    });
    let options = new RequestOptions({ headers });

    return this.http
      .post(
        'https://blacksonic.eu.auth0.com.auth0.com/usernamepassword/login',
        { username, password, client_id: 'YOUR_CLIENT_ID' },
        options
      )
      .map((response: Response) => response.text());
  }
}
```

The main difference between this example and the previous one is that here we are sending a JSON payload to the server
and appending additional headers onto it.
We don't have to manually ```JSON.stringify``` the payload --- the request methods will take care of it.
The response will be in text format, so this time we don't have to convert anything to JSON.

Let's look at the test to see how we can check every detail of the request.

```typescript
it('should be called with proper arguments', (done) => {
  backend.connections.subscribe((connection: MockConnection) => {
    expect(connection.request.url).toEqual('https://blacksonic.eu.auth0.com.auth0.com/usernamepassword/login');
    expect(connection.request.method).toEqual(RequestMethod.Post);
    expect(connection.request.headers.get('Content-Type')).toEqual('application/json');
    expect(connection.request.getBody()).toEqual(JSON.stringify(
      {
        username: 'blacksonic',
        password: 'secret',
        client_id: 'YOUR_CLIENT_ID'
      }, null, 2
    ));
    ...
  });

  subject.login('blacksonic', 'secret').subscribe((response) => {
    expect(response).toEqual('<form />');
    done();
  });
});
```

The headers are also available on the ```Request``` object and can be checked one by one.
The payload can be retrieved with the ```getBody``` method.
This method always returns the body converted to a string, which will we see in the network traffic.
When we send JSON it will contain the output of the ```JSON.stringify``` method: printed with spaces and an indentation of two.

### Refactoring

The previous setup works, but it has multiple problems.

- For every service we test, the provider configuration will be exactly the same.
- The subscription to the outgoing connection responds the same immediately, regardless of the url.
- The assertions are verbose and hard to read.

Those who have tested their HTTP services in Angularjs may remember how simple the setup was for those tests.
Angularjs provided convenient methods for setting expectations on requests.

Angular doesn't have those built-in functionalities,
but very similar ones are present in the [ngx-http-test](https://github.com/blacksonic/ngx-http-test) library.

It can solve the problems mentioned earlier.
Let's look at the test with the library for the Github profile fetch.

```typescript
...
import { FakeBackend } from 'ngx-http-test';

describe('GithubServiceRefactored', () => {
  ...

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [
        GithubService,
        FakeBackend.getProviders()
      ]
    });
  });

  beforeEach(inject([GithubService, FakeBackend], (github, fakeBackend) => {
    subject = github;
    backend = fakeBackend;
  }));

  it('should get profile data of user', (done) => {
    backend
      .expectGet('https://api.github.com/users/blacksonic')
      .respond(profileInfo);

    subject.getProfile('blacksonic').subscribe((response) => {
      expect(response).toEqual(profileInfo);
      done();
    });
  });
});

```

The setup becomes a function call to ```FakeBackend.getProviders()```.
Setting the expectation hides the subscription and gives more readable methods like ```expectGET```.

The login test also becomes less verbose.

```typescript
it('should be called with proper arguments', (done) => {
  backend.expectPost(
    'https://blacksonic.eu.auth0.com.auth0.com/usernamepassword/login',
    {
      username: 'blacksonic',
      password: 'secret',
      client_id: 'YOUR_CLIENT_ID'
    },
    { 'Content-Type': 'application/json' }
  ).respond(responseForm);

  subject.login('blacksonic', 'secret').subscribe((response) => {
    expect(response).toEqual('</form>');
    done();
  });
});
```

## Aside: Securing Angular Applications with Auth0

Are you building a product with Angular? We at Auth0, can help you focus on what matters the most to you, the special features of your product. [Auth0](https://auth0.com/) can help you make your product secure with state-of-the-art features like [passwordless](https://auth0.com/passwordless), [breached password surveillance](https://auth0.com/breached-passwords), and [multifactor authentication](https://auth0.com/multifactor-authentication). [We offer a generous **free tier**](https://auth0.com/pricing) to get started with modern authentication.

We provide the simplest and easiest to use [User interface tools to help administrators manage user identities](https://auth0.com/user-management) including password resets, creating and provisioning, blocking and deleting users.

### Conclusion: What we've learned about Angular HTTP testing

In this tutorial, we managed to:

- setup tests and fake an HTTP backend
- write assertions for requests
- refactor the tests to be more readable

Angular has the tools to test HTTP requests, but still lacks the readable assertion methods that were present in Angularjs.
Until such methods are implemented, the [ngx-http-test](https://github.com/blacksonic/ngx-http-test) library can be used.

To see the tests in action check out
[this GitHub repository](https://github.com/blacksonic/angular-testing-ground "Angular testing ground").


Angular Testing In Depth: HTTP Services

joyce-echessa

Joyce Echessa

Learn how to test React applications with the Jest JavaScript testing framework.

Testing React Applications with Jest

Learn how to test services in Angular. We will start with setting up the environment and finish with using Dependency Injection.



<div class="alert alert-info alert-icon">
  <i class="icon-budicon-664"></i>
  <strong>Get the "Migrating an Angular 1 App to Angular 2 book" for Free.</strong> Spread the word and <a href="https://auth0.com/e-books/migrating-to-angular2">download it now!</a>
</div>

When I started developing and writing tests for Angularjs applications,
everything felt natural. The tools were mature and I easily got used to
developing applications in TDD ([Test-Driven Development](https://en.wikipedia.org/wiki/Test-driven_development)).
It gave me a high level of confidence, knowing that my application was working as I had imagined.
Just after Angular 2 came out and I learned the basics, I knew that the next step was to testing.

This article is the first part of a series in which
I share my experiences testing different building blocks of an Angular application.
We will start with simple use cases and then head for more complex ones.

- Services (this article)
- [Http Services](https://auth0.com/blog/angular-testing-in-depth-http-services/)
- [Components](https://auth0.com/blog/angular-testing-in-depth-components/)
- Pipes
- Routing

You may wonder why it is so important to write tests.

<p align="center">
  <img src="https://github.com/blacksonic/articles/raw/master/img/angular2-testing-services/tdd_guilty.png" alt="Angular Testing Driven Development"/>
</p>

With tests, we can ensure the correctness of our application: that the code does what it was designed to do.
We can guard against someone breaking our code by refactoring or
adding new features. This might have happened to you when someone added a small feature
or equivalent code transformations and nothing worked afterwards.
Writing tests can clarify the intention of the code by giving usage examples.
It can also reveal design flaws. When a piece of code is hard to test,
there might be a problem with the underlying architecture.

If you are new to Test-Driven Development, I would recommend reading the Test-Driven Development book by Kent Beck.
It gives a nice overview about the concepts and best practices.

### Choosing the framework to test Angular

<p align="center">
  <img src="https://github.com/blacksonic/articles/raw/master/img/angular2-testing-services/jasmine-mocha.png" alt="Angular Testing Framework"/>
</p>

The first thing we have to choose is the framework. The one suggested by Angular's core team is
[Jasmine](http://jasmine.github.io/edge/introduction.html).
For a long time it was the only supported testing framework, because test setups were hard wired into the framework.
Thanks to refactoring, now tests can also be written in [Mocha](https://mochajs.org/), or any other framework
that supports the ```beforeEach``` hook. This hook runs before every test run.
If your framework of choice doesn't support it, you have to add the following code snippet to your setup:

```typescript
import { resetFakeAsyncZone, TestBed } from '@angular/core/testing';

beforeEveryTestHook(() => {
  TestBed.resetTestingModule();
  resetFakeAsyncZone();
});
```

The first line within the hook resets the internal state of the Dependency Injection container.
It clears out any given provider or module.
If you are not familiar with Dependency Injection, I would recommend reading the
[official documentation](https://angular.io/docs/ts/latest/guide/dependency-injection.html) about it.

The second one clears out any remaining zone that fakes asynchronous operations like ```setTimeout```.
Detailed articles can be found on the Thoughtram blog about zones:
[Understanding zones](http://blog.thoughtram.io/angular/2016/01/22/understanding-zones.html) and
[Zones in Angular](http://blog.thoughtram.io/angular/2016/02/01/zones-in-angular-2.html).

For this series, we will be using Jasmine as the test framework.

### Writing the first Angular test

Let's look at our first service that will be tested.

```typescript
import { Injectable } from '@angular/core';

@Injectable()
export class Engine {
  getHorsepower() {
    return 150;
  }

  getName() {
    return 'Basic engine';
  }
}
```

It has two getter methods and the ```Injectable``` decorator.
The tests will check whether these getter methods work as intended.
The decorator is needed to utilize dependency injection.

In Jasmine, we can group our tests with the ```describe``` method.
Within this method, we can create test cases with the ```it``` function.
It is advised to place one class per file (the service) and group the tests around it (with ```describe```).
We can further group test cases around methods of the class
by placing ```describe``` statements inside the top ```describe``` block.
For now we will only group our tests around the class.

```typescript
import { Engine } from './engine.service';

describe('Engine', () => {
  it('should return it\'s horsepower', () => {
    let subject = new Engine();

    expect(subject.getHorsepower()).toEqual(150);
  });
});
```

In this setup, only plain instantiation is used; we will introduce dependency injection later.
For basic services, plain instantiation can be enough.

We call the ```getHorsepower``` method of the engine and check that it's equal to the expected value.

The first test is green and has been passed. Let's write another one for the ```getName``` method.

```typescript
it('should return it\'s horsepower', () => {
  let subject = new Engine();

  expect(subject.getName()).toEqual('Basic engine');
});
```

If you run the tests, a similar output will be on the terminal.

![Angular First Tests](https://github.com/blacksonic/articles/raw/master/img/angular2-testing-services/first_test_run.png)

Both tests have been passed; it is time to refactor.
There is duplication at the start of each Angular test. Instantiation is exactly the same,
we can move it out into a setup block.

```typescript
describe('Engine', () => {
  let subject: Engine;

  beforeEach(() => {
    subject = new Engine();
  });

  it('should return it\'s horsepower', () => {
    expect(subject.getHorsepower()).toEqual(150);
  });

  it('should return it\'s horsepower', () => {
    expect(subject.getName()).toEqual('Basic engine');
  });
});
```

The ```subject``` variable is declared at the start of the ```describe``` block, and the creation of the service
is moved to the ```beforeEach``` block. This way we don't have to do it manually every time.
It is common to move the creation of the test case subject to a separate method,
because it offloads the tests and makes them more readable.

### Using Dependency Injection

Creating services directly can be good if the subject under test has no or few, dependencies.
But if it has multiple dependencies, or a deeper dependency tree, setting up all the classes becomes tedious.
For these situations, we can use Angular's dependency injection management.

The ```Car``` class uses the ```Engine``` class in the constructor and its instance in the ```getName``` method.

```typescript
import { Injectable } from '@angular/core';
import { Engine } from './engine.service';

@Injectable()
export class Car {
  constructor(private engine: Engine) {}

  getName() {
    return `Car with ${this.engine.getName()}(${this.engine.getHorsepower()} HP)`;
  }
}
```

We check for the ```getName``` method's output in the test after we set up the dependency injection container.

```typescript
import { TestBed, inject } from '@angular/core/testing';
import { Engine } from './engine.service';
import { Car } from './car.service';

describe('Car', () => {
  let subject: Car;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [Engine, Car]
    });
  });

  beforeEach(inject([Car], (car: Car) => {
    subject = car;
  }));

  it('should display name with engine', () => {
    expect(subject.getName()).toEqual('Car with Basic engine(150 HP)');
  });
});
```

The difference here is that we configure the ```TestBed``` with the provided
services in the ```configureTestingModule``` method.
Only these classes can be instantiated with the ```inject``` method.
If we try to request something else, we get an error saying it is an unknown provider.

![Angular Testing Error](https://github.com/blacksonic/articles/raw/master/img/angular2-testing-services/test_failure_missing_dep.png)

We can request instances of the services in an array from the ```inject``` method.
In the callback, we get the instances in the same order as in the dependency array with the first parameter.
The type hint inside the  callback is only for IDE completion; it also works without it.
In the example, it is placed inside the ```beforeEach``` function, but it can also be added to the ```it``` block.

```typescript
it('should display name with engine', inject([Car], (car: Car) => {
  expect(car.getName()).toEqual('Car with Basic engine(150 HP)');
}));
```

### Mocking

In unit tests for Angular, we want to execute the code in isolation.
This means it is not dependent on big, complex objects and is not calling methods that rely on external systems
(like [HTTP calls](https://auth0.com/blog/angular-2-series-part-3-using-http/) or database access).
In these cases, we want to simulate the original behavior while skipping the underlying implementation.

When achieved, it is called mocking.
We don't have to do it manually. Jasmine provides tools to make it work.
Let's assume that the method of the ```Engine``` class has a call through to the server
and we want to mock it.

```typescript
...
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [Engine, Car]
  });

  spyOn(Engine.prototype, 'getHorsepower').and.returnValue(400);
  spyOn(Engine.prototype, 'getName').and.returnValue('V8 engine');
});

...

it('should display name with engine', () => {
  expect(subject.getName()).toEqual('Car with V8 engine(400 HP)');
});
```

We mock the class methods by calling the ```spyOn``` method on the class's prototype.
We also alter the return value of the function. This way the original method never gets called.
When mocking the prototype, it affects every instance of the class.

### Using Dependency Injection for Mocking

The previous solution for mocking can be achieved also with Angular's dependency injection mechanism.
We pass the ```Engine``` class as the provider token, but create the instances with a fake class.

```typescript
@Injectable()
class V8Engine {
  getHorsepower() {
    return 400;
  }

  getName() {
    return 'V8 engine';
  }
}
```

Then we pass this fake class to the setup.

```typescript
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [
      { provide: Engine, useClass: V8Engine },
      Car
    ]
  });
});
```

With this setup, the ```inject``` call will return an instance of ```V8Engine``` when asked for ```Engine```.
We can also use ```useFactory``` with a callback, or ```useValue``` with an instance, to accomplish the same result.
The only drawback here is that every method of the class must be implemented and changed
whenever the original class changes.
The original class can be extended optionally in order to override only specific methods.

<include src="asides/Angular" />

## Conclusion: What we've learned about Angular Testing

In this tutorial, we managed to:

- create a basic service and write tests for it
- use dependency injection in tests
- fake dependencies with Jasmine
- fake dependencies with dependency injection

If you follow the steps introduced in this article and write tests for your Angular application, you can sleep safe and sound.
The code will work as intended and when someone accidentally breaks it,
the tests will warn him that those changes are unsafe and shouldn't be committed until the tests are green again.

Jasmine will help you along the way with its easy syntax and batteries included (assertion and mocking library).

I hope this has convinced you that writing tests in Angular is not an overly complicated thing.

To make the start even easier, the code is available in
[this GitHub repository](https://github.com/blacksonic/angular-testing-ground "Angular testing ground").


Angular Testing In Depth: Services

How A/B Testing can help you taking decisions that make impact



Even large successful companies like Facebook understand and [utilize the power of A/B testing](https://fbinsights.files.wordpress.com/2016/07/facebookiq_placement-optimization.pdf) to ensure they stay ahead. **A/B testing** is a powerful tool you can use to drive more conversions from your site. 

The main goal of an A/B test is to test two or more variants of a page to determine which option works best. Starting your tests high-level before moving to test smaller details is the best way to maximize these conversions. 

It's important to make sure you choose a page that has [high traffic but low conversions](http://unbounce.com/a-b-testing/data-based-a-b-testing-process/) so that you're maximizing returns. If conversions are high but traffic low, then you need to find a way to drive more traffic which isn't something you can A/B test for. Low conversions and low traffic also won't benefit from an A/B test because without any traffic to gather data from, your A/B test won't have results.

<include src="TweetQuote" quoteText="Choose a page that has high traffic but low conversions, so that you're maximizing returns."/>

![Conversion-Traffic graphic](https://images.ctfassets.net/23aumh6u8s0i/Qr8MVveoPHIFnyydvD7No/acebffd65d8b957da32d073863a6c4a9/conversion-traffic-graph)

Source: [Unbounce](http://webinar.unbounce.com/analytics-for-conversions/?utm_source=Webinar&utm_medium=Blog-Post&utm_content=conversion-rate-optimization&utm_campaign=Hiten-Shah&_ga=1.218726042.2055948509.1470424864)

A/B testing one change at a time allows you to fully determine the effect of that variation. This way, you can combine the effects of multiple changes over time to optimize for the best page possible. But most people take this to mean they should A/B test minor changes to their site. Here we are going to show you why that thinking is wrong, and how big A/B tests allow you to get great data while making great changes to your site.

## The Problems With Starting Small

When deciding how to conduct A/B tests, Facebook knows to start big picture to have the biggest impact before even thinking about the smaller details. 

As we've mentioned, one of the most important [A/B testing rules](https://blog.kissmetrics.com/know-about-ab-testing/) is to test only one thing at a time. This way you'll make sure it's something that counts, rather than trying out multiple little things. 

The other problem with testing multiple small things like colors, small text, or call-to-action is that you can't be entirely sure what is really making a difference if at all. You're likely not making much of an impact. Conversion rates may be changed by a percent of a percent at most, if there is even enough traffic to make a statistically significant comparison.

![A/B Testing small changes](https://images.ctfassets.net/23aumh6u8s0i/5DKY6JTYpdFXnmnifrvPzQ/e8649f3fe04e8c14cc460f79befee649/small-changes)

For example, if we made the above changes — slight color and font resize — to the Auth0 homepage, it likely wouldn't make a difference. In fact, most people probably wouldn't even notice that we made a change. It certainly wouldn't effect the number of conversions.

When looking to A/B test, it's better to make big changes first to have the most significant effect. Small changes are good for optimizing further down the road, but those first need to be guided by larger-scale tests.

## Go Big, Then Go Small

Starting big will ensure that your A/B test will “[create results, not statistics](https://blog.kissmetrics.com/ab-testing-results/)” by focusing on the message you're trying to present, rather than the words you use to do so.

There are countless examples of impressive A/B testing case studies available online, but even in this compilation of “[10 kickass A/B testing case studies](https://vwo.com/blog/10-kickass-ab-testing-case-studies/),” the ones that made the biggest changes saw the biggest improvements. Testing the things that have the [biggest impact](https://blog.kissmetrics.com/ab-testing-introduction/) — such as headlines, graphics related to sales or product description — will present the biggest returns.

![Radical vs Incremental changes](https://images.ctfassets.net/23aumh6u8s0i/274U4RTIBWcC6dBDe6iW1h/2aaff2dce6c932fddb32eeb9adae6a06/radical-vs-incremental-changes)

Companies should also not be afraid to make radical changes to test a completely new idea. As shown in a study done by [conversion optimization platform Experiment Engine](https://www.experimentengine.com/blog/2016/08/02/what-exactly-are-companies-ab-testing/), radical changes are more likely to show impact. With more general idea testing, if the change doesn't work, it is easy to just not launch rather than having to re-do your entire page for a small change that proved unsuccessful. 

### How This Works For Any Industry

In any industry, starting [high-level](https://knowledge.hubspot.com/landing-page-user-guide-v2/how-to-ab-test-landing-pages) and testing the entire landing page can open many doors for things to A/B test further down the line. Making big changes can reveal [surprising and maybe even unintuitive results](http://unbounce.com/a-b-testing/surprising-a-b-test-results/) that you might've never expected. 

For web app automation service [Zapier](https://zapier.com/app/explore), completely changing their landing page gave them the boost they needed. Though they [received criticism](http://www.usertesting.com/blog/2015/06/09/homepage/) for having a simplistic landing page, this choice was actually a result of a surprising A/B test.

![Zapier Comparison](https://images.ctfassets.net/23aumh6u8s0i/45Yb6jXlGr0niIbVK2gg2N/5dc52e011faa3a6a278d2b30f474eb37/zapier-comparison)

They had compared the two above landing pages, thinking that the more informative page would lead to more conversions. Instead, they discovered that the simplistic page ended up leading to statistically significant more converted signups and active users than the other.

![Zapier Homepage Test Statistics](https://images.ctfassets.net/23aumh6u8s0i/6Tuu214p10GtTqUFjuUdJ/9e0028cfd2ff96553c5dd97388af18ab/zapier-homepage-test-stats)

Zapier isn't the only company to make big changes to their web page to find out what appeals most to users.

Health-related eCommerce store [Body Ecology](http://bodyecology.com/) added product categories to their homepage instead of a drop-down menu, [increasing revenue by 56.43%](https://vwo.com/blog/10-kickass-ab-testing-case-studies/).

![Body Ecology A/B testing in the home page](https://images.ctfassets.net/23aumh6u8s0i/3t6R6GvjUDFsA79ySbKCKJ/ce439588667b2a6f4dc49e8f70671d66/body-ecology)

Business training company [Dale Carnegie](http://www.dalecarnegie.com/) redesigned their main lead generation page to more clearly display the benefits of their course in a 2-column design. This change led to a [17.1% increase in downloads](https://blog.optimizely.com/2016/03/02/form-redesign-increase-leads/).

![Dale Carnegie A/B testing](https://images.ctfassets.net/23aumh6u8s0i/1tBodW8DxRQWGzhYrmmZzU/aa3d004ff198a3b81db4797523fafb3b/dale-carnegie)

[Spreadshirt](https://www.spreadshirt.com/), where people sell their T-shirt ideas online, [increased conversions by 606%](http://blog.wishpond.com/post/98235786280/50-a-b-split-test-conversion-optimization-case-studies) by simplifying the “how to” section of their website.

![Spreadshirt A/B Testing](https://images.ctfassets.net/23aumh6u8s0i/3Xd2Af2qYb3y8mPc5Td627/4b8bc0ca51c6af4ca53c70c8425a267b/spreadshirt)

By improving their value proposition and emphasizing a free new town, The Sims 3 [increased visitor registration by 128%](https://blog.kissmetrics.com/100-conversion-optimization-case-studies/).

![The Sims 3 A/B Testing](https://images.ctfassets.net/23aumh6u8s0i/3h8MrFLvXcaINrYQTmNdCO/87ee22bafd6b2a98d32021a7dbbb02ae/the-sims)

By making entirely new pages and A/B testing more general ideas, these companies were able to see a more immediate difference that they could then start to iterate and optimize. 

## How To Run An A/B Test 

There is a scientific process you can follow when [running A/B test](https://www.optimizely.com/ab-testing/) experiments:

1. **Conduct background research**: Use data from analytics to provide insight on what to test.
2. **Determine your goal:** Know what you're working towards and never test without a goal in mind.
3. **Construct a hypothesis:** Identify and prioritize reasons on why you think this variation will be more effective.
4. **Prepare your experiment:** Make the changes! Using a software platform can make creating these variations much easier.
5. **Run your experiment:** Run the A/B test. Make sure your visitors are split evenly and interactions with your site are measured accurately.
6. **Analyze your results:** Use the data collected to see if there was a statistically significant difference and determine how to move forward.

This process, similar to the experimental framework from [A/B Testing and Personalization Platform Optimizely](https://www.optimizely.com/), is very general and can be applied to any A/B testing situation.

![The A/B Testing process](https://images.ctfassets.net/23aumh6u8s0i/5hM22tci6A2Vr93fpdJWYx/c5bcd5937da3622aeb6df27450c884f4/ab-testing-process)

Following this process will make sure you are testing with a purpose and will learn something from the results, regardless of success. 

## A/B Test Everything — But Start With The Big Things

Starting your A/B tests high-level will give you the biggest returns quickly. By incorporating each successful change into the next A/B test, you will compound on these benefits to your conversions even more.

And the best part? If the change doesn't give the result you want, you can simply not launch the new page. Even if you get bad results, by testing, at least you know what doesn't work.

<include src="TweetQuote" quoteText="If the change doesn't give the result you want, you can simply not launch the new page."/>

The main takeaway message is that you are free to test anything on your website, so it's best to start big. You may learn that something you never expected is what appeals most to your customers.


"testing"