Code Review

# Many small pull requests

Okay, so you are working on a new feature. Because your team operates using a
pull request-based workflow, someone needs to review your code before it lands
in the main branch and is released to all users. In the last retrospective,
there was a lot of frustration among peers because code reviews usually take
hours or even days to complete, and still, there is a lot of rubber-stamping or
minor comments about code style (things that could be easily automated with
better linters).

This time, you will try to approach it a bit differently and optimize for
reviewing rather than your own immediate productivity (which gets hurt in the
long term anyway due to delays in code review). Based on your experience as a
reviewer, code reviews start to get complicated not when they involve many file
changes but when they change multiple behaviors at the same time. For example, a
pull request with 300 file changes where you're simply renaming a constant is
much easier to review than a pull request with 4 file changes that modify four
different system behaviors.

This time, you plan to slice your work in a way that you can create more than
one single pull request, ensuring each pull request only introduces one new
behavior into the system (a variable rename, a change to existing logic). The
only problem with this approach is that no one on the team operates this way,
and you are unsure whether it is possible to merge incomplete feature code into
the main branch or if there is a way to hold off on all the changes but still
allow for incremental reviews.

A few months ago, someone from the billing team shared a recent experiment using
feature flags to turn on and off certain logic in production based on a
configuration that’s easily accessed by a UI. Leveraging feature flags sounds
like a sensible approach. That way, you could wrap all the new code under a
feature flag that’s deactivated by default and only enabled once all pull
requests have been merged into the main branch and the feature is code complete.
But it seems the feature flag infrastructure is a bit experimental in the
company, and you’re unsure whether it will be safe for your team to start
relying on them.

But wait, there might be ways to achieve a similar code reviewing experience
(note from the author: yeah, deploying code behind feature flags offers many
more benefits than just facilitating code review, but that’s part of another
series) by stacking pull requests. For example, you can create a first branch
for your initial set of changes and then branch off again with the new set of
changes. This second pull request will be based on the first branch instead of
the main branch, so the diff is clear and only shows the new set of incremental
changes.

Although stacking pull requests may become a bit tricky with large feature
developments, it offers a good compromise for small to medium developments. You
just need to make sure each new set of changes branches off from the previous
branch. Then, each pull request will use the previous branch as the base branch
for comparison. You don't need to merge each pull request independently; they
are there just to facilitate the code review process. Once each step has been
approved by your team, you can create a final pull request containing all the
changes and use that to release the code. It's true the process accounts for
some minimal duplication, but the benefits of having small, reviewable units
persuade you to give it a try.

![Diagram illustrating the stacked pull requests workflow with branches and incremental changes.](/static/articles/stacked-pull-requests/how-it-works.jpg "Illustration of the stacked pull requests workflow, showing how incremental changes build upon each other for streamlined code reviews.")

The only problem: you have never worked this way before, and typically, your
feature development is a bit chaotic. Although you know the end goal, you’re
usually figuring out the way to get there as you experiment with the codebase.
This time, however, you may need a clearer plan to slice your work correctly for
reviewing, following the principles you stated before (each pull request will
only contain one change in behavior).

All your teammates have small differences in the way they approach feature
development. Thinking about it for a second, you realize Sara uses something she
calls an “Implementation Plan” and regularly posts it as a comment on the issue
even before writing a single line of code. Reflecting a bit more, each step in
Sara’s implementation plan typically matches the principles you’ve stated
before: each pull request introduces only one new behavior into the system.

Deciding to follow Sara’s approach, you take a few hours to design a possible
solution for the problem. There might be a few surprises along the way, but the
implementation plan looks solid and has already given you some hints about how
you may slice the problem. You have already identified a little refactoring you
need to accomplish in the first instance that is better encapsulated in its own
pull request so Jose, one of the experts on that part of the system, can take a
look. Actually, now that you look at the plan, you realize it might be a good
moment to ask Sofia, the tech lead for your team, to chime in so she can give
you a thumbs-up now that you haven’t invested too much time in development.
Working in smaller batches has already proven to be helpful even before creating
the first pull request.

--

So, the little story above is just an example of how we may approach software
development in a way that favors creating many small pull requests instead of a
single one. Obviously, your mileage may vary, as may the experience around your
team, but regularly incorporating this notion of 1 pull request = 1 behavior
should facilitate both your development (because you’ll be working with less
complexity at every step) and your code review process.

Implementation plans are just a technique that may help you divide your work in
a way that makes sense and follows the principle we’ve stated before. They may
also contribute to other benefits such as discovering potential blockers,
incorporating feedback from your colleagues early in the process, or offering
you some guidance as you move forward with the development.

We have already covered how stacking pull requests may work at a high level.
Some tools support this kind of process by default (e.g., Phabricator via
stacked diffs), but a similar workflow can be easily replicated in tools such as
GitHub or GitLab (although the developer experience could be much better).

But as with almost everything in software, there isn’t a silver bullet. One
drawback of slicing your work this way is that reviewers may find it more
complex to see the whole picture of your changes. While this can be minimized by
offering links to previous pull requests, having all your changes in a single
pull request can make it easier for them to understand the context and scope. On
the other hand, a large pull request with dozens of changes can also be
overwhelming and, as we have discussed before, delay the overall reviewing
process because reviewers need to deal with more complexity.

If you're looking for cost-effective ways to improve the code review process on
your team, give stacked pull requests a try or, at the very least, aim to
conform to the rule of one behavior change = one pull request.


Many small pull requests

# Effective Code Reviews

Many companies use pull requests as a critical part of their software
development process to achieve goals such as automated testing (via continuous
integration services) and conducting code reviews.

In many cases, pull requests also serve as gatekeepers to production: someone
from the organization (likely from the same team) needs to approve the changes
for development to move forward. This process is often a source of frustration
in software teams, where it is common to hear complaints about how long it takes
for a pull request to be reviewed or the lack of constructive feedback received
during code reviews.

On the other hand, reviewers often express frustration because pull requests are
usually very large, making them difficult to review and thus more
time-consuming. Still, many developers write code with a focus on their own
productivity instead of optimizing for the later, required step of code
reviewing.

In this series, I'd like to explore ways to make code reviews more productive
for everyone: developers who want to receive constructive feedback while
releasing software on time, and code reviewers who want to set a high-quality
standard and use code reviews as a tool to leverage collective learning and
knowledge sharing.

## But first...

