Por definición, las pruebas unitarias nos ayudan a asegurarnos de que una unidad de código en específico hace lo que debe de hacer. Por lo tanto, para crear pruebas unitarias sólidas debemos asegurarnos de aislar debidamente la pieza de código que queremos probar. No queremos que otros módulos (las dependencias) interfieran con el resultado de la unidad que estamos probando.

Sin embargo, puede resultar un trabajo complicado simular cada dependencia requerida por un módulo. Aquí es donde Proxyquire entra en acción.

Proxyquire es un módulo bastante útil, el cuál nos permite sustituir todas las dependencias requeridas por la unidad que estemos probando al importar dicha unidad. Si lo combinamos con Sinon, otro módulo de Node JS para pruebas, nos resultará mucho más fácil simular todas las dependencias y, por lo tanto, enfocarnos únicamente en el comportamiento del módulo que estamos probando.

Cómo funciona

Veamos un ejemplo para ilustrar cómo trabajan en conjunto Proxyquire y Sinon. Imaginemos que necesitamos desarrollar un módulo que lea/escriba la configuración de los usuarios desde/hacia un archivo. Vamos a crear ese módulo y sus respectivas pruebas unitarias.

El código (simplificado) para este gestor de configuraciones quedaría más o menos como sigue:

const fs = require('fs/promises');

module.exports = () => {
    const load = async () => {
        try {
                const rawSettings = await fs.readFile('settings.json');
                return JSON.parse(rawSettings);
            } catch (error) {
                return {};
            }
    };

    const save = async (settings = {}) => {
        const settingsStr = JSON.stringify(settings);
        fs.writeFile('settings.json', settingsStr);
    };

    return {
        load,
        save
    };
};

Como se observa, nuestro gestor de configuraciones depende del módulo fs de Node JS. Por lo tanto, el comportamiento de este módulo externo podría afectar los resultados de las pruebas unitarias que realicemos para este módulo que acabamos de crear. Idealmente, buscaríamos evitar esto, ya que: 1) el comportamiento del módulo fs (o cualquier otro módulo que nuestra unidad a probar requiera) está completamente fuera de nuestras manos (por ejemplo, conexiones a APIs externas, bases de datos o sistemas de archivos, como en este ejemplo) y 2) necesitamos enfocarnos en probar una única unidad (y no en sus dependencias).

Ahora veamos cómo podemos probar nuestro módulo sustituyendo sus dependencias y evitando así comportamientos no deseados.

(Nota: para este ejemplo, utilizaremos Mocha + Chai como marco + biblioteca para pruebas unitarias. Luego, haremos uso de Sinon y Proxyquire para sustituir las dependencias del gestor de configuraciones y probarlo de manera aislada.)

Pero primero lo primero: para instalar todas las dependencias de desarrollo que vamos a usar para las pruebas podemos usar el siguiente comando:

npm install mocha chai sinon sinon-chai proxyquire

Después, viene el código:

const chai = require('chai');
chai.use(require('sinon-chai'));
const { expect } = chai;
const sinon = require('sinon');
const proxyquire = require('proxyquire').noCallThru();

