Testing Time-Based Features with Cypress

Thinking about time is hard. Testing software is hard too. Testing time-based software can be brutal. In this article, I'll explain some techniques that simplify time-based software feature testing.

What do you mean by "time-based" feature?

Usually, software doesn't care what time it is. For example, a social media timeline only has one time state: past. There is no such thing as a social media post in a future state because the post hasn't been created yet.

Now, let's use a different example like a digital itinerary. The itinerary contains reservations that represent a single date and time.

Here are some hypothetical acceptance criteria for the digital itinerary:

As a user, when I view...
A future reservation, I want to see a "Cancel" button.
A current reservation, I want to see the date as "Today".
A past reservation, I want to see a "Send Receipt" button.

You can see how this complicates things. The user wants different functionality based on what time they are viewing the same data.

In the next section, I'll dive into some code and show how to build this feature.

Building The Feature

I'm not going to dive super deep here. Instead, I'll show a quick overview of how I built the hypothetical itinerary feature.

First, I created and ran a new SPA using create-react-app.

Once the app was running, I added a fake reservations API to simulate our reservations server:

// src/api/getReservations.js

const reservations = [
  {
	id: 1,
	name: "Donnie's Pizzeria",
	dateTime: "2021-10-10T14:48:00",
  },
];

export const getReservations = async (userId) => {
  return new Promise((resolve, reject) => {
	setTimeout(() => {
  	resolve(reservations);
	}, 500);
  });
};

Next, I create a ReservationCard component to display the reservations:

// src/components/ReservationCard.js

import React from "react";

const isSameDay = (date1, date2) =>
  date1.getDate() === date2.getDate() &&
  date1.getMonth() === date2.getMonth() &&
  date1.getFullYear() === date2.getFullYear();

export function ReservationCard({ reservation: { id, name, dateTime } }) {
  const reservationDate = new Date(dateTime);
  const today = new Date();

  const displayDate = isSameDay(today, reservationDate)
	? "Today"
	: reservationDate.toDateString();

  return (
	<div style={reservationCardStyle}>
  	<div>{name}</div>
  	<br />
  	<div>
    	<strong>Date:</strong> {displayDate}
  	</div>
  	<br />
  	<button>{today < reservationDate ? "Cancel" : "Send Receipt"}</button>
	</div>
  );
}

const reservationCardStyle = {
  backgroundColor: "aliceblue",
  width: 400,
  margin: "0 auto",
  padding: "1rem 2rem",
  border: "1px solid #ddd",
  borderRadius: 8,
};

Finally, I will rework App.js to fetch our reservations and render them:

// src/App.js

import React, { useState, useEffect } from "react";
import { getReservations } from "./api/getReservations";
import { ReservationCard } from "./components/ReservationCard";
import "./App.css";

function App() {
  const myUserId = 1;
  const [reservations, setReservations] = useState([]);

  useEffect(() => {
	const fetchReservationsAndSet = async () => {
  	let response = await getReservations(myUserId);
  	setReservations(response);
	};

	fetchReservationsAndSet();
  }, []);

  return (
	<div className="App">
  	<h1>Itinerary</h1>
  	{reservations.length === 0 && <div>Loading...</div>}
  	{reservations.length !== 0 && (
    	<>
      	{reservations.map((reservation) => (
        	<ReservationCard key={reservation.id} reservation={reservation} />
      	))}
    	</>
  	)}
	</div>
  );
}

export default App;

The finished product should look something like this:

Notice that in src/api/getReservations.js I've hard-coded the reservation dateTime as "2021-10-10T14:48:00". This is simulating a reservation in the database for Donnie's Pizzeria on Oct. 10th, 2021.

Depending on when you're running this code, the reservation card displays different content. This illustrates the complexity of time-based features.

Testing The Feature

Now that the feature is working, we need to test it. This article is about testing with Cypress, but the same principles apply elsewhere.

First, let's install Cypress and then run it.

Now let's write our test:

// cypress/integration/app.spec.js

describe("Itinerary App", () => {
  before(() => {
	cy.visit("http://localhost:3000/");
  });

  it("displays an Itinerary", () => {
	cy.contains("Itinerary");
  });

  it("displays a reservation", () => {
	cy.contains("Donnie's Pizzeria");
	cy.contains("Sun Oct 10 2021");
	cy.contains("Send Receipt");
  });
});

Now make sure the react app is running at http://localhost:3000 and then run your test.

Can you spot the issues with this test?

If you run the test on Oct. 10th, 2021 then the reservation card will display "Today" instead of "Sun Oct 10, 2021".

If you run the test before Oct. 10th then the button will show "Cancel" instead of "Send Receipt".

This test is flaky because it will pass or fail depending on what time the test is run. Flaky tests slow down development and can take a lot of time to debug. This is bad!

In the next section, I'll explain how to fix this flaky test.

Fixing The Flaky Tests

The problem with this test is that we don't have control over when it is run. That means we don't control which time state we are testing in (i.e. past, present, future).

This is where cy.clock() comes in.

Let's rewrite our test using cy.clock to simulate all three-time states:

// cypress/integration/app.spec.js

const url = "http://localhost:3000";

describe("Itinerary App", () => {
  it("displays an Itinerary with a reservation", () => {
	cy.visit(url);
	cy.contains("Itinerary");
	cy.contains("Donnie's Pizzeria");
  });

  // Reservation dateTime: 2021-10-10T14:48:00
  describe("viewing a future reservation", () => {
	before(() => {
  	const now = new Date(Date.parse("2021-01-01")).getTime();
  	cy.clock(now, ["Date"]); // Set "now" to BEFORE reservation
  	cy.visit(url);
	});

	it("displays the date and a cancel button", () => {
  	cy.contains("Sun Oct 10 2021");
  	cy.contains("Cancel");
	});
  });

  describe("viewing a current reservation", () => {
	before(() => {
  	const now = new Date(Date.parse("2021-10-10T14:48:00")).getTime();
  	cy.clock(now, ["Date"]); // Set "now" to SAME DAY as reservation
  	cy.visit(url);
	});

	it("displays the date and a cancel button", () => {
  	cy.contains("Today");
	});
  });

  describe("viewing a past reservation", () => {
	before(() => {
  	const now = new Date(Date.parse("2021-12-31")).getTime();
  	cy.clock(now, ["Date"]); // Set "now" to AFTER reservation
  	cy.visit(url);
	});

	it("displays the date and a send receipt button", () => {
  	cy.contains("Sun Oct 10 2021");
  	cy.contains("Send Receipt");
	});
  });
});

Great! Now our tests are passing regardless of when they are run. We are confident that our feature works in past, present, and future states.

Let's take a look at what we did here, and then I'll wrap up.

First, we split up our tests into past, present, and future scenarios.

Next, before each test suite runs we mock the system date using cy.clock.

We know that our reservation date is Oct. 10th, 2021. If we mock 'now' as Jan 1st, 2021, then we are simulating a user who is viewing an upcoming reservation! Similarly, if we mock 'now' as Dec 31st, 2021 then we are simulating a user viewing a past reservation.

IMPORTANT: It's crucial that you include the ["Date"] as the second parameter to cy.clock. If you fail to do this, then other time-related functions such as setTimeout will stop working.

Conclusion

In this article, we used cy.clock to write consistent tests for a time-based feature.

We learned:

• that time-based features are complex because they have different functionality for past, present, and future states
• writing tests for time-based features are prone to flakiness
• we need to separate tests for past, present, and future scenarios
• we need to mock the system date & time using cy.clock to simulate different time scenarios

Thanks for reading, and good luck building (and testing) your time-based feature!