Pull requests, or pull request-based workflows, are just one option for
collaborative work. I'm aware that other teams use more lightweight approaches,
such as [trunk-based development](https://trunkbaseddevelopment.com/), where all
commits are made directly to the main branch. This method relies on a highly
sophisticated continuous integration infrastructure to validate each commit
before it gets released.

There are also companies that focus heavily on pair or ensemble programming
sessions, thereby reducing the need for asynchronous work. Still, highly
distributed companies or teams that prefer a more asynchronous approach may
choose pull requests to review code.

Ultimately, this series is not advocating for a pull request workflow but rather
highlighting ways to make it more productive.

## Read the full series

1. [Many small pull requests](/blog/stacked-pull-requests)
2. ...more coming soon!


Effective Code Reviews

React

# React: Using children instead of dedicated render slots

Using component props to pass data (or `JSX` elements directly) that will later
populate internal UI pieces has been a prevalent pattern in the React community,
trying (probably) to emulate [the better-designed slot approach adopted by
Vue][vue-slots].

For example, imagine we are coding a new `Nav` component for our site. It will
render a collection of nav items, the page title, and a call to action link.
Each page might customize any of these elements.

Not surprisingly, I think either of these two would be the most popular examples
we might find out there (or a combination of both):

```jsx
// Passing simple data structures with the desired data
<Nav
  cta={{ text: "Buy the book!", href: "https://url.to/buy-my-book" }}
  menuItems={[
    { text: "Home", href: "/home" },
    { text: "About", href: "/about" },
    { text: "Contact", href: "/contact" },
  ]}
  title="My Site"
/>

// Passing JSX elements directly
<Nav
  cta={<a href="https://url.to/buy-my-book">Buy the book!</a>}
  menuItems={
    <>
      <li>
        <a href="/home">Home</a>
      </li>

      <li>
        <a href="/about">About</a>
      </li>

      <li>
        <a href="/contact">Contact</a>
      </li>
    </>
  }
  title={<h1>My Site</h1>}
/>
```

Even in such as simple example, we can start seeing some of the problems with
this approach: it creeps the component API with render props, it is not very
idiomatic, and it can quickly get worse as we continue adding some more
customization for each element. For example, we may later add specific props to
styling each of the items, title, and call-to-action components:
`menuItemStyle`, `titleStyle`, `ctaStyle`, and so on:

```jsx
<Nav
  cta={{ text: "Buy the book!", href: "https://url.to/buy-my-book" }}
  ctaStyle={{ color: "red" }}
  ctaOnClick={() => alert("Thanks for buying the book!")}
  menuItems={[
    { text: "Home", href: "/home" },
    { text: "About", href: "/about" },
    { text: "Contact", href: "/contact" },
  ]}
  menuItemStyle={{ color: "blue" }}
  onMenuItemClick={(href) => alert(`Navigating to ${href}`)}
  title="My Site"
  titleStyle={{ color: "green" }}
/>
```

Let’s try a different approach. One that resembles how HTML works and that is
supported out-of-the-box by React.

## Using `children` and dedicated components

```jsx
<Nav>
  <Nav.Title>My Site</Nav.Title>

  <Nav.Menu>
    <Nav.Menu.Item href="/">Home</Nav.Menu.Item>
    <Nav.Menu.Item href="/about">About</Nav.Menu.Item>
    <Nav.Menu.Item href="/contact">Contact</Nav.Menu.Item>
  </Nav.Menu>

  <Nav.CallToAction href="https://url.to/buy-my-book">
    Buy the book!
  </Nav.CallToAction>
</Nav>
```

If you have done some React development, you probably know the `children` prop
is how React passes content down to components (for example `<p>Hola</p>`, where
`p` is the component, and `Hola` is the value of the `children` prop).

The example above uses `children` and composition extensively to render the
desired UI. Instead of passing multiple props to the `Nav` component, we create
many small, dedicated components which may of course receive their own props.

As a result, this approach gives us a much more flexible and idiomatic API. If
we later need to add additional elements to the `Nav` component, we can do so
without changing the `Nav` component at all (following the [Open-Closed design
principle][open-closed]).

On the other hand, using this technique comes with some drawbacks worth
mentioning:

- We have to make it clear that these dedicated components are only meant to be
  used as children of the `Nav` component. We can do this by using the `Nav`
  namespace, for example: `Nav.Title`, `Nav.Menu`, and `Nav.CallToAction`.
- We must ensure the `Nav` component is flexible enough to handle the different
  cases we might want to render. For example, if we want to make it possible to
  render the `Nav.Menu` component either after or before the `Nav.CallToAction`
  component, the styles should be sufficiently sophisticated to handle both
  cases.

### Possible implementation

Pay attention to how we export the `Nav` component and its dedicated components.
That’s the secret sauce to namespace them and make it clear they are only meant
to be used as children of the `Nav` component.

```jsx
const Nav = ({ children }) => {
  return <nav>{children}</nav>;
};

const CallToAction = ({ children, href }) => {
  return <a href={href}>{children}</a>;
};

const Menu = ({ children }) => {
  return <ul>{children}</ul>;
};

const MenuItem = ({ children, href }) => {
  return (
    <li>
      <a href={href}>{children}</a>
    </li>
  );
};

const Title = ({ children }) => {
  return <h1>{children}</h1>;
};

Menu.Item = MenuItem;

Nav.CallToAction = CallToAction;
Nav.Menu = Menu;
Nav.Title = Title;

export { Nav };
```

## Notes

- A few weeks after starting to write this post, I received a newsletter from
  [Kent C. Dodds][kentcdodds] featuring a React article. Coincidentally, the
  content of [the post][soul-crushing-components] covered precisely this! So,
  digging a little more, I found this pattern had been documented since a few
  years ago (watch out [this video talk][talk] from Ryan Florence at _Phoenix
  ReactJS Conf_ in 2017), and it is called **_Compound components_**.
- [Radix UI][radix] uses this pattern extensively.
- If you’re curious, I used this pattern to build the whole landing page for my
  tddworkshop.com page. You can check the source code [here][tddworkshop].

Happy hacking!

[vue-slots]: https://vuejs.org/guide/components/slots.html#named-slots
[open-closed]: https://en.wikipedia.org/wiki/Open%E2%80%93closed_principle
[tddworkshop]:
  https://github.com/codecoolture/tddworkshop.com/blob/trunk/pages/en/index.tsx
[radix]: https://www.radix-ui.com/
[kentcdodds]: https://kentcdodds.com/
[soul-crushing-components]: https://epicreact.dev/soul-crushing-components/
[talk]: https://www.youtube.com/watch?v=hEGg-3pIHlE


React: Using children instead of dedicated render slots

Testing

# Using the Builder pattern for creating test data with ease

If you have yet to hear about [software] design patterns, you may think of them
as reusable solutions for everyday problems that work for different contexts. Of
course, new design patterns appear now and then, but there is a [well-documented
core of patterns][design-patterns] that are popular and can be seen in many
object-oriented code bases. The [Builder][builder] pattern is one of them.

Although this pattern may come in handy in multiple situations, it is especially
helpful when creating test data. Tests for any medium-large-sized applications
often require us to create various objects, put them in a particular state, and
have relationships with other entities. That can be hard to do, especially if
the objects are complex and we need to create many of them. The Builder pattern
offers a solution to use a more semantic, domain-specific interface that makes
the process easier.

For example, imagine we are coding a software system to help manage an
automobile repair shop. Not surprisingly, we may find mechanics and cars.
Mechanics can be responsible for multiple vehicles, be on holiday, and have
different hourly salaries. The following tests verify that we cannot assign a
car to a mechanic under certain circumstances.

```ts
import { Car, Mechanic } from "@domain";

describe("POST /mechanics/{id}/cars", () => {
  it("does not add a new car if the mechanic is on holiday", async () => {
    const mechanic = new Mechanic({
      id: 1,
      name: "Alice",
    });

    const today = new Date();

    const pto = new Pto({
      mechanic,
      startDate: startOfDay(today),
      endDate: endOfDay(today),
    });

    mechanic.ptos = [pto];

    await mechanicRepository.save(mechanic);

    const car = new Car({
      id: 1,
      make: "Mazda",
      model: "Mazda 3",
      year: 2021,
    });

    await carRepository.save(car);

    const response = await request(app)
      .post(`/mechanics/${mechanic.id}/cars`)
      .send({ carId: car.id });

    expect(response.status).toBe(400);
  });

  it("does not add a new car if the mechanic is working on five cars already", async () => {
    const mechanic = new Mechanic({ id: 1, name: "Alice" });

    mechanic.cars = [
      new Car({
        id: 1,
        make: "Mazda",
        model: "Mazda 2",
        year: 2021,
      }),
      new Car({
        id: 2,
        make: "Mazda",
        model: "Mazda 3",
        year: 2021,
      }),
      new Car({
        id: 3,
        make: "Mazda",
        model: "CX-30",
        year: 2021,
      }),
      new Car({
        id: 4,
        make: "Mazda",
        model: "MX-5",
        year: 2021,
      }),
      new Car({
        id: 5,
        make: "Mazda",
        model: "CX-60",
        year: 2021,
      }),
    ];

    await mechanicRepository.save(mechanic);

    const car = new Car({
      id: 6,
      make: "Mazda",
      model: "CX-9",
      year: 2021,
    });

    await carRepository.save(car);

    const response = await request(app)
      .post(`/mechanics/${mechanic.id}/cars`)
      .send({ carId: car.id });

    expect(response.status).toBe(400);
  });
});
```

As you may see in the code block above, creating all these objects by hand is
expensive and makes the whole test hard to read. Let’s try instead to use a
`MechanicBuilder` that makes the process easier while producing the same result.

```ts
import { MechanicBuilder, CarBuilder } from "@test/builders";

describe("POST /mechanics/{id}/cars", () => {
  it("does not add a new car if the mechanic is on holiday", async () => {
    const mechanic = await new MechanicBuilder()
      .onHoliday()
      .save(mechanicRepository);

    const car = await new CarBuilder().save(carRepository);

    const response = await request(app)
      .post(`/mechanics/${mechanic.id}/cars`)
      .send({ carId: car.id });

    expect(response.status).toBe(400);
  });

  it("does not add a new car if the mechanic is working on five cars already", async () => {
    const mechanic = await new MechanicBuilder()
      .withCars(5)
      .save(mechanicRepository);

    const car = await new CarBuilder().save(carRepository);

    const response = await request(app)
      .post(`/mechanics/${mechanic.id}/cars`)
      .send({ carId: car.id });

    expect(response.status).toBe(400);
  });
});
```

Reading the code above, we can clearly see the scenario we are creating for the
test. The builder reduces verbosity and makes the code more expressive while
favoring reusability for other test cases. Of course, we may keep adding methods
to the `MechanicBuilder` as new requirements appear, so we always have an
up-to-date, semantic interface to create `Mechanic` objects (and the same
applies for `Car` instances).

## Example of a Builder implementation using TypeScript

Wondering how you can create that fancy builder above using TypeScript? 😏 As
with many things in software development, different paths may lead to the same
result, but this approach worked very well for me in the past.

The Builder pattern is considered a _creational pattern_ since it helps us
create objects by removing all the complexity to instantiate them. So let’s
start by creating a generic `Builder<T>` interface that defines the two methods
all builders should implement: `build` (to return the object) and `save` (to
persist the object in the database). I usually add a third method, `with`, that
would allow us to pass an object with the properties we want to override. Still,
for the sake of simplicity, I will skip it in this example.

```ts
export interface Builder<T> {
  build(): T;
  save(repository: Repository<T>): Promise<T>;
}
```

Then, we may create a `BaseBuilder<T>` abstract class that implements the
`Builder<T>` interface and provides a default implementation for both methods.
The `build` method will return the object, while the `save` method will return
the object and persist it in the database. Here, we use inheritance just for
code reusability.

```ts
import { Builder } from "@test/builders";

export abstract class BaseBuilder<T> implements Builder<T> {
  protected abstract entity: T;

  public build(): T {
    return this.entity;
  }

  public save(repository: Repository<T>): Promise<T> {
    return repository.save(this.entity);
  }
}
```

Finally, we can create the `MechanicBuilder` simply by extending
`BaseBuilder<Mechanic>` and providing all the additional methods.

```ts
import { Mechanic } from "@domain";
import { BaseBuilder, CarBuilder, PtoBuilder } from "@test/builders";

export class MechanicBuilder extends BaseBuilder<Mechanic> {
  protected entity: Mechanic;

  constructor() {
    super();

    this.entity = new Mechanic({ id: 1, name: "Alice" });
  }

  public onHoliday(): this {
    this.entity.ptos = [
      new PtoBuilder().for(this.entity).on(new Date()).build(),
    ];

    return this;
  }

  public withCars(count: number): this {
    this.entity.cars = new Array(count)
      .fill(null)
      .map(() => new CarBuilder().build());

    return this;
  }
}
```

> Note how we return `this` in the `onHoliday` and `withCars` methods. That is
> the _secret sauce_ to making the Builder provide a [fluent interface][fluent]
> so that we can use it in the following way:

```ts
const mechanic = await new MechanicBuilder()
  .onHoliday()
  .withCars(5)
  .save(mechanicRepository);
```

Happy hacking!

[fluent]: https://en.wikipedia.org/wiki/Fluent_interface
[design-patterns]:
  https://en.wikipedia.org/wiki/Software_design_pattern#Classification_and_list
[builder]: https://en.wikipedia.org/wiki/Builder_pattern


Using the Builder pattern for creating test data with ease

# Uncovering and conquering async bugs: A trick to testing undesired effects

Imagine you are coding a new React component to upload a file. The component
will receive a callback to notify the app if the upload has been or has not been
successful. You may end with something similar to:

```tsx
/**
 * We will use the `executor` function to simulate different
 * scenarios from our tests.
 */
function UploadButton({ executor, onSuccess }) {
  return (
    <button
      type="button"
      onClick={async () => {
        await executor();

        onSuccess();
      }}
    >
      Upload
    </button>
  );
}
```

To test the most simple scenario, that the `<UploadButton />` component uses the
callback once the upload is completed, we can rely on the standard approach:

```tsx
it("uses the callback to notify that the upload completed", async () => {
  const spy = jest.fn();

  render(<UploadButton executor={success} onSuccess={spy} />);

  user.click(screen.getByText("Upload"));

  await waitFor(() => {
    expect(spy).toHaveBeenCalledTimes(1);
  });
});
```

But things are more complicated if we want to ensure that the `onSuccess`
callback is not executed if something unexpected happens and the process fails.
The initial and most naive implementation might be to assure that the spy is
never called when using the failing executor:

```tsx
it("does not use the callback if something goes wrong", async () => {
  const spy = jest.fn();

  render(<UploadButton executor={fail} onSuccess={spy} />);

  user.click(screen.getByText("Upload"));

  await waitFor(() => {
    expect(spy).toHaveBeenCalledTimes(0);
  });
});
```

**Even if it passes, the test is not checking that the spy never gets called**.
Since the executor is an asynchronous process, and the spy starts with zero
calls, the expectation is valid immediately. You can spot this by replacing
`executor={fail}` with `executor={success}` --that’s the kind of change that
should make the test have a different result, but it continues passing!

To test this scenario, we need to come up with a different approach:

```tsx
it("does not use the callback if something goes wrong", async () => {
  const asyncRender = new Promise<undefined>((resolve, reject) => {
    render(<UploadButton executor={fail} onSuccess={reject} />);

    user.click(screen.getByText("Upload"));

    setTimeout(resolve, 0);
  });

  await expect(asyncRender).resolves.toBeUndefined();
});
```

By embracing the asynchronous nature of this problem, we can wrap the rendering
within a promise and use its reject function as the `onSuccess` callback.
Remember that promises execute immediately but return a delayed response. To
give some room for the component to fail, I use the [setTimeout][settimeout]
trick to force the process to complete pending tasks from the queue.

Now, `asyncRender` should always resolve (with an `undefined` value). If it does
not, our component is having issues handling the `onSuccess` callback and
calling it even when the upload fails (since it is what the failing executor
does). If you change `executor={fail}` to `executor={success}`, you may see the
result keeps consistent, and the test fails.

[settimeout]:
  https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#zero_delays


Uncovering and conquering async bugs: A trick to testing undesired effects

Software Delivery

# Un acercamiento sencillo a feature flags en una aplicación React con TypeScript

Aunque ya he escrito en otras ocasiones sobre feature flags y como su uso nos
puede ayudar a alcanzar un flujo de entrega continua, en este artículo me
gustaría compartir una implementación sencilla en React utilizando TypeScript.

En esencia, una feature flag es un interruptor que nos permite activar o
desactivar una funcionalidad concreta bajo una serie de condiciones. Los tipos
de condiciones pueden ser muy variados: entorno de ejecución de la aplicación,
tipo de usuaria, porcentaje de tráfico, etc. Además, el cálculo de esa condición
puede realizarse dentro de la propia aplicación, o bien delegarse en otro
sistema.

Este concepto posibilita, entre otras cosas, desacoplar nuestro repositorio del
proceso de entrega de software. Siempre y cuando nuestras funcionalidades
incompletas estén protegidas bajo una feature flag, podremos integrar
continuamente nuestros cambios en la rama principal (aunque eso implique su
despliegue a producción o cualquier otro entorno).

## Publicando feature flags

El primer paso para comenzar a utilizar feature flags es definirlas en algún
sitio. Aunque existan servicios específicamente creados para trabajar con ellas
(que, además, ofrecen flujos y procesos mucho más refinados), yo siempre
recomiendo comenzar con un enfoque humilde, gestionando las feature flags
directamente en la aplicación. En este caso, vamos a crear un módulo que exporte
las diferentes feature flags y una función para obtener su estado:

```tsx
export const Features = {
  newSettingsPage: () => process.env.NODE_ENV === "development",
};
```

La única razón de asociar una función a la feature flag en lugar de directamente
un booleano es dotarle de cierta flexibilidad (realmente, sería incluso más
interesante hacer que la función devolviese una promesa -de esa manera,
estaríamos cubriendo el caso en el que, para calcular el valor de una feature
flag, tuviésemos que realizar una petición a un servicio externo).

## Integrando la aplicación React con las feature flags

Ahora que ya tenemos un módulo encargado de publicar las feature flags de la
aplicación, es hora de hacerlo accesible desde los componentes React.

El enfoque más directo, sería importar el módulo desde las diferentes páginas o
componentes que lo utilicen y realizar después las operaciones para
mostrar/ocultar alguna parte de la interfaz. Aunque este enfoque funcionaría
estaríamos creando una dependencia no explícita entre nuestros diferentes
componentes y un elemento global (el módulo de `Features`) lo que hará que
probar nuestros componentes en cada uno de los estados sea más complejo.

Vamos a verlo con un ejemplo:

```tsx
import { Features } from "../lib/Features";

export function Menu() {
  return (
    <nav>
      <ul>
        <li>
          <a href="/dashboard">Dashboard</a>
        </li>

        <li>
          <a href="/profile">Profile</a>
        </li>

        {Features.newSettingsPage() && (
          <li>
            <a href="/settings">Settings</a>
          </li>
        )}
      </ul>
    </nav>
  );
}
```

En esta implementación, `Menu` utiliza directamente el módulo de `Features` para
saber si tiene que mostrar o no la opción de ajustes. A la hora de probar este
componente, tenemos que tener en cuenta esta dependencia y utilizar un _stub_
para poder ajustarlo a ambos escenarios:

```tsx
/**
 * @jest-environment jsdom
 */

import { render, screen } from "@testing-library/react";
import { Features } from "../lib/Features";
import { Menu } from "./Menu";

describe("Menu", () => {
  it("doesn't show Settings if the feature is disabled", async () => {
    render(<Menu />);

    expect(screen.queryByText("Settings")).toBeNull();
  });

  it("shows Settings if the feature is enabled", async () => {
    jest.spyOn(Features, "newSettingsPage").mockImplementationOnce(() => true);

    render(<Menu />);

    expect(screen.queryByText("Settings")).not.toBeNull();
  });
});
```

Los stubs (o test doubles en general) son recursos muy útiles pero me gusta
reservar su uso para situaciones donde no tengo ninguna otra opción más
idiomática para probar el sujeto bajo test. En este caso, lo ideal sería
convertir esa dependencia no explícita en algo que pudiésemos controlar desde el
exterior, utilizando inyección de dependencias. En React, tendríamos varias
opciones para conseguirlo. Veamos un par de ellas.

### Obtener las feature flags a través de una prop

Por ejemplo, utilizando una prop `features` para poder recibir el objeto
completo de feature flags. El problema con este enfoque es que podría haber
muchos componentes intermedios que necesiten propagar esta prop sin necesidad de
utilizarla. Este fenómeno se denomina
[Prop Drilling](https://kentcdodds.com/blog/prop-drilling) y, aunque no es malo
_per se_, puede convertirse en algo difícil de gestionar cuando nuestra
aplicación crezca en número de componentes.

```tsx
import { Features } from "../lib/Features";

export function Menu({ features }: { features: typeof Features }) {
  return (
    <nav>
      <ul>
        <li>
          <a href="/dashboard">Dashboard</a>
        </li>

        <li>
          <a href="/profile">Profile</a>
        </li>

        {features.newSettingsPage() && (
          <li>
            <a href="/settings">Settings</a>
          </li>
        )}
      </ul>
    </nav>
  );
}
```

Ahora que el componente `Menu` obtiene la información de las feature flags a
través de una prop, podemos ajustar los diferentes escenarios para las pruebas
sin necesidad de utilizar test doubles:

```tsx
/**
 * @jest-environment jsdom
 */

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

describe("Menu", () => {
  it("doesn't show Settings if the feature is disabled", async () => {
    render(<Menu features={{ newSettingsPage: () => false }} />);

    expect(screen.queryByText("Settings")).toBeNull();
  });

  it("shows Settings if the feature is enabled", async () => {
    render(<Menu features={{ newSettingsPage: () => true }} />);

    expect(screen.queryByText("Settings")).not.toBeNull();
  });
});
```

### Obtener las feature flags a través de la API de contextos

Bien utilizada, la
[API de contextos de React](https://reactjs.org/docs/context.html) puede servir
como un contenedor de inyección de dependencias que permita aislar a los
componentes padre de las dependencias concretas de sus componentes hijo. En este
caso, vamos a crear un nuevo contexto que publique las feature flags disponibles
dentro de la aplicación y que permita acceder a ellas a través de un hook
concreto, `useFeatures`.

Lo primero, es definir el propio contexto encargado de devolver las feature
flags existentes. Junto a él, también definiremos el hook que se utilizará
después desde nuestros componentes. Este último es una simple capa de
abstracción que centraliza la lógica común de acceso.

```tsx
import { createContext, useContext } from "react";

export const Features = {
  newSettingsPage: () => process.env.NODE_ENV === "development",
};

export const FeaturesContext = createContext(Features);

export function useFeatures() {
  return useContext(FeaturesContext);
}
```

Los contextos en React se crean con un valor por defecto. En caso de que no
exista ningún proveedor que sobrescriba el valor para el contexto, nuestros
componentes recibirán ese valor al acceder a él. En este caso, hemos creado el
contexto utilizando como valor por defecto el propio objeto exportado por
`Features`.

```tsx
import { useFeatures } from "../lib/Features";

export function Menu() {
  const features = useFeatures();

  return (
    <nav>
      <ul>
        <li>
          <a href="/dashboard">Dashboard</a>
        </li>

        <li>
          <a href="/profile">Profile</a>
        </li>

        {features.newSettingsPage() && (
          <li>
            <a href="/settings">Settings</a>
          </li>
        )}
      </ul>
    </nav>
  );
}
```

Ahora que nuestro componente `Menu` utiliza el nuevo contexto, sólo necesitamos
envolver el componente en diferentes proveedores cuando queramos probar
distintos escenarios:

```tsx
/**
 * @jest-environment jsdom
 */

import { render, screen } from "@testing-library/react";
import { FeaturesContext } from "../lib/Features";
import { Menu } from "./Menu";

describe("Menu", () => {
  it("doesn't show Settings if the feature is disabled", async () => {
    render(
      <FeaturesContext.Provider value={{ newSettingsPage: () => false }}>
        <Menu />
      </FeaturesContext.Provider>,
    );

    expect(screen.queryByText("Settings")).toBeNull();
  });

  it("shows Settings if the feature is enabled", async () => {
    render(
      <FeaturesContext.Provider value={{ newSettingsPage: () => true }}>
        <Menu />
      </FeaturesContext.Provider>,
    );

    expect(screen.queryByText("Settings")).not.toBeNull();
  });
});
```

## `<FeatureFlag />`, un componente para abstraernos por completo

Si utilizamos la API de contextos, podemos ir todavía un paso más allá y
abstraernos por completo de la gestión de funcionalidades disponibles. En este
caso, vamos a crear un componente `FeatureFlag` que recibirá la flag sobre la
que queremos trabajar y los nodos que queremos ocultar en caso de no estar
disponible:

```tsx
import { ReactNode } from "react";
import { Features, useFeatures } from "../lib/Features";

type FeatureFlagProps = { children: ReactNode; flag: keyof typeof Features };

export function FeatureFlag({ children, flag }: FeatureFlagProps) {
  const features = useFeatures();

  if (features[flag]()) {
    return <>{children}</>;
  }

  return null;
}
```

Al definir la prop de `flag` como `keyof typeof Features` estamos tomando
ventaja de la ayuda del compilador de TypeScript, que nos dirá automáticamente
que funcionalidades existen y evitará que utilicemos flags que no se encuentran
en el objeto global de `Features`.

```tsx
import { FeatureFlag } from "./FeatureFlag";

export function Menu() {
  return (
    <nav>
      <ul>
        <li>
          <a href="/dashboard">Dashboard</a>
        </li>

        <li>
          <a href="/profile">Profile</a>
        </li>

        <FeatureFlag flag="newSettingsPage">
          <li>
            <a href="/settings">Settings</a>
          </li>
        </FeatureFlag>
      </ul>
    </nav>
  );
}
```

Con este último enfoque, nuestras pruebas anteriores utilizando el proveedor del
contexto de feature flags seguirán funcionando (ya que es el mecanismo sobre el
que se construye todo) a la vez que tomamos ventaja de un diseño mucho más
idiomático, encapsulando la gestión de feature flags en su propio componente
React.


Un acercamiento sencillo a feature flags en una aplicación React con TypeScript

Test-Driven Development

# Test-driven front-end development

> Este artículo fue publicado originalmente en la edición de 2020 de
> [Octuweb](https://octuweb.com/test-driven-front-end-development/).

En la edición de 2018 **Cristina Ponce** publicó
[Testing en el front](https://octuweb.com/testing-front/), una guía sobre los
diferentes tipos de pruebas que podemos realizar en aplicaciones front-end.
Apoyándonos en ese artículo, vamos a hablar aquí de cómo aprovechar la nueva
generación de herramientas para alcanzar flujos de desarrollo que, hasta hace
solo unos años, no eran (tan) fácilmente aplicables en este contexto:
**Test-Driven Development** (o **TDD**).

## Pero primero, ¿qué es TDD?

Test-Driven Development es una metodología que se basa en aplicar pequeños
ciclos de desarrollo con el objetivo de resolver casos de prueba. De manera más
concreta, lo podemos definir en 3 pasos:

1. Codificar una prueba que defina el nuevo comportamiento que queremos añadir a
   nuestro sistema
2. Escribir la menor cantidad de código posible que nos permita hacer pasar el
   test anterior
3. Mejorar el código anterior utilizando las pruebas como red de seguridad
   (a.k.a _refactoring_)

En TDD clásico, lo habitual es comenzar por las entidades más internas de
nuestro sistema para ir construyendo capas una encima de otra hasta terminar de
implementar la funcionalidad. En front-end sin embargo, y con las herramientas
actuales, lo más natural es utilizar una variación denominada **ATDD**
(inspirada en **Outside-in**, un enfoque de TDD que se originó en la comunidad
de eXtreme Programming de Londres), donde se empieza creando un primer test en
la capa más externa del sistema (en este caso, la interfaz o un componente) para
ir construyendo desde ahí el resto de la funcionalidad.

## Escribiendo nuestro primer test

En su sentido más estricto, TDD es una herramienta de desarrollo (un flujo de
trabajo, una metodología) y no tiene que verse como un instrumento de calidad
(entendiendo esta como la disciplina para el control de defectos). Por tanto, su
objetivo es ayudar a las programadoras a entregar valor lo antes posible, con
confianza. En ATDD, por ejemplo, el primer test nos tiene que permitir poner el
foco en el problema que vamos a resolver y servirnos como guía durante el
desarrollo de la funcionalidad. Lo habitual es intentar reflejar en este primer
test los criterios de aceptación que perseguimos cumplir con la historia de
usuario en curso.

Por ejemplo, supongamos que estamos trabajando en el front-end para la web de
una editorial de libros y queremos añadir una página de contacto:

> Es posible acceder a una página de contacto para, indicando email, asunto y
> mensaje, ponerse en contacto con la editorial. Una vez completada la
> operación, se realizará una redirección a una página de éxito con un mensaje
> que indique que todo ha ido bien.
>
> Hay disponible un endpoint `/api/contact` que completa la operación en el
> back-end.

Utilizando [**Cypress**](https://www.cypress.io/), podemos trasladar esta
descripción a una prueba de alto nivel como la siguiente:

```tsx
// Location: cypress/integration/sendContactMessage.test.ts

context("sendContactMessage", () => {
  specify("A user can send a contact message", () => {
    // Setup
    cy.server();
    cy.route2("/api/contact", { statusCode: 200 });

    // Act
    cy.visit("/contact");
    cy.findByLabelText(/tu email/i).type("hola@codecoolture.com");
    cy.findByLabelText(/asunto/i).type("Información sobre próximos libros");
    cy.findByLabelText(/mensaje/i).type(
      "Hola, me gustaría obtener más información sobre próximos libros.",
    );
    cy.findByText(/enviar/i).click();

    // Assert
    cy.url().should("eql", Cypress.config().baseUrl + "/contact/success");
    cy.findByText(/tu mensaje ha sido enviado con éxito/i).should("exist");
  });
});
```

La prueba anterior codifica el escenario de aceptación básico: primero, hacemos
que Cypress simule la respuesta al endpoint `/api/contact` para indicar que todo
ha ido bien (devolverá un código `200`), y después interactuamos con la
aplicación para ir a la página de contacto y completar el formulario. Por
último, validamos que se ha llevado al usuario a la página de éxito tras enviar
el formulario.

> Ahora que hemos visto un ejemplo, seguramente nos sea más sencillo explicar
> qué es Cypress: un framework de testing para construir pruebas de aceptación
> sobre un navegador, utilizando JavaScript.

En el ejemplo anterior, la prueba se ejecutará sobre nuestra propia aplicación.
En este caso, **como todavía no hemos escrito código de producción, lo que
esperamos es que el test falle**. Es ahora cuando tenemos que escribir la mínima
cantidad posible de código para que este test pueda pasar.

```tsx
// Location: pages/contact.tsx

export default function Contact() {
  return (
    <main>
      <Formik
        initialValues={{ email: "", subject: "", message: "" }}
        onSubmit={async ({ email, subject, message }) => {
          const response = await fetch("/api/contact", {
            body: JSON.stringify({ email, subject, message }),
            headers: { "content-type": "application/json" },
            method: "post",
          });

          if (response.ok) {
            window.location.href = "/contact/success";
          }
        }}
      >
        {() => {
          return (
            <Form>
              <label>
                Tu email <Field id="email" name="email" />
              </label>

              <label>
                Asunto <Field name="subject" />
              </label>

              <label>
                Mensaje <Field name="message" />
              </label>

              <button type="submit">Enviar</button>
            </Form>
          );
        }}
      </Formik>
    </main>
  );
}
```

```tsx
// Location: pages/contact/success.tsx

export default function ContactSuccess() {
  return <p>¡Enhorabuena! Tu mensaje ha sido enviado con éxito</p>;
}
```

Obviando algunos detalles de implementación (como el uso de
[Formik](https://formik.org/) para el formulario), los dos fragmentos de código
anteriores muestran una posible implementación (básica pero funcional) que sirve
para hacer pasar nuestro primer test de aceptación. En este punto, podemos
añadir CSS a nuestra nueva página o extraer comportamientos a otro tipo de
entidades (por ejemplo, mover la operación de `onSubmit` a un servicio). Si
nuestro test sigue en verde al completar los cambios, tendremos la certeza de
que no hemos roto nada ✅

## Aplicando ciclos de desarrollo más pequeños

Aunque Cypress es un magnífico framework de testing, las pruebas de tan alto
nivel suelen venir con algunos compromisos: es difícil poder ejercitar todos los
caminos de ejecución posibles y son lentas. Recordad que con TDD estamos
buscando mejorar nuestra productividad por lo que **necesitamos que los ciclos
de feedback sean lo más cortos posibles**. Para ello, mi consejo es utilizar
pruebas de aceptación para cubrir el _happy path_ de la funcionalidad (y quizás
algún escenario de error clave) y después iterar en ciclos de desarrollo más
pequeños facilitados por pruebas de una granularidad más baja (en front-end,
podríamos entenderlas como híbridos de integración + unitaria, centradas en
componentes).

Si volvemos al ejemplo anterior, seguramente hay ciertas reglas de experiencia
de usuario que queramos validar sobre el formulario de contacto: que no se pueda
completar la operación sin un email de remite o sin el cuerpo del mensaje, que
aparezcan correctamente los mensajes de error, que los campos permitan
únicamente ciertos patrones, etc. Aunque estas pruebas se podrían hacer también
utilizando Cypress, su latencia es a menudo lo suficientemente grande como para
preferir moverlos a tests de más bajo nivel (por lo general, más rápidos).

Para hacer pruebas de componentes (en React, aunque las mismas herramientas
están disponibles en otros frameworks como Vue o Angular) mi consejo es utilizar
[**Testing Library**](https://testing-library.com/) en conjunción con
[**Jest**](https://jestjs.io/). Por ejemplo, vamos a añadir un nuevo
comportamiento a nuestra página de Contacto, aunque esta vez iterando en un
nivel de abstracción más bajo:

> El formulario sólo debe enviarse si contiene un email de remite y un mensaje.

```tsx
// Location: components/ContactForm.test.tsx

describe("ContactForm", () => {
  it("does not submit the form if some required fields are missing", async () => {
    // Setup
    const spy = jest.fn();
    render(<ContactForm onSubmit={spy} />);

    // Act
    await user.type(
      screen.getByLabelText(/asunto/i),
      "Información próximos libros",
    );

    user.click(screen.getByText(/enviar/i));

    // Assert
    await expect(
      screen.findAllByText("Este campo es obligatorio."),
    ).resolves.toHaveLength(2);

    await waitFor(() => expect(spy).not.toHaveBeenCalled());
  });
});
```

El test anterior codifica el nuevo comportamiento que queremos validar. Veréis
que, en un primer vistazo, la apariencia del test es similar al primero que
creamos utilizando Cypress. La única diferencia es que aquí se prueba el
componente de manera aislada en lugar de simular a un usuario real utilizando la
aplicación. En Testing Library, no hay ningún navegador ejecutándose en
paralelo, como sí ocurre con Cypress; así, mientras el último que hemos escrito
podemos ejecutarlo en ~2 segundos, el primero necesita de ~22 segundos.

Cuando trabajamos a un nivel de granularidad más bajo, nuestros tests pueden
afectar al diseño de nuestros componentes (por lo general, haciéndolos más
sencillos de probar). En este caso, he decidido inyectar la función que gestiona
el envío del formulario para poder reemplazarla por un espía que me permita
validar que no se ha invocado cuando no debía (aunque también podríamos haber
espiado el módulo HTTP con [**nock**](https://github.com/nock/nock)). Este es
otro de los beneficios clave de TDD, ser capaces de ir definiendo el diseño de
nuestras interfaces a medida que escribimos las pruebas.

Como todos estos cambios no están repercutiendo en cambios de comportamiento a
nivel de aceptación, nuestro test de Cypress debería seguir pasando después de
cada modificación, ayudándonos de nuevo a garantizar que no hemos roto nada ✅.

Ahora, al igual que en el ejercicio anterior, tendríamos que escribir la menor
cantidad de código que sirva para hacer pasar este test.

> Pss! Podéis ver el ejemplo completo en
> [este repositorio de GitHub](https://github.com/codecoolture/octuweb-2020) 👀

## Conclusión

¿Que conseguiremos aplicando un flujo similar al anterior? En la literatura de
TDD, estaríamos aplicando lo que se conoce como
[Outside-In development with Double Loop TDD](http://coding-is-like-cooking.info/2013/04/outside-in-development-with-double-loop-tdd/)
o el proceso descrito en el libro
[Growing Object-Oriented Software, Guided by Tests](https://www.goodreads.com/book/show/4268826-growing-object-oriented-software-guided-by-tests).

Primero, arrancamos con un test de aceptación (o del nivel de granularidad más
alto que podamos) que nos ayudará a mantener el foco en la funcionalidad que
queremos resolver. En ocasiones, este test puede estar fallando durante varias
horas porque necesite de otros ciclos complementarios más pequeños que nos
ayuden avanzar (el ejemplo anterior era tan sencillo que no lo hemos
necesitado). Para esos ciclos complementarios es donde podemos hacer uso de
flujos como TDD clásico (útil para avanzar en piezas de bajo nivel como
funciones, clases, servicios) y herramientas como Testing Library (para probar
los diversos componentes que construyan la interfaz) o _simplemente_ Jest (para
lógica de negocio como controladores, funciones de utilidad, etc.).

## Otras referencias

- Además de los enlaces contenidos en el artículo, podéis encontrar más
  referencias a TDD en
  [esta página](https://www.notion.so/codecoolture/Public-References-50b1e927fe1641748f95610353e97b7f).
- Cypress tiene una sección de
  [mejores prácticas](https://docs.cypress.io/guides/references/best-practices.html)
  con algunos consejos muy útiles sobre cómo escribir pruebas de aceptación.
- [Kent C. Dodds](https://twitter.com/kentcdodds/) (creador de Testing Library)
  tiene bastantes artículos relacionados con testing de aplicaciones front-end
  (desde TDD hasta diferentes estrategias de testing). Podéis encontrarlos en
  [su blog](https://kentcdodds.com/blog?q=testing).


Test-driven front-end development

# Aplicando ATDD para resolver El Juego de la Vida

> Nota: en la literatura, ATDD suele ir acompañado de un conjunto de prácticas y
> herramientas más amplio que lo descrito en este artículo. Mi objetivo aquí es
> transmitir mi experiencia sobre cómo aplicar parte de sus principios para
> mejorar nuestra productividad a la hora de resolver determinados problemas,
> visto únicamente desde el plano de desarrollo de software.

Una de las situaciones más habituales que me he encontrado en los últimos años
cuando facilito coding dojos o coderetreats (donde muchas personas se enfrentan
por primera vez a resolver una _kata_ aplicando metodologías como TDD) es
observar cómo los participantes empiezan atacando el problema de una manera que
no les ayuda a avanzar, sino más bien les obliga a perderse en pequeños detalles
de implementación o incluso a sufrir de cierta _parálisis por análisis_.

Al principio, yo también pensaba que aplicar TDD debería ser suficiente por sí
mismo para evitar esa fricción inicial y tener _working software_ lo más rápido
posible, pero tras observarlo (y sufrirlo) durante varios años, me he dado
cuenta que no siempre es así. Cuando empezamos a trabajar con TDD es habitual
que tratemos de solucionar el problema desde aquellos puntos donde nos es más
sencillo poder aplicarlo (pequeñas piezas de bajo nivel, como una función
sencilla), aunque no sean las partes que nos ayuden a llegar antes a resolver el
problema (y por tanto, a entregar valor).

Como parte de la preparación para facilitar el
[GDCR19](https://www.coderetreat.org/), estuve trabajando en resolver el Juego
de la Vida utilizando un enfoque basado en
[ATDD](https://en.wikipedia.org/wiki/Acceptance_test%E2%80%93driven_development)
(_acceptance test-driven development_), una aplicación de TDD que nos obliga a
pensar en pruebas de muy alto nivel (aceptación) con la idea de tener una
versión desplegable de nuestro sistema con cada iteración.

## El síndrome de la página en blanco, o _ese_ primer test

Una de las ventajas de aplicar ATDD es que esa primera _crisis_ sobre cómo
atacar el problema me vino resuelta casi de base. En este caso, sabía que el
sistema debía ser un CLI que, a partir de un fichero de entrada, generase un
fichero de salida con la siguiente evolución del tablero
([aquí](http://codingdojo.org/kata/GameOfLife/#problem-description) tenéis un
enlace con las reglas del juego).

La primera porción de funcionalidad mínima (de alto nivel) que se me ocurrió
implementar fue un CLI que, dadas las condiciones anteriores, supiera
evolucionar un tablero con despoblación.

Seguramente, esta sea la diferencia más notable frente a tratar de resolver el
problema utilizando (únicamente) TDD a nivel unitario (de ahora en adelante,
UTDD -aunque no creo que este concepto esté definido en ningún sitio 😅). Con
UTDD nos vemos _obligados_ a detectar desde el principio una primera entidad
sobre la que escribir los tests, lo que en muchas ocasiones me ha hecho perder
el foco y caer en la trampa del
[Big Design Up Front](https://wiki.c2.com/?BigDesignUpFront).

```ts
const subject = join(__dirname, "../src/cli.ts");

it("supports underpopulation", () => {
  const inputFilename = join(__dirname, "./fixtures/underpopulation");
  const outputFilename = join(__dirname, "./results/underpopulation");

  play(`${subject} --input=${inputFilename} --output=${outputFilename}`);

  const result = getResult(outputFilename);

  expect(result).toEqual(["0 0 0", "0 0 0", "0 0 0"].join("\n"));
});
```

Pero vayamos paso a paso por el test anterior:

- La función `play` es un simple envoltorio que ejecuta en un shell la
  instrucción indicada. En este caso, nuestro ejecutable es el fichero
  `src/cli.ts` y se le pasan como parámetro ambos: el fichero de entrada con el
  tablero inicial y el fichero de salida donde guardar la evolución.
- Una vez ejecutado el script, recuperamos el resultado a partir del fichero de
  salida indicado y comprobamos que sea el resultado esperado.

ATDD sigue el mismo ciclo Red-Green-Refactor que TDD, por lo que en esta primera
iteración hemos sentado las expectativas tanto de un primer comportamiento del
sistema como de su propia interfaz para operar, sin tener aún nada de código de
producción implementado. Si estáis acostumbradas a trabajar con UTDD, es posible
que este primer test os parezca _demasiado grande_. Y es que con ATDD el **ciclo
de feedback** es mucho más largo.

## Añadiendo nuevos comportamientos

Con el test anterior en verde, ya dispondríamos de una versión 0.1.0 de nuestro
Juego de la Vida 🙂 Un CLI que, a partir de un fichero de entrada, sería capaz
de evolucionar el tablero detectando aquellas células que sufran de despoblación
y guardando el resultado en el fichero de salida indicado.

Pero para implementar el Juego de la Vida de manera completa, hay que tener en
cuenta también otros escenarios. El enfoque que apliqué para ello fue ir creando
un nuevo test para cada nuevo comportamiento. Así pues, tras implementar el
soporte para despoblación, el siguiente en la lista era el escenario de
sobrepoblación.

Con esa prueba también en verde, tendríamos una nueva versión 0.2.0 del sistema
lista para desplegar; esta vez, soportando ya un nuevo escenario. Este mismo
flujo se utilizaría para implementar el resto de reglas.

> Cada nuevo test define un nuevo comportamiento de alto nivel en el sistema. Al
> resolverlo, nuestro software debería estar listo para ser desplegado.

## ATDD y productividad

Seguramente, aplicar ATDD tampoco me hubiese ayudado a terminar de implementar
el Juego de la Vida en los 45 minutos que duran las sesiones de un coderetreat
🙃, pero sí creo que me habría permitido acercarme mucho más que si hubiese
intentado solucionar el sistema siguiendo una estrategia _bottom-up_.

Trabajar con tests de aceptación me ayudó a ganar foco y programar rápidamente
una solución que los pusiese en verde. Sentir que con cada prueba disfrutas de
un sistema desplegable (aunque su implementación no sea perfecta a nivel de
diseño) me parece un gran _boost_ de productividad. Con 4 pruebas, tienes las
reglas de negocio del Juego de la Vida cubiertas y puedes empezar a aplicar
_refactoring_ para extraer comportamientos a nuevas entidades de manera muy
confiable (los test de aceptación te aseguran que el sistema funciona punto a
punto -y esto, cuando sueles trabajar con muchos pequeños tests unitarios, está
muy bien).

## ATDD y UTDD

El Juego de la Vida es un problema sencillo, que prácticamente se resuelve con
unas pocas líneas de código. En sistemas más sofisticados, donde estemos
implementando funcionalidad más compleja, es muy habitual mezclar ambos ciclos
para disfrutar de las ventajas de ambos enfoques (lo más habitual es que
trabajemos con código _legacy_, donde aplicar UTDD es _sencillo_ al tener muchas
entidades de dominio ya modeladas en nuestro sistema).

Juntar ambas estrategias termina generando un _ciclo de ciclos_, donde el test
de aceptación está en rojo mientras que vamos aplicando ciclos de UTDD para
tratar de ponerlo en verde (y terminar de implementar ese nuevo comportamiento
de alto nivel en el sistema).

## Contenido relacionado

Si os habéis quedado con ganas de investigar un poco más, el libro
[Growing Object-Oriented Software, Guided by Tests](https://www.amazon.es/Growing-Object-Oriented-Software-Addison-Wesley-Signature-ebook/dp/B002TIOYVW)
cubre muy bien (y en profundidad) esta manera de trabajar y resolver los
problemas. Además, he publicado en
[GitHub](https://github.com/sergioalvz/practice/tree/master/game-of-life-atdd)
la implementación que utilicé para practicar con este enfoque mientras resolvía
el Juego de la Vida.

La estrategias comentadas en este artículo también se representan en la
literatura a través de los conceptos de **Inside Out** y **Outside In** (que se
cubren en detalle en
[este artículo](https://8thlight.com/blog/georgina-mcfadyen/2016/06/27/inside-out-tdd-vs-outside-in.html)).


Aplicando ATDD para resolver El Juego de la Vida

# Desacoplando la entrega de software de los sistemas de control de versiones

Como una extensión más de la
[ley de Conway](https://es.wikipedia.org/wiki/Ley_de_Conway), es muy habitual
encontrarse con proyectos donde la estrategia de _branching_ del sistema de
control de versiones está fuertemente relacionada con la estrategia de entrega
de software. Esta relación entre ambos mundos puede parecer conveniente (por
ejemplo: utilizar una rama para representar el código _vivo_ en producción o
_staging_, congelar los cambios que van a desplegarse en una rama `release/*`,
etc.) pero, con el paso del tiempo, puede traer consigo efectos
contraproducentes:

- **Viola el principio de responsabilidad única**. Si algo nos queda claro sobre
  el _Single Reponsability Principle_ es que cada abstracción sólo debe tener
  _una única razón para cambiar_ (en palabras de Robert C. Martin). Si cambios
  en los procesos de entrega de software (flujos de resolución de _hotfixes_,
  nuevos entornos) implican cambios en la estructura de nuestro repositorio (o
  cambios en la manera de interactuar con él), los límites entre ambos contextos
  no están bien establecidos.
- **Todo se vuelve innecesariamente complejo**. Aún con flujos muy populares
  como `git-flow` (y herramientas muy sofisticadas a su alrededor, construidas
  como una capa de abstracción sobre `git`), se _hackea_ el sistema de control
  de versiones para dejar de ser una herramienta de _tracking_ y colaboración
  por un sistema de despliegue y configuración.
- **Resta flexibilidad**. Si es el sistema de control de versiones el encargado
  de determinar qué funcionalidades se van a liberar al final de una iteración,
  se pueden dar situaciones en las que una rama se quede _congelada_ por
  contener funcionalidad defectuosa que inevitablemente contamina al resto de
  cambios de esa misma rama, bloqueando la entrega de nueva funcionalidad.

![Imagen de un repositorio que utiliza git-flow](/static/articles/decoupling-vcs-from-software-delivery/git-flow.jpg "Este repositorio utiliza el sistema de control de versiones como una herramienta de entrega de software para la próxima iteración (aplicando un flujo similar a git-flow)")

Para aliviar los problemas anteriores, una solución pasa por mover la
responsabilidad de decidir qué funcionalidades están disponibles en cada entorno
desde el sistema de control de versiones a la propia base de código. Es decir,
decidir programáticamente si una funcionalidad está habilitada o no en función
de en qué entorno se está ejecutando la aplicación.

Una representación habitual de este principio es a través del uso de
[Feature Flags](https://featureflags.io), que no dejan de ser, conceptualmente,
bloques condicionales que se sitúan en algún punto de nuestra base de código y
deciden si un camino de ejecución debe evaluarse o no.

Con esta estrategia, únicamente necesitaríamos una rama `master` donde fusionar
las _feature branches_ de funcionalidades terminadas y una configuración de
_feature flags_ que defina los entornos en los que estarían disponibles. Por
ejemplo: habilitar la funcionalidad únicamente en entornos de _staging_ para
realizar pruebas de rendimiento, labores de _quality assurance_, etc. La
resolución de hotfixes, se podría realizar igualmente sobre la rama `master`,
pues es esta la que siempre se despliega y define qué funcionalidades estarían
disponibles en cada momento y para cada entorno.

![Imagen de un repositorio con una única rama master y múltiples feature branches](/static/articles/decoupling-vcs-from-software-delivery/with-feature-flags.jpg "En este ejemplo, el repositorio es agnóstico de la capa de entrega de software, que estará gestionada por la propia base de código mediante el uso de feature toggles.")

Siguiendo esta dirección, también se obtendrían beneficios adicionales como, por
ejemplo, poder realizar _merges_ de manera mucho más recurrente (al estar el
entorno de producción siempre protegido a través de _feature flags_). Esto
podría derivar, a su vez, en procesos de _code review_ con un número menor de
cambios y ciclos de _feedback_ más cortos, siempre que lo combinemos con
técnicas como _continuous integration_ y _continuous delivery_.

## Otras lecturas relacionadas

- [Decoupling Deployment from Release - ThoughtWorks’ Technology Radar](https://www.thoughtworks.com/radar/techniques/decoupling-deployment-from-release)


Desacoplando la entrega de software de los sistemas de control de versiones

# React: MultipleRender

El síntoma más claro de este _code smell_ es la aparición de varios métodos de
instancia tipo `render` especializados en construir una parte de la UI de un
componente React. Suele aparecer especialmente en componentes complejos (o de
gran tamaño, como una página) cuando diferentes partes de la interfaz precisan
de alguna comprobación o cálculo extra que afecte a su representación.

```tsx
export class Blog extends React.Component<{ articles: Article[] }> {
  public render() {
    return (
      <>
        {this.renderHeader()}

        {this.renderArticles()}
      </>
    );
  }

  private renderHeader() {
    const {
      articles: { length: numberOfArticles },
    } = this.props;

    if (numberOfArticles === 0) {
      return (
        <header>
          <p>No articles 😯</p>
        </header>
      );
    }

    return (
      <header>
        <p>Yay! {numberOfArticles} articles 🎉</p>
      </header>
    );
  }

  private renderArticles() {
    return this.props.articles.map((article) => {
      return (
        <section>
          <h1>
            <a href={article.url}>{article.title}</a>
          </h1>
        </section>
      );
    });
  }
}
```

En el caso anterior, vemos que la representación de la cabecera de la página
varía en función del número de artículos que se vayan a mostrar. Del mismo modo
que la lógica para pintar la colección de artículos está encapsulada en su
propio método de instancia.

Con echar un simple vistazo al método `render`, ya vemos con claridad cuáles son
las verdaderas responsabilidades de nuestra página: definir un _layout_ que
muestre una cabecera y una colección de artículos.

¿Es, por tanto, responsabilidad de la página conocer los _internals_ de la
cabecera y la lógica necesaria para pintar la colección de artículos? No. Este
componente contiene más de una responsabilidad y no cumple con el
[Principio de Responsabilidad Única](https://en.wikipedia.org/wiki/Single_responsibility_principle).

Para mejorar nuestro diseño, bastaría con definir dos nuevos componentes que
encapsulen la lógica necesaria para pintar ambas partes. Con este enfoque,
ganaríamos cierta capacidad para reutilizar esos componentes en otros lugares de
nuestra interfaz (aunque no es condición necesaria para crear un nuevo
componente) a la vez que reducimos la complejidad del componente padre, que no
necesita ya llevar consigo toda la lógica de las diferentes partes que la
conforman.

Además, si seguís un enfoque de integración y entrega continua, veréis que es
mucho más sencillo [aplicar _feature flags_](/blog/branch-by-abstraction-react)
sobre estos pequeños componentes de vuestra interfaz en lugar de en mitad de
componentes grandes y complejos, donde se estarían mezclando responsabilidades y
requisitos de distintas partes de la aplicación.

```tsx
import { Articles } from "./components/Articles";
import { Header } from "./components/Header";

export function Blog(props: { articles: Article[] }) {
  return (
    <>
      <Header {...props} />

      <Articles {...props} />
    </>
  );
}
```

Este _code smell_ está relacionado con otros de propósito general (no
relacionados directamente con React) como
[_Large Class_](https://sourcemaking.com/refactoring/smells/large-class) y
técnicas de _refactoring_ como
[Extract Class](https://refactoring.guru/extract-class).


Code Smell: React.MultipleRender

# JavaScript: NakedCode

> Código que se escribe y, por tanto se ejecuta, sin estar encapsulado en ningún
> bloque o procedimiento (como por ejemplo una función o una clase).

En JavaScript, sufrimos de una relación de amor-odio con el contexto de
ejecución goblal. Hasta la aparición de los módulos en la especificación de ES6+
la manera más habitual de gestionar dependencias en nuestra aplicación era a
través de la variable global `window`, accesible desde cualquier punto de
nuestro programa.

Con los módulos, llegó una manera de gestionar esas dependencias de manera
explícita y favorecer técnicas como
[tree shaking](https://github.com/rollup/rollup#tree-shaking) para mejorar el
rendimiento de nuestras aplicaciones. Mientras que, a su vez, ganamos también
cierta capacidad para encapsular nuestro código y evitar que se ejecutase en el
contexto global de la aplicación, junto al resto de código de otros ficheros.

Sin embargo, sigue siendo habitual encontrar este tipo de
[code smell](https://martinfowler.com/bliki/CodeSmell.html) gracias a lo
sencillo de codificar directamente en el cuerpo de módulos ECMAScript:

```js
const repository = {};

export function addTodo(todo) {
  if (repository[todo.id]) {
    return;
  }

  repository[todo.id] = todo;
}
```

Aunque escribir código directamente en el cuerpo de un módulo tiene sus casos de
uso, tiene efectos laterales que pueden ser **no** evidentes:

- El código del módulo (sin encapsular) es ejecutado por el intérprete la
  primera vez que se importa, por lo que perdemos la habilidad de controlar
  cuándo evaluar un fragmento de código para, por ejemplo, establecer un
  escenario de ejecución determinado en nuestras pruebas.
- En el ejemplo anterior, la variable `repository` es un objeto _global_ (aunque
  únicamente accesible desde el propio cuerpo del módulo) que dificulta
  enormemente la capacidad de probar el código de manera unitaria, ya que hay
  que gestionar el estado de un variable sobre la que no tenemos acceso.
- Podemos incurrir en problemas de rendimiento (_memory leaks_), al disponer de
  una serie de variables globales sobre las que el recolector de basura no puede
  actuar en caso de no ser necesarias (siempre mantendrán -al menos- una
  referencia).

¿Cómo podríamos mejorar el caso anterior? Envolviendo el cuerpo del módulo en
una función `createRepository` que nos devuelva el control sobre el contexto de
ejecución del repositorio.

```js
export function createRepository(todos = {}) {
  const repository = { ...todos };

  return {
    addTodo(todo) {
      if (repository[todo.id]) {
        return;
      }

      repository[todo.id] = todo;
    },
  };
}
```

A pesar de los problemas anteriores, existen escenarios donde realmente sí
queramos ejecutar código en el cuerpo del módulo para poder beneficiarnos del
hecho de ser una suerte de
[_Singleton_](https://en.wikipedia.org/wiki/Singleton_pattern):

- Fichero `index` donde inicializar dependencias globales de la aplicación.

Cabe recordar que un _code smell_ no significa que algo esté _mal_. Simplemente
se refiere a un patrón que _puede_ (esto es importante) conllevar consigo males
de diseño. En este caso, a no ser que sea plenamente consciente de los efectos
laterales que conlleva, evito utilizar _naked code_ en el cuerpo de mis módulos
JavaScript.


Code Smell: JavaScript.NakedCode

# Branch by Abstraction en Componentes React

En ocasiones, nos vemos en la situación de tener que actualizar varios
componentes de nuestra interfaz de usuario para ajustarlos a nuevas directrices
de diseño. Otras veces, necesitamos reemplazar su implementación para hacer
frente a nuevos requisitos de negocio. Si el número de cambios es lo
suficientemente alto, es posible que no se puedan realizar de manera atómica (o
tengan que ser sincronizados con eventos fuera del control del equipo de
desarrollo como, por ejemplo, la publicación de una nueva imagen de marca) a la
vez que necesitamos continuar entregando valor en forma de nuevas
funcionalidades, corrigiendo defectos o aplicando alguna que otra mejora.

En este artículo vamos a hablar sobre una estrategia que nos permita obtener un
flujo de integración continua evitando, por tanto, mantener los cambios en
nuestros componentes en una rama independiente en el sistema de control de
versiones durante el transcurso de su desarrollo.

¿Cómo lo conseguiremos? Haciendo uso de dos técnicas muy habituales en equipos
que trabajan con prácticas como _continuous integration_ o _continuous
delivery_: [Feature Flags](http://featureflags.io/) (o Feature Toggles si
[leéis a Martin Fowler](https://martinfowler.com/bliki/FeatureToggle.html)) y
[Branch By Abstraction](https://martinfowler.com/bliki/BranchByAbstraction.html).

Ambas estrategias nos permitirán fusionar código de manera regular sobre la rama
principal, aún con funcionalidades parcialmente terminadas, evitando así
mantener ramas en paralelo que podrían estar días (o semanas) sin integrarse con
el trabajo realizado por el resto del equipo.

> Las feature flags son, conceptualmente, bloques condicionales que permiten
> habilitar o deshabilitar una funcionalidad (o un camino de ejecución) en base
> a un conjunto de condiciones (como pueden ser: el entorno de ejecución, el
> perfil del usuario o un porcentaje de tráfico)

Pongamos como ejemplo que, en nuestra aplicación, llevamos ya un tiempo
utilizando `<AwesomeCalendar />` (un componente de terceros) como _widget_ de
calendario. En los puntos donde es necesario mostrar un calendario, importamos
el componente y lo insertamos en el _layout_ de la página.

```tsx
import React from "react";

import { AwesomeCalendar } from "awesome-calendar";

function Page() {
  return (
    <Page>
      <Header />

      <Body>
        <AwesomeCalendar date={new Date(2018, 6, 21)} />
      </Body>
    </Page>
  );
}
```

Debido a una serie de requisitos, tenemos que crear un nuevo componente para
mostrar un calendario que sustituya a `AwesomeCalendar` y le añada un _extra_ de
funcionalidad para dar cabida a nuevas historias de usuario. El desarrollo del
componente se extenderá durante varias semanas.

El primer paso para poder integrar nuestro componente de manera continua es
asegurar que somos capaces de controlar cuándo y cómo se utiliza para poder
aislar a los consumidores de `AwesomeCalendar` de los cambios en el mismo. Para
ello, vamos a empezar creando una nueva _abstracción_ `Calendar` que pasará a
ser utilizada por el resto de componentes y mantendrá la misma interfaz que
ofrecía `AwesomeCalendar`:

```tsx
import React from "react";

import { AwesomeCalendar } from "awesome-calendar";

export function Calendar({ date }: { date: Date }) {
  return <AwesomeCalendar date={date} />;
}
```

Como vemos, la manera de consumir este nuevo componente sería muy parecida a la
versión anterior:

```tsx
import React from "react";

import { Calendar } from "../components";

function Page() {
  return (
    <Page>
      <Header />

      <Body>
        <Calendar date={new Date(2018, 6, 21)} />
      </Body>
    </Page>
  );
}
```

> En este punto, ya podríamos fusionar nuestros cambios con la rama de código
> principal para que el resto de trabajo en curso pueda ir haciendo uso de
> nuestro (no tan) _nuevo_ componente.

A continuación, vamos a crear una implementación muy sencilla de nuestro propio
calendario, que empezará apoyándose en una implementación nativa de `datetime`
pero respetando la interfaz original del componente `AwesomeCalendar`:

```tsx
import React from "react";

export function NewCalendar({ date }: { date: Date }) {
  const value = /* implementation details */;

  return <input type="datetime-local" value={value} />;
}
```

Una vez hemos eliminado la responsabilidad de elegir qué calendario utilizar de
los consumidores del componente, podemos utilizar _feature flags_ para
determinar qué calendario mostrar en cada momento.

En este caso, vamos a permitir que cualquier entorno que **no sea producción**
utilice siempre nuestro propio calendario, con el objetivo de obtener _feedback_
sobre su experiencia de uso a medida que avanzamos en su desarrollo:

```ts
export function isNewCalendarEnabled() {
  return process.env.NODE_ENV !== "production";
}
```

> Este caso, representamos la feature flag con una simple función que comprueba
> el entorno de ejecución actual, pero existen
> [sistemas más sofisticados](https://github.com/Unleash/unleash) para gestionar
> el estado de los _toggles_ en nuestra aplicación.

Ahora, nuestra nueva abstracción `Calendar` (que hace las veces de factoría)
puede hacer uso de esta función para determinar qué componente de calendario
utilizar, manteniendo al resto de consumidores aislados de toda complejidad:

```tsx
import React from "react";

import { AwesomeCalendar } from "awesome-calendar";

import { NewCalendar } from "./components";

import { isNewCalendarEnabled } from "../features";

export function Calendar(props: { date: Date }) {
  return isNewCalendarEnabled() ? (
    <NewCalendar {...props} />
  ) : (
    <AwesomeCalendar {...props} />
  );
}
```

A partir de este momento, todas las pantallas de nuestra interfaz de usuario que
necesiten de un calendario, utilizarán la abstracción `Calendar` y será esta
misma abstracción la que se encargará de utilizar la implementación concreta del
calendario que corresponda en función del entorno de ejecución.

Como vemos, aplicar técnicas como _branch by abstraction_ y _feature flags_ nos
permite alcanzar un flujo de integración (y entrega) continua en nuestros
componentes aportándonos beneficios cómo:

- Minimizar la superficie de cambios a fusionar cuando integramos trabajo en
  curso
- Tomar el control sobre cuándo se ejercita un camino de ejecución y poder
  habilitarlo y deshabilitarlo en base a una serie de condiciones
- Dotar a los equipos de negocio de visibilidad sobre el trabajo en curso en
  tareas de larga duración (sin sacrificar ninguna de las premisas anteriores)


Blog

2024

2022

2021

2020

2019