describe('Settings manager', () => {
    const settingsPath = 'settings.json';
    let settingsFake;
    let fsFake;
    let settingsManager;

    beforeEach(() => {
        settingsFake = {
            language: 'English'
        };

        // [1] Con Sinon, se crea un doble del módulo 'fs'.
        fsFake = {
            // [2] Se crea un doble de la función 'readFile'.
            readFile: sinon.stub().callsFake(path => JSON.stringify(settingsFake)),
            // [3] Se crea un doble de la función 'writeFile'.
            writeFile: sinon.stub().callsFake((path, settings) => {
                settingsFake = JSON.parse(settings);
            })
        };

        // [4] Se carga el módulo gestor de archivos con Proxyquire.
        settingsManager = proxyquire('../../settingsManager', {
            'fs/promises': fsFake
        })();
    });

    it('loads settings', async () => {
        const settings = await settingsManager.load();

        // Se revisa que la función  haya sido llamada correctamente.
        expect(fsFake.readFile).to.have.been.calledOnceWith(settingsPath);
        // Se revisa que las configuraciones regresadas sean correctas.
        expect(settings).to.be.an('object').that.deep.equals(settingsFake);
    });

    it('saves settings', async () => {
        const defaultSettings = {
            language: 'English'
        };
        const updatedSettings = {
            language: 'Japanese'
        };
        const updatedSettingsStr = JSON.stringify(updatedSettings);

        // Primero, se revisa que las configuraciones originales coincidan con las configuraciones por defecto.
        let settings = await settingsManager.load();
        expect(settings).to.be.an('object').that.deep.equals(defaultSettings);

        // Luego, se actualizan las configuraciones...
        await settingsManager.save(updatedSettings);
        // ...y se revisa que la función haya sido llamada correctamente.
        expect(fsFake.writeFile).to.have.been.calledOnceWith(settingsPath, updatedSettingsStr);

        // Finalmente, se revisa que las configuraciones hayan sido actualizadas correctamente.
        settings = await settingsManager.load();
        expect(settings).to.be.an('object').that.deep.equals(updatedSettings);
    });
});

Aquí una pequeña explicación de lo que sucede en el código:

Primero, creamos un módulo fs falso con Sinon (1), el cuál contiene versiones simplificadas de las funciones que utiliza nuestro gestor de configuraciones. Creamos una función readFile (2) con comportamiento simplificado: recibe una ruta como parámetro (el cuál es completamente ignorado) y únicamente regresa el objeto falso de configuraciones convertido a cadena. También creamos una función writeFile (3) con un comportamiento, igualmente, simplificado: recibe una ruta y las configuraciones a almacenar como parámetros y, simplemente, actualiza el objeto falso de configuraciones con las configuraciones recibidas.

Nuestro objetivo no es probar estas funciones del módulo fs, por lo que podemos simplificar su comportamiento para que funcionen como lo esperamos y no afecten el resultado del módulo que sí nos interesa probar.

Finalmente, cargamos el módulo gestor de configuraciones con Proxyquire (4) para inyectar las dependencias falsas, evitando así que se carguen las dependencias reales.

De esta manera podemos evitar comportamiento no deseado y enfocarnos en probar el módulo que realmente nos interesa. Con esto podemos ejecutar nuestras pruebas unitarias las veces que sean necesarias y esperar el mismo resultado con cada ejecución.

¡Así es como podemos simular dependencias para nuestras pruebas unitarias en Node JS con Proxyquire y Sinon!

¡Gracias por leer hasta aquí! Cualquier comentario o duda, háganmelo saber.

Imagen de portada por Zafiro Luna.

Para profundizar en el tema:

• Repositorio en Github de Proxyquire

• Documentación de Sinon

By definition, unit tests help us ensure a single unit of code does what it has to do. Therefore, to create solid unit tests we must assure we're isolating the piece of code we want to test as much as possible. We don't want other modules (the required dependencies) to interfere with the outcome of the unit we're testing.

However, it could be a bit tricky to mock every single dependency a module requires. That's where Proxyquire comes into action.

Proxyquire is a handy module that lets us proxy all the dependencies required by the module we're testing when importing it. If we combine it with Sinon (another helpful Node JS module for testing), we can now stub with ease any dependencies, making it easy to focus on the behavior of the unit we're testing in isolation.

How it works

Let's use an example to illustrate how Proxyquire and Sinon work together. Imagine we need a module to retrieve/store user settings from/into a file for our application. Let's create that module along with its corresponding unit test.

The (simplified) code for this settings manager module would be as follows:

const fs = require('fs/promises');

module.exports = () => {
    const load = async () => {
        try {
                const rawSettings = await fs.readFile('settings.json');
                return JSON.parse(rawSettings);
            } catch (error) {
                return {};
            }
    };

    const save = async (settings = {}) => {
        const settingsStr = JSON.stringify(settings);
        fs.writeFile('settings.json', settingsStr);
    };

    return {
        load,
        save
    };
};

As we can see, our new module relies on Node JS' built-in file system module. Therefore, the behavior of this external module could affect the unit tests for the settings manager module we just created. Ideally, we don't want this to happen, because: 1) the behavior of the fs module (or any other module required by the unit being tested) could be completely out of our hands (say, a connection to an external API, database, file system, etc.), and 2) we want to focus our tests on a single unit (not its dependencies).

So, let's see how we can test our module by mocking its dependencies, avoiding unwanted behavior.

(Note: for this example, we're going to use Mocha + Chai as the test framework + library. Then, we're adding Sinon and Proxyquire for mocking the dependencies of the settings manager and testing it in isolation.)

First things first: to install all the dev dependencies we're going to use for testing we can use the following command:

npm install mocha chai sinon sinon-chai proxyquire

Then comes the code (some test cases are omitted for simplicity):

const chai = require('chai');
chai.use(require('sinon-chai'));
const { expect } = chai;
const sinon = require('sinon');
const proxyquire = require('proxyquire').noCallThru();

describe('Settings manager', () => {
    const settingsPath = 'settings.json';
    let settingsFake;
    let fsFake;
    let settingsManager;

    beforeEach(() => {
        settingsFake = {
            language: 'English'
        };

        // [1] Create a fake 'fs' module with Sinon.
        fsFake = {
            // [2] Stub the 'readFile' function.
            readFile: sinon.stub().callsFake(path => JSON.stringify(settingsFake)),
            // [3] Stub the 'writeFile' function.
            writeFile: sinon.stub().callsFake((path, settings) => {
                settingsFake = JSON.parse(settings);
            })
        };

        // [4] Load the settings manager module with Proxyquire.
        settingsManager = proxyquire('../../settingsManager', {
            'fs/promises': fsFake
        })();
    });

    it('loads settings', async () => {
        const settings = await settingsManager.load();

        // Check that the stubbed function was called properly.
        expect(fsFake.readFile).to.have.been.calledOnceWith(settingsPath);
        // Check that the returned settings are correct.
        expect(settings).to.be.an('object').that.deep.equals(settingsFake);
    });

    it('saves settings', async () => {
        const defaultSettings = {
            language: 'English'
        };
        const updatedSettings = {
            language: 'Japanese'
        };
        const updatedSettingsStr = JSON.stringify(updatedSettings);

        // First, check that the original settings are equal to the default ones.
        let settings = await settingsManager.load();
        expect(settings).to.be.an('object').that.deep.equals(defaultSettings);

        // Then, update the settings...
        await settingsManager.save(updatedSettings);
        // ..and check that the stubbed function was called properly.
        expect(fsFake.writeFile).to.have.been.calledOnceWith(settingsPath, updatedSettingsStr);

        // Finally, check that the settings where updated correctly.
        settings = await settingsManager.load();
        expect(settings).to.be.an('object').that.deep.equals(updatedSettings);
    });
});

Here's a quick explanation of what happens on the above code:

First, we create a fake fs module with Sinon (1) which contains stubbed versions of the functions we use in our module. We have a stubbed readFile function (2) with a simplified behavior: it receives a path as a parameter (which is completely ignored) and it just returns the stringified settings fake. We also have a stubbed writeFile function (3) with a simplified behavior as well: it receives a path and the settings to save as parameters and it just updates the settings fake with the parsed settings received. We're not interested in testing these fs functions for these tests, so we can simplify their behavior as we would expect it to be for our module to work properly.

Finally, we load our settings manager module with Proxyquire (4) to inject the stubbed dependencies, preventing the real ones to be loaded instead.

This way we can avoid unexpected behavior from the modules required by the unit being tested and focus on its functionality. We can now run our unit tests as many times as we want and expect the same results every time.

That's how we can mock dependencies for creating unit tests in Node JS with Proxyquire and Sinon!

Thanks for reading! Let me know if you have any thoughts or questions!

For further reading:

• Proxyquire's Github repository

• Sinon documentation

In this series, I will share with you everything I know about RESTful APIs: from what they are and why they came to be, to how they work and why they are so convenient for building anything from small websites to entire platforms.

If you aim to create useful APIs or want to make the most out of the ones already out there, I invite you to read on!

Versión en español

Part 1: How RESTful APIs came to be

The beginning (or REST: a bit of history)

Before RESTful APIs, there was REST; before REST, there had to be... chaos!

Back in the 90s, the number of users surfing the World Wide Web saw a rapid increase. The Internet was the new kid on the block and everyone was loving it!

Everyone, except programmers.

The development of general-purpose websites suddenly became a demanding occupation. Sooner than later, the huge growth of the web ecosystem made a big problem clear: there weren't well-defined, standardized ways of building and communicating applications throughout the Internet.

Luckily, several nice folks began working on this, consolidating some of the most fundamental standards of the web. One such folk, Roy Thomas Fielding, who was part of the team that specified the standards of HTTP 1.0 and 1.1, started working on a thesis about an architectural style for building and communicating systems on the Internet.

Enter REST.

Going RESTful! (or REST: a definition)

Fielding presented his dissertation "Architectural Styles and the Design of Network-based Software Architectures" in 2000. There, he defined the Representational State Transfer (REST) architectural style as a set of constraints: a sort of guide for designing and building systems over the Internet.

We can say that REST is more about defining how to do things (an architectural style), rather than representing an implementation by itself.

Every piece of software that follows (all or most of) the constraints defined by the REST architectural style (aka every implementation of REST) is... drum roll... RESTful!

But, what are those so-called constraints defined by REST anyway? I'm glad you asked! Let's talk about the 6 constraints that every RESTful implementation should follow:

1. Client-Server. This is our starting point: how the architecture should be. Following a client-server architecture, we must separate the user interface concerns (the client) from the data storage concerns (the server). This separation will allow every component (client or server) to evolve independently, thus, providing portability and scalability.

2. Stateless. Having defined a client-server architecture, this second constraint states that the communication between the client and the server must be stateless: every request made by the client must contain all the information needed by the server to process it. Requests cannot rely on any context on the server: they must be independent.

3. Cache. As a nice complement to the stateless communication between clients and servers, the cache constraint lets us tag certain resources returned by the server as cacheable or non-cacheable. A cacheable resource can be safely reused by the client for identical requests later on. This can improve speed and efficiency by reducing the number of interactions between the client and the server.

4. Uniform Interface. This is the constraint that differentiates REST from other architectural styles. It tells us that, regardless of what resources the server is providing, there must always be a uniform interface that defines how these resources are presented and, thus, how they should be consumed by the clients. This uniform interface is, in turn, defined by four constraints:

   • Identification of resources: Every resource must be identifiable by a unique ID.

   • Manipulation of resources through representations: A client should be able to manipulate resources through their representations returned by the server.

   • Self-descriptive messages: Interactions between client and server should provide enough information (media-type, HTTP verb, etc.) to make clear the intention of the request.

   • Hypermedia as the engine of application state: Hypertext/hyperlinks provided by the server as part of the responses should specify what can be performed next for any given resource.

5. Layered System. This constraint allows us to break the architecture into separate layers with a specific task each. Every layer is independent and knows nothing beyond the immediate layer they interact with. With this in mind, we can have a layer for managing authorization, for example; another one for load balancing, and so on. This also provides portability and scalability for each component on the layered system.

6. Code-On-Demand. This last constraint is an optional one. It provides the client with the possibility to extend its functionality by downloading and executing code in the form of applets or scripts. This allows the clients to be more lightweight by reducing the features implemented directly on them.

Now that we know what RESTful means, we are ready to talk about APIs, RESTful APIs!

Defining RESTful APIs (or what you came for, finally!)

We're almost there!

With a clear idea of what REST is and what RESTful means, there's only one last bit we need to clarify: what are APIs?

An Application Programming Interface (API) is a set of rules that define how two pieces of software must communicate with each other. We can see it as a sort of contract that each part has to follow to transfer data between them.

Cool! Now we have a decent understanding of all the concepts we need to finally define a RESTful API!

Here's a simple definition:

A RESTful API is a way of communicating two applications over the Internet under the constraints defined by REST. In other words, RESTful APIs are a way to define how web services present their resources and how clients should consume those resources over the Internet.

So, although not exactly a standard, this implementation of REST in the form of APIs was a solution to the problem of communicating applications over the Internet. Not the only solution, though: SOAP, for instance, was already out there by the time RESTful APIs came out. But that's a story for another article...

What's next? (or How RESTful APIs work)

For the next part of the series, I'm planning on presenting a deeper explanation of how these APIs work: I'll write about how they stick to the REST constraints mentioned before, including concepts like resources, HTTP methods, etc., so that you can actually consume or even create your RESTful APIs.

I will finally end this series with a brief conclusion on why RESTful APIs are so useful nowadays. Should you always use them? Should you not?

...

I hope this article helped you have a better idea of what a RESTful API is. If you have any comments or thoughts on this article or if you have a specific topic you'd like me to write about, please let me know!

Thank you so much for reading this far! Have a great day!

All images used in this article, including the cover, were designed specifically for this blog by Zafiro Luna.

En esta serie compartiré todo lo que sé sobre APIs RESTful: desde qué son y cómo surgieron, hasta cómo trabajan y por qué resultan convenientes para desarrollar cualquier tipo de aplicación web.

Si deseas crear APIs o sacar el mejor provecho de las APIs ya existentes, ¡te invito a que sigas leyendo!

English version

Parte 1: Cómo surgieron las APIs RESTful

El inicio (o REST: un poco de historia)

En la década de los 90s, el número de usuarios navegando la web aumentó drásticamente. Internet era el nuevo chico en el barrio ¡y todos lo amaban!

Todos, excepto los programadores.

El desarrollo de sitios web de propósito general se convirtió, de un momento a otro, en una ocupación demandante. Más temprano que tarde, el crecimiento acelerado del ecosistema web dejó ver un problema importante: en aquel momento no existían maneras bien definidas, estandarizadas, de construir y comunicar aplicaciones a través de Internet.

Afortunadamente, algunas personas comenzaron a atacar este problema, consolidando algunos de los estándares fundamentales de la web. Una de estas personas, Roy Thomas Fielding, quien fuera parte del equipo que definió los estándares de HTTP 1.0 y 1.1, comenzó a trabajar en una tesis sobre un estilo arquitectónico para construir y comunicar sistemas en Internet.

Comienza REST.

¡Modo RESTful! (o REST: una definición)

Fielding presentó su disertación "Architectural Styles and the Design of Network-based Software Architectures" en el 2000. Ahí, definió el estilo arquitectónico de Transferencia de Estado Representacional (REST, por sus siglas en inglés) como un conjunto de reglas: una especie de guía para diseñar y construir sistemas sobre Internet.

Podríamos decir que REST define cómo hacer las cosas (un estilo arquitectónico) en lugar de representar una implementación por sí mismo.

Cualquier pieza de software que siga (todas o la mayoría de) las reglas definidas por REST (es decir, cualquier implementación de REST) es... redoble de tambores... ¡RESTful!

Pero, ¿cuáles son esas dichosas reglas definidas por REST? ¡Me alegra que lo preguntes! Hablemos, entonces, sobre las 6 reglas que toda implementación de REST debe seguir:

1. Cliente-Servidor. Este es nuestro punto de partida: cómo debe ser la arquitectura. Siguiendo una arquitectura Cliente-Servidor, debemos separar las tareas relacionadas con la interfaz de usuario (el cliente) de las tareas del almacenamiento de datos (el servidor). Esta separación permitirá a cada componente (cliente o servidor) evolucionar de manera independiente, aportando, por lo tanto, portabilidad y escalabilidad.

2. Carencia de Estado. Habiendo definido una arquitectura cliente-servidor, esta segunda regla indica que la comunicación entre el cliente y el servidor debe carecer de estado: cada petición hecha por el cliente debe contener toda la información que el servidor necesite para procesarla. Las peticiones no deben depender de ningún contexto en el servidor: deben de ser independientes.

3. Caché. Como un buen complemento a la comunicación carente de estado entre clientes y servidores, esta regla nos permite etiquetar a un recurso regresado por el servidor como cacheable o no cacheable. Un recurso cacheable puede ser reutilizado sin problema por el cliente para peticiones idénticas en el futuro. Esto permite un incremento en la velocidad y la eficiencia al reducir las interacciones con el servidor.

4. Interface Uniforme. Esta es la regla que realmente diferencia a REST de otros estilos arquitectónicos. Básicamente nos dice que, sin importar qué recurso provea el servidor, siempre debe existir una interface uniforme que defina cómo son presentados esos recursos y, por lo tanto, cómo deben ser consumidos por el cliente. Esta interface uniforme queda definida, a su vez, por 4 reglas:

   • Identificación de Recursos: Cada recurso debe distinguirse por un identificador único.
   • Manipulación de recursos a través de representaciones: Un cliente debe poder manipular un recurso a través de sus representaciones, las cuáles regresa el servidor.
   • Mensajes auto-descriptivos: Las interacciones entre el cliente y el servidor deben proveer suficiente información (tipo de medios, verbo de HTTP, etc.) para dejar clara la intensión de la petición.
   • Hypermedia como motor del estado de la aplicación: Los hipertextos/hipervínculos proporcionados por el servidor como parte de una respuesta deben especificar qué acciones se pueden tomar en el futuro para un recurso dado.

5. Sistema por capas. Esta regla nos permite romper la arquitectura en capas separadas, cada una a cargo de una tarea en específico. Cada capa es independiente y no tiene conocimiento del sistema más allá de la capa aledaña con la que interactúa: son independientes. Con esto en mente, podemos tener una capa que maneje la autorización, por ejemplo; otra encargada del balanceo de carga y así sucesivamente. Esto permite aumentar la portabilidad y escalabilidad para cada componente del sistema.

6. Código bajo demanda. Esta última regla es opcional. Le permite al cliente extender su funcionalidad descargando y ejecutando código en la forma de applets o scripts. Esto permite al cliente ser más ligero al reducir las funcionalidades implementadas directamente por él.

Ahora que entendemos mejor lo que RESTful significa, estamos listos para hablar sobre APIs, APIs RESTful.

Definiendo las APIs RESTful (o lo que estabas esperando, ¡por fin!)

¡Casi estamos listos!

Ahora que tenemos una mejor idea de lo que es REST y lo que significa RESTful, sólo nos queda un concepto por revisar: ¿qué es una API?

Una Interfaz de Programación de Aplicaciones (API, por sus siglas en inglés) es un conjunto de reglas que definen cómo deben comunicarse dos piezas de software. Podemos definirla como una especie de contrato que cada parte debe seguir para poder transferir datos entre ellas.

¡Genial! ¡Ahora tenemos una idea clara de todos los conceptos que necesitamos para definir una API RESTful!

Aquí va una sencilla definición:

Una API RESTful es una manera de comunicar dos aplicaciones en Internet bajo las reglas definidas por REST. Dicho de otro modo, las APIs RESTful definen la manera en la que los servicios web deben exponer sus recursos y cómo los clientes deben consumir dichos recursos en Internet.

Entonces, aunque no se trata propiamente de un estándar, esta implementación de REST en la forma de APIs representó una solución al problema de comunicar dos aplicaciones en Internet. No fue la única solución, cabe aclarar: ya se hablaba de SOAP, por ejemplo, cuando las APIs RESTful apenas aparecían. Sin embargo, esa es una historia para otro artículo...

¿Qué sigue? (o Cómo funcionan las APIs RESTful)

Para la siguiente entrega de esta serie planeo hablar más a fondo de cómo funcionan estas APIs: escribiré a detalle sobre cómo implementan las reglas definidas por REST mencionadas anteriormente, incluyendo conceptos como recursos, métodos HTTP, etc. para que te sea más fácil construir tu propia API RESTful o consumir alguna existente.

Finalmente, terminaré esta serie con una breve conclusión sobre por qué las APIs RESTful son tan relevantes en la actualidad. ¿Deberías usarlas siempre o no?

...

Espero que este artículo te haya sido de utilidad para entender mejor el concepto de una API RESTful. Cualquier comentario o duda al respecto, déjamelo saber en los comentarios. De igual manera, si hay algún tema sobre el que te gustaría que escribiera, no dudes en hacérmelo saber.

¡Muchas gracias por leer hasta aquí! ¡Que tengas un excelente día!

Todas las imágenes utilizadas en este artículo, incluyendo la portada, fueron diseñadas específicamente para este blog por Zafiro Luna.