Forem: Jake Marsh

Prompting Users to Reload Your Next.js App After an Update

Jake Marsh — Mon, 05 Apr 2021 16:37:25 +0000

The pages of a Next.js application are served in one of two ways: server-side rendering, or client-side rendering. It's important to understand the distinction, and when each scenario occurs. (There is also static generation, but we will disregard that for this walkthrough.)

Server-side rendering is when the underlying Node.js server is handling the request, loading the corresponding page component (and any data dependencies), and returning the populated HTML that results. A page will be server-side rendered if it's the initial request to load the page, and the page implements either getInitialProps or getServerSideProps.

Client-side rendering is when the Javascript in the browser has taken over the handling of the request, and React will handle rendering the new page component and reconciling any differences. Client-side rendering occurs when the user has already loaded your application, and is navigating via the Next.js router (either directly) or via the <Link /> component.

The important caveat with client-side rendering is that once the user has loaded the application and each of the pages, requests are no longer being made to the server to render any of them -- the client is handling it all. This means that if you deploy a new version of your application while someone is using it, they could continue seeing and using the previous version of your application until they happen to reload.

This can cause issues if you're making breaking changes, or fixing bugs, or making any other changes you'd prefer your users see ASAP. This risk is multiplied by the number of people using your application. So how can you handle new deploys on the client to ensure our users get the latest version?

Next.js allows customizing the Webpack configuration used at build time via a next.config.js file. It will automatically pass in various relevant arguments; the one that we're interested in is buildId. By default, this is a random string unique to each build.

Combined with Webpack's DefinePlugin, you can expose this buildId to our application by replacing any checks for process.env.BUILD_ID with the real buildId:



// next.config.js

module.exports = {
  ...
  webpack(config, { buildId }) {
    config.plugins.push(
      new webpack.DefinePlugin({
        'process.env': {
          BUILD_ID: JSON.stringify(buildId),
        },
      }),
    );

    return config;
  },
};

This means that the resulting bundles served on the client will have the real buildId available to them when checking process.env.BUILD_ID. Since these bundles stay loaded as client-side navigation occurs, this will remain a static reference to the buildId loaded on the client.

Next, you'll want to also expose this process.env.BUILD_ID variable in our server-side environment. This is because when you deploy a new version of your application, anything being handled by the server will immediately be operating on the newest version. You can do this via Next.js's API routes:



// pages/api/build-id.ts

import { NextApiRequest, NextApiResponse } from 'next';

export default (_req: NextApiRequest, res: NextApiResponse): void => {
  res.status(200).json({
    buildId: process.env.BUILD_ID,
  });
};

With this new endpoint exposing process.env.BUILD_ID from the server, you have a route we can hit at any time to get the newest deployed buildId: /api/build-id.

Since the client will now have a static reference to its own buildId, and the server now has the endpoint always returning the newest buildId, we can implement our own polling and diffing to determine if the user needs to reload. Below is a component that encapsulates this logic, polling for the latest buildId every 30 seconds via a useInterval hook. This can then be rendered anywhere in your application.



import { useEffect, useRef } from 'react';
import request from 'superagent';

function useInterval<P extends Function>(
  callback: P,
  { interval, lead }: { interval: number; lead?: boolean },
): void {
  const savedCallback = useRef<P>(null);

  useEffect(() => {
    savedCallback.current = callback;
  }, [callback]);

  useEffect(() => {
    const tick = (): void => savedCallback.current();

    lead && tick();

    if (interval !== null) {
      const id = setInterval(tick, interval);

      return () => clearInterval(id);
    }
  }, [interval]);
}

export function DeployRefreshManager(): JSX.Element {
  useInterval(
    async () => {
      const { buildId } = (await request.get('/api/build-id')).body;

      if (buildId && process.env.BUILD_ID && buildId !== process.env.BUILD_ID) {
        // There's a new version deployed that we need to load
      }
    },
    { interval: 30000 },
  );

  return null;
}

At walrus.ai, we display a non-closable modal to the user with just one possible action: reloading the page. Clicking this button simply calls window.location.reload().

This is achieved by simply setting a boolean state value in the above if statement, and conditionally returning your modal element from the component instead of always returning null.

You'll now be able to rely on the fact that your users are always using the latest version of your application, or at least being prevented from taking actions until they've reloaded.

Writing Resilient End-to-End Tests

Jake Marsh — Mon, 20 Apr 2020 18:38:03 +0000

What is end-to-end testing?

End-to-end testing is the process of testing your application through replicating the expected full flows and behaviors of an end user. For example, if you wanted to test that an application's signup flow was working, you would use code to automatically navigate and complete the signup flow in the browser just like a user.

By testing the full functionality of your application in this manner, you're ensuring everything is working as expected from the client, to the API, to the database. It eliminates the seams that occur when unit testing each parts of your application in isolation.

If it's possible to gain more confidence with end-to-end tests, why don't people do more of it? Because it's hard. One of the biggest issues is resiliency: what happens if you change the text of a button that your test was looking for? What happens if you hit a network spike and something takes longer than expected? Without handling cases like these, your end-to-end tests are likely to start failing.

Why is resiliency important?

In a perfect world, end-to-end tests should be run any time a change is made to your application. This is because the smallest (perceived) change is always capable of causing unforeseen issues throughout the rest of your application. To achieve this, teams will typically execute their end-to-end tests within their CI/CD pipeline.

If your end-to-end tests are running inside your CI/CD pipeline, that means they're directly intertwined with your deployment process. Any delays or failures will impede (or prevent) the deployment from completing. Change the button text in your signup flow from "Next" to "Continue"? If your tests weren't updated for that change, you're about to hit a deployment failure and lose up to 30 minutes of precious time.

What is a flake, and what causes them?

A "flake" is a (usually) non-deterministic failure caused by something that is either intermittent or unexpected. Due to the nature of end-to-end tests and the many layers involved, a flake can be caused by any number of things. Some of the more common examples are:

Asynchronous delays. If submitting a form on your page suddenly takes 5 seconds instead of 2, the page will not be behaving as your tests may expect. Spinners may stick around, buttons may not re-enable.
Identifier changes. As we've mentioned, changing something like the text of a button could cause failures. That's also true of non-user-facing identifiers such as HTML classes or IDs, which can change at any time due to unrelated engineering updates.
Actual application/UX changes. In the case that your team has actually carried out a large redesign or refactor of your application, your existing tests are very likely to start failing.

Flakes and How to Avoid Them

Asynchronous Delays

Asynchronous delays, often resulting from network requests, are the largest and broadest category of test flakes. This is because asynchronous requests are happening quite often in an average web application, affecting many other parts of the app.

Submitting the login form? Waiting for a response from the API. Trying to view a list of data? Waiting for data to be fetched. Just clicked a button? Waiting for the request to finish before updating the UI. You may even have to wait on something like an email being sent and arriving in your test inbox.

These are all examples of things that most end-to-end tests will be doing often: navigating, filling out forms, clicking elements, waiting for things to happen. And they're all unpredictable!

What can you do?

There are a few things you can do in your end-to-end tests to better handle any form of asynchronous delay. None of these are foolproof, but they should get most of the way to resiliency around these issues.

1. Explicitly wait on network requests when possible. Many testing libraries provide APIs to hook into the loading status of the browser page. This can be done when you're submitting a form that you know will result in a redirect, or when you're clicking a link. In Puppeteer, for example, they provide page.waitForNavigation(). Clicking a button to submit a form, then, might look something like this:

await Promise.all([
   page.waitForNavigation(),
   page.click('button[type="submit"]'),
]);

2. Wait often to allow for arbitrary load times. Even when using a helper like waitForNavigation, there may be additional delay involved post-request. For example, the application may take a second or two to enable the button you'll be clicking next. In instances like these, it can be helpful to have a simple wait helper to wait a small amount of hardcoded time before proceeding:

// Helper
function wait(time) {
  return new Promise((resolve) => setTimeout(resolve, time));
}  

// Usage
await Promise.all([
    page.waitForNavigation(),
    page.click('button[type="submit"]'),
]);

await wait(2000);
await page.click('.some-later-rendered-element');

3. Use polling. Many testing libraries will provide a method (or its easy to write your own), that "polls" for an element on the screen. This makes your test more resilient to those millisecond differences when finding an element to operate on.

// Bad
await page.click('button');

// Good
await (await page.waitForSelector('button')).click();

If you're testing some process that can be particularly long and/or unpredictable such as querying a large set of data for a new entry, or receiving an email, it can be helpful to carry out your logic and assertions in a custom polling method. This means you're checking on some defined interval for the assertion (i.e. "my data entry did appear"), with a hardcoded timeout that determines a "failure".

await pollUntilTimeout(async () => {
   return !!(await page.$('.some-new-element'));
}, {
   intervalMs: 1000,
   timeoutMs: 30000,
   timeoutMessage: 'New element not found.',
});

Identifier Changes

Most identifiers or attributes used in testing exist for other purposes. Classes, for example, are primarily used for styling. Element tags are used for DOM layout and specific to element purpose. Any time one of these identifiers is changed for their real purpose (updating a button's styling, changing a button to a link), your tests can break.

One option is to define and enforce strict rules around naming behaviors and update processes for element identifiers. For example, you could add a new class to every element you'll be using in your test, prefixed with test-, and ensure those are always kept in sync. However, this can be a painful process to remember and enforce.

Ideally, you can write your tests to be better prepared for changes to identifiers.

What can you do?

1. Avoid relying on "internals". Things like class and id should generally be avoided and assumed to be unstable, as they may change at any time due to internal engineering efforts. Of course there may still be scenarios in which you have no other option, but be prepared for changes to affect your tests.

// Bad
await page.$('input.form--input.some-styling.text');

// Good
await page.$("input[type='text'");

2. Use selectors based on actual functionality to the end-user. Since the goal of your end-to-end test is to ensure that an end-user is still able to complete some flow, it makes sense that it should be written in the same way a user may look for something. A user of your application isn't going to be looking for the selector button.btn.btn--green when they want to create a new post, they'll look for a button that contains the words "Create Post".

// Bad
await page.click('button.btn.btn--green');

// Good
await (await page.waitForXPath("//button[contains(., 'Create Post')]"));

3. Be (reasonably) lenient with your matchers. In the example above, we're searching for a button with the text "Create Post". But what if a change is made and it now says "Create New Post"? Barely anything has changed, but your test is going to break. If there's no other conflicts on the page, it can be helpful to loosen your matcher. What if we just search for "Create"?

// Bad
await (await page.waitForXPath("//button[contains(., 'Create Post')]"));

// Good
await (await page.waitForXPath("//button[contains(., 'Create')]"));

Real Application/UX Changes

The last major cause of end-to-end test failures are larger instances of what we've already discussed: intentional changes to your application and/or UX. If your signup flow, for example, is completely redesigned from the ground up, your test logic and matchers will likely no longer be correct.

Although this class of changes is least common, they are by far the most expensive in terms of time to update the applicable end-to-end tests. There's not much you can do in your tests to prepare for large sweeping changes, due to the need to balance non-colliding and specific matchers with the possibility of an entirely different page.

What can you do?

walrus.ai is a new solution for end-to-end testing with ease. All you provide is a user story written in plain English instructions, and the test is then interpreted and executed by a human and automated for all future runs. Any changes or flakes are handled, and so your tests will only fail when there's a true failure.

An Introduction to End-to-End Testing

Jake Marsh — Mon, 11 Nov 2019 19:04:30 +0000

What are end-to-end tests?

You can think of automated tests as existing on a spectrum. Although they're all valuable, it's helpful to know the difference between the various types and when to use them.

At one end are unit tests, used to test the functionality of individual methods or components. These are helpful for ensuring that the core building blocks of your applications function as expected in isolation.

In the middle are integration tests. These are tests abstracted up a level from unit tests, executing and asserting on code paths that traverse between multiple units or modules. Now we're starting to ensure the different pieces of our application interact with each other as expected.

Lastly, on the opposite end, are end-to-end (E2E) tests. These are tests aimed to cover the entire surface area of your application from top to bottom. These should generally follow the code paths expected from your end-users to ensure they're as close to reality as possible.

Why should you write end-to-end tests?

In the typical "testing pyramid" (above), E2E tests represent the very top of the pyramid. This is due to the fact that they can be expensive and slow both to write and maintain, and so should make up a smaller percentage of the tests your team is responsible for. What people typically fail to mention around this pyramid, however, is that as you move up the tiers of the pyramid each form of testing is providing you with more confidence.

Why exactly do end-to-end tests provide more confidence? As mentioned before, they should emulate a real user as closely as possible. This means that when one of your E2E tests results in a real failure, you're catching a bug that a real user would have found on their own later. This is much more helpful than a unit test telling me my individual method returns the correct string, or my integration test telling me that my endpoint correctly invokes my method.

And so why, then, is E2E the smallest tier of the testing pyramid? As we touched on above, E2E tests have historically been slow, painful, and expensive for a team to maintain. Frameworks were hard to set up and use, tests were flaky for a variety of common reasons, and often times companies even had manual QA teams to fill this role.

Luckily, things have changed and end-to-end tests are more feasible than ever before.

How do you begin writing end-to-end tests?

Now that we understand what E2E tests are and why they're important, how do we begin to implement them? Let's go over some popular options for web applications today.

For the examples below, let's assume we're testing Amazon's "Add to Cart" functionality. We're going to search for "shoes", add a result to our cart, and simply ensure it's actually in the cart.

Puppeteer (+ Jest)

Puppeteer is a Node library by Google for running a "headless" instance of Chrome. Longstanding and widely known, it's been a large presence in the testing community for some time now. It allows you to programmatically interface with and manipulate Chrome (or Chromium).

Since Puppeteer itself is not intended solely for testing purposes, it must be combined with an existing testing library in order to test and assert as we'd expect (pun intended). Jest is the most popular Javascript option, and can be paired with Puppeteer using jest-puppeteer.

describe('amazon.com', () => {
    beforeAll(async () => {
        await page.goto('https://amazon.com');
    });

    it('should allow adding to cart', async () => {
        const searchInput = await page.$('input#twotabsearchtextbox');
        searchInput.type('shoes');

        const productLink = await page.$('#SEARCH_RESULTS-SEARCH_RESULTS a');
        const productTitle = productLink.evaluate((node) => node.innerText);

        await productLink.click();
        await page.click('#add-to-cart-button');

        await page.click('#hlb-view-cart');
        await page.waitForFunction(`document.querySelector(".sc-product-link").innerText.includes("${productTitle}")`);
    });
});

Selenium (+ Jest)

Selenium WebDriver is another API for automating and interfacing with the browser. As opposed to Puppeteer, Selenium has support for every popular browser.

Like Puppeteer, Selenium itself does not provide testing or assertion functionality. However, we have another way to integrate with Jest: jest-environment-webdriver.

describe('amazon.com', () => {
    beforeAll(async () => {
        await page.goto('https://amazon.com');
    });

    it('should allow adding to cart', () => {
        const searchInput = driver.findElement(By.css('input#twotabsearchtextbox'));
        searchInput.sendKeys('shoes');

        const productLink = driver.findElement(By.css('#SEARCH_RESULTS-SEARCH_RESULTS a'));
        const productName = productLink.getText();

        productLink.click();
        driver.findElement(By.css('#add-to-cart-button')).click();

        driver.findElement(By.css('#hlb-view-cart')).click();
        expect(driver.findElements(By.css('.sc-product-link'))).resolves.toHaveText(productName);
    });
});

cypress.io

Possibly the most popular option today, cypress.io is a Javascript framework and SaaS offering for E2E testing your application. Through their framework and CLI, it's fairly easy to get started writing a simple Javascript test and seeing the results.

describe('amazon.com', () => {
    beforeAll(() => {
        cy.visit('https://amazon.com');
    });

    it('should allow adding to cart', () => {
        const searchInput = cy.get('input#twotabsearchtextbox');
        searchInput.type('shoes');

        const productLink = cy.get('#SEARCH_RESULTS-SEARCH_RESULTS a');
        const productName = productLink.invoke('text');

        productLink.click();
        cy.contains('Add to Cart').click();

        cy.contains('Cart').click();
        cy.contains(productName);
    });
});

walrus.ai

walrus.ai is a new, developer-first SaaS option looking to abstract away the complexities and pain points of true end-to-end testing. Through a combination of AI and human verification, walrus.ai allows developers to specify tests in plain English and with just a single API call.

walrus -a YOUR_API_TOKEN -u https://amazon.com -i \
    'Search for "shoes"' \
    ‘Add a result to your shopping cart’ \
    'Ensure the shoes are in your cart'

Notice how many fewer instructions we need thanks to the use of human-readable sentences? Due to their higher-level description, they're also inherently less fragile than specific selectors.

It's also free to get started with walrus.ai to see if it makes sense for you. Try it out today!

Wrapping up

If you didn't already, hopefully you now understand the difference between the various types of automated tests, as well as the benefits of writing end-to-end tests for your application. Maybe you've even used walrus.ai to get your first E2E test running ASAP!

In a future post, we'll discuss best practices for ensuring your end-to-end tests are both resilient and robust.

How to Choose and Track User Events to Build a Better Product

Jake Marsh — Wed, 09 Oct 2019 16:12:13 +0000

Online products are unique in the richness of user data they have available. Every action you take, whether hovering over an ad, clicking a link, or making a keystroke, can be tracked. This one concept has led to an entire industry of “big data”, valued most highly by ad companies. It’s for this reason that the practice has been in the headlines and at the top of minds recently.

That being said, user activity is still a highly valuable source of information for applications not serving ads, but rather looking to improve their products for the sake of their users. This data is not only valuable for identifying user preferences, it is also key for understanding trends in user behavior. That’s why it’s important to still consider and implement event tracking when building a paid product.

Monolist is the command center for engineers — tasks, pull requests, messages, docs — all in one place. Learn more or try it for free.

🎥 Tracking from the Get-Go

There are three main advantages to tracking user events as soon as you’re able.

Set a precedent. By tracking the right user events early, you’re working to set a precedent that this should be followed for all future user-facing features being shipped. This is a good practice to maintain to avoid event tracking becoming an afterthought or post-launch effort.
Get the architecture in place. Tackling event tracking early on and in a flexible manner means you’ll have the code and APIs in place for tracking events quickly, easily, and long into the future. We’ll go into more detail on this below.
Start learning ASAP. This one should be obvious - the sooner you’re gathering the data, the sooner you can learn from it. If you’re tracking events from your first acquired user, you’re that much closer to improving the experience for your next user.

🔑 Deciding What to Track

There are two aspects to a user event that you track: the action the event represents (“user clicked on log in button”), and the data you choose to associate with that event ({ user_id: 123 }).

What events should be tracked?

It’s important to carefully consider what events get tracked and persisted. There are a few questions you should ask when determining if something is worth tracking.

Is this an action the user took directly? For example, did they interact with an element or trigger an update? If the event occurs automatically or passively, it should likely not be tracked.
Does this action happen at a reasonable interval? An example of an event that a user may trigger quite often would be a mouseover or hover event on an element. In this case, the event should probably not be tracked as it’ll introduce noise to your data, and it really won’t tell you much.
Could this event tell us something about user behavior? The answer to this question is most often yes, but it’s still a good one to consider. If you’re tracking an irrelevant (or likely inevitable) event like “user pressed the ‘y’ key”, it may not be valuable to track.

What data should be included with an event?

This is when it’s most important to find the balance between user privacy and data availability. When attaching a data payload to a user event, it’s important to minimize (or ideally eliminate) any personal or identifying user about the info. The data should be pared down to the bare minimum needed to infer your learnings about the user’s experience. This is because you’ll most likely end up persisting your user events in a third-party service.

An example of a bad payload might look something like this:

{
    "user_email": “john.doe@gmail.com”,
    "user_full_name": “John Doe”,
    "email_sent": “This is the body of an email I’m composing to a close friend.”
}

A good payload, on the other hand, might look something more like this:

{
    "user_gid": “abc-123”,
    "sent_email_gid": “def-456”
}

Notice the difference? Rather than the raw data that is both identifying and personal, we only associate the event with the top-level (externalized) identifiers that we can use to then match to the proper entities internally.

🛠 Architecting Your Tracking Framework

Now that we’ve discussed how to select what events you’re tracking, along with what data they entail, what’s the best way to incorporate this into our application?

Determine where the events take place

Here at Monolist, we use React for our UI and Redux for our data management. Together, these give us two fairly well-defined places that an event can occur: inside the UI, i.e. a React component, or inside a Redux action, i.e. when making an API call.

function handleButtonClick() {
    // We could track this event
}

function closeActionItem() {
    return (dispatch) => {
        // We could also track this event
    };
}

In general, we prefer the latter approach: centralizing our tracking in our Redux actions. This gives us one place and one common approach for tracking an event, making it easy to find and understand. It also allows us to easily track events across platforms since we share our Redux code between our web and react-native clients. However, tracking within a component is still sometimes necessary when we want insight into lighter actions that don’t necessarily update the Redux store.

Determine where to send the events

The actual event tracking method we call is also a Redux action, providing us a familiar method of invocation. This looks something like this:

export const trackUserEvent = (
  eventName: string,
  eventData?: object,
) => {
  return async () => {
    if (process.env.NODE_ENV === 'production') {
        await api.post(
          '/analytics/user-event',
          {
            eventName,
            eventData,
          },
        );
    }
  };
};

As you can see, it’s fairly straight forward: if we’re in the production environment, send the event and its data back to our API. We send the data back to our API (rather than directly to a third-party service for three reasons:

This allows the API to carry out any additional data scrubbing we may want to define.
This allows us to carry out the third-party pushing in an async queue, ensuring the event gets persisted regardless of further UI interaction (user unloads page, etc.)
We now have one point of third-party contact to modify (in the case of a service provider switch, etc.)

The examples we provided earlier end up looking like this:

async function handleOpenClick() {
    await props.onTrackUserEvent(‘open-item-click’);
}

function closeActionItem() {
    Return (dispatch) => {
    dispatch(analyticsActions.trackUserEvent(‘close-action-item’));
    };
}

Determine where to put the data

As we mentioned above, the primary reason for being strict about the data we persist for an event is that we may want to send our data to a third-party. There are many services dedicated to tracking your user events and helping you to analyze them (we use Mixpanel here at Monolist). These are great for being able to easily parse and visualize your data without additional engineering work. This also means your PM can even dive into the data themselves.

Mixpanel has a relatively straight-forward API, which makes it easy for us to integrate from our Rails API. The endpoint that the above Redux action hits looks something like this:

def track_user_event
    PushUserEventWorker.perform_async(user_event.id)
    head 200
end

As you can see, it does just one thing: creates an async job to push the event to our third-party (Mixpanel). That worker then makes a quick API call:

class PushUserEventWorker
  include Sidekiq::Worker

  def perform(user_event_id)
    user_event = UserEvent.find(user_event_id)
    mixpanel = Mixpanel::Tracker.new(ENV["MIXPANEL_CLIENT_ID"])

    event_data = user_event.event_data || {}

    mixpanel.track(user_event.user.id, user_event.event_name, event_data, user_event.ip_address)
  end
end

This worker is now our single point of third-party contact if we ever decide to switch providers.

An alternative to this approach would be to use something like Redshift to store your data, and then write in-house tooling to use the data however you see fit. Although this is a much larger undertaking, it’ll likely provide you more control over your data and analysis (and save you a few dollars).

📊 Analyzing the Data

Once the data is stored, parsed, and visualized as we’ve described above, it’s up to you and your team to infer learnings from the data. Is that new signup flow seeing more engagement? Is the new feature you released last week resulting in any additional invites?

How has your team used event tracking to learn and implement product changes? Let us know on Twitter!

❗️ Are you a software engineer?

At Monolist, we’re focused on building the global command center for software engineers. If you want to try it for free, just click here.

TypeScript 3.7 Features in Production: Optional Chaining, Nullish Coalescing, and Assertion Functions

Jake Marsh — Mon, 07 Oct 2019 17:39:50 +0000

At Monolist, we're building the command center for engineers. We integrate with all of the tools engineers use (code hosting, project management, alerting),
and aggregate all of their tasks in one place. If you've read our previous posts, you know we're big fans of TypeScript and highly recommend it.

Microsoft has just announced the TypeScript 3.7 Beta, and it included multiple features we were excited to start using ASAP here at Monolist. We're going to be diving into some of these features and how we're already using them in production.

Optional Chaining

Optional chaining is a new feature that allows you to chain property accesses without worrying about null or undefined. If it encounters one of these values, it will stop executing the expression. This means you no longer have to chain && when accessing a nullable property.

If you're familiar with Ruby (which we use for our API), this is similar to the safe navigation operator.

In Practice

There are a few patterns that emerge when writing a React app. Optional props mean you're often doing null checks and && chaining to ensure a prop exists before accessing it.

For some of our reusable components, we have optional render props to render any context-specific supplementary content. This ends up looking something like this:

<div>
  {props.renderSupplementaryContent && props.renderSupplementaryContent()}
</div>

With optional chaining, this becomes:

<div>
  {props.renderSupplementaryContent?.()}
</div>

Not bad! A similar pattern can occur when trying to access properties of an optional prop. Here's a snippet of our code for rendering pull request approvals, in which props.update may not exist:

function getOverlay(): React.ReactNode {
  return (props.update && props.update.text) || `Approved by ${props.approvedBy.join(', ')}`;
}

With optional chaining, this becomes:

function getOverlay(): React.ReactNode {
  return props.update?.text || `Approved by ${props.approvedBy.join(', ')}`;
}

These are just a few examples in a React app that this new feature will be helpful. Although simple, it removes a lot of boilerplate and helps readability, so it's easy to see why this was one of their most requested features.

Nullish Coalescing

Although the name sounds a little intimidating, this feature is simple: the new ?? operator provides a way to fall back to a default value in a more reliable manner than ||.

Since || triggers implicit type coercion, any falsy value at the beginning will be passed over for the following value. With the new ?? operator, it will only fall back to the subsequent value if the first value is truly null or undefined.

In Practice

We recently added full diff browsing and commenting support to Monolist.

One obvious requirement of this feature is the ability to map comment threads back to their original line in the git diffs. When doing this, we're often doing comparisons on the relevant line numbers. Here's an example utility function we use:

function getLineNumberForChange(change: IChange): number {
  return change.newLineNumber || change.oldLineNumber;
}

This means that whenever we pass in a change (a single line of a git diff), we return either its newest line number, or if that doesn't exist then fall back to its old line number. For now this works because our line number indices start at 1. However, if newLineNumber were ever 0, we'd pass right over it and erroneously return oldLineNumber. We can now fix this easily with nullish coalescing:

function getLineNumberForChange(change: IChange): number {
  return change.newLineNumber ?? change.oldLineNumber;
}

This will only return newLineNumber if it's not explicitly null or undefined! No more skipping over 0.

Assertion Functions

The last "headline" feature in TypeScript 3.7 that we'll go over is assertion functions. These ensure that whatever condition is being checked must be true for the remainder of the containing scope. These assertion functions can take two forms.

The first, asserts condition, says that whatever gets passed as the condition must be true if the assert returns. Otherwise, an error is thrown. This is similar to Node's assert module.

The second, asserts val is <type>, doesn't check for a condition but rather that a specific variable or property has a different type. These are Similar to type predicates.

In Practice

Since Monolist integrates with many different applications and displays them all in one similar format, we have many different item types that contribute to one union type: ActionItem. This means there are many places where we have to check the type of the item before we proceed with integration-specific logic.

Here's an example:

function getActionsForGithubPullRequestActionItem(actionItem: ActionItem): Action[] {
  const possibleActions: Action[] = [];

  if (actionItem.actionItemType !== 'githubPullRequest') {
    return [];
  }

  const _actionItem = actionItem as GithubPullRequestActionItem;

  if (_actionItem.state === 'open') {
    if (_actionItem.githubPullRequest.canBeApproved) {
      possibleActions.push('approve');
    }

    possibleActions.push('merge');
  }

  return possibleActions;
}

Here, we're getting the available actions that a user can take on their GitHub pull request items. However, we first have to ensure that the item is the type we expect: a githubPullRequest. This requires first checking the type of the item, and then re-aliasing it as the proper type so that our later property accesses don't throw (like actionItem.githubPullRequest.canBeApproved).

Using the second assertion function signature, we can create an assertion function to be re-used in places like this moving forward:

function assertIsGithubPullRequestItem(val: ActionItem): asserts val is GithubPullRequestActionItem {
  if actionItem.actionItemType !== 'githubPullRequest') {
    throw new AssertionError('Not a GitHub pull request item!');
  }
}

function getActionsForGithubPullRequestActionItem(actionItem: ActionItem): Action[] {
  assertIsGithubPullRequestItem(actionItem);

  const possibleActions: Action[] = [];

  if (actionItem.state === 'open') {
    if (actionItem.githubPullRequest.canBeApproved) {
      possibleActions.push('approve');
    }

    possibleActions.push('merge');
  }

  return possibleActions;
}

Now, assuming our newly added assertion function doesn't throw, the rest of getActionsForGithubPullRequestActionItem will know that actionItem is a GithubPullRequestActionItem. Again, this is similar to what can be achieved with type predicates.

Wrapping Up

These are just a few of the new features being added to TypeScript regularly. Read their full announcement here, and subscribe to our mailing list to keep up to date on any of our future posts.

❗️ Are you a software engineer?

At Monolist, we're building software to help engineers be their most productive. If you want to try it for free, just click here.

Building a Subscription Billing System From Scratch with Rails and Stripe

Jake Marsh — Wed, 02 Oct 2019 17:02:55 +0000

As an early-stage startup building a paid product, there’s an entire feature-set you’ll inevitably have to build out: a billing system. Although this can (and should) be extremely basic in your first iteration, some time and thought should still be taken to ensure it’s done correctly and you’re set up for success moving forward. The last thing you want to be debugging or struggling to scale is your ability to take people’s money.

Luckily, there are a huge number of APIs and tools that make building out a simple billing system fairly straightforward. Our personal favorite is Stripe.
Not only do they offer billing APIs and dashboards for likely everything you could need, but their documentation and developer ecosystem is also known for being extremely good. This is all not to mention their suite of services to help early startups like Atlas, or their developer tools like Sorbet.

Monolist is the command center for engineers — tasks, pull requests, messages, docs — all in one place. Learn more or try it for free.

We’re going to be diving in and building a simple billing system from scratch. Since we use Rails here at
Monolist and it’s fairly easy to get started with, that’s what we’ll be working with. Per our reasons above, we’ll be using Stripe Billing.
There will also be a focus on resiliency to ensure we’re handling all possible cases that Stripe may throw at us.

Getting Started

If you don’t have a Rails app to work with, you can read their Getting Started guide here.

Since we’re using Rails, as always there’s a gem to help us out here. Stripe maintains stripe-ruby, a great library
that should support all of the functionality that we’ll need. Let’s get it installed:

Add stripe-ruby to your gemfile: gem "stripe"
bundle install

Next, we made to make sure we’re actually including and initializing Stripe in our application.
To do so, let’s add a new file at config/initializers/stripe.rb. Rails will execute this initializer after all frameworks and plugins are loaded.

require "stripe"

Stripe.api_key = ENV["STRIPE_PRIVATE_API_KEY"]

Pretty simple, right? To generate the STRIPE_PRIVATE_API_KEY, follow their documentation here. It’s generally good to store
these kinds of keys in an environment variable, but it could also be hardcoded here for expediency. Just make sure not to check it into source control!

Creating our models

At the lowest level, the core Stripe resources we’ll be working with are a Product and Customers. In this walkthrough, we’ll be assuming we have just one product representing our subscription application.

First, let’s write the migration and create the corresponding models. In all of the migrations below, the purpose of the column is provided in the comments.

class AddBillingEntities < ActiveRecord::Migration[5.2]
  def change
    create_table :billing_products do |t|
      t.string :stripeid, null: false            # To map to the Product in Stripe
      t.string :stripe_product_name, null: false # The name of the product in Stripe

      t.timestamps
    end

    create_table :billing_customers do |t|
      t.references :user

      t.string :stripeid, null: false # To map to the Customer in Stripe
      t.string :default_source        # Stripe identifier for the user's default payment source (initially null)

      t.timestamps
    end
end

class BillingProduct < ApplicationRecord
  has_many :billing_plans # Ignore this for now, we'll be adding this later
end

class BillingCustomer < ApplicationRecord
  belongs_to :user, { required: false }
  has_many :billing_subscriptions # Ignore this for now, we'll be adding this later
end

To associate our product with a price and recurrence period, we’ll next create an entity to correspond to our Plan.
We should also then ensure we’ve added the has_many association to BillingProduct that we commented on in the snippet above.

class AddBillingPlans < ActiveRecord::Migration[5.2]
  def change
    create_table :billing_plans do |t|
      t.belongs_to :billing_product, null: false              # The BillingProduct that the BillingPlan belongs to

      t.string :stripeid, null: false                         # To map to the Plan in Stripe
      t.string :stripe_plan_name                              # The name of the plan in Stripe
      t.decimal :amount, precision: 10, scale: 2, null: false # Price of the plan, in the corresponding currency's smallest unit (i.e., cents)

      t.timestamps
    end
end

class BillingPlan < ApplicationRecord
  belongs_to :billing_product
  has_many :billing_subscriptions # Ignore this for now, we'll be adding this later
end

Lastly, we need a way to track our Subscriptions. These map a specific customer to a product via a plan.
This is also when we should ensure we’ve added the has_many associations to BillingCustomer and BillingPlan that were commented on above.

class AddBillingSubscriptions < ActiveRecord::Migration[5.2]
  def change
    create_table :billing_subscriptions do |t|
      t.belongs_to :billing_plan, null: false     # The BillingPlan that the BillingSubscription belongs to
      t.belongs_to :billing_customer, null: false # The BillingCustomer that the BillingSubscription belongs to

      t.string :stripeid, null: false             # To map to the Subscription in Stripe
      t.string :status, null: false               # The status of the Stripe subscription (trialing, active, etc.)

      t.datetime :current_period_end              # When the current subscription period will lapse
      t.datetime :cancel_at                       # If set to cancel, when the cancellation will occur

      t.timestamps
    end
end

class BillingSubscription < ApplicationRecord
  belongs_to :billing_plan
  belongs_to :billing_customer
end

Hooking up our core models

Now let’s write some services that will help us synchronize our entities with their counterparts on Stripe.

Generally, you won’t be creating or modifying Products or Plans very often. However, we still need to be able to synchronize them quickly and easily with Stripe to ensure we’re never out of sync and causing billing issues for our users. This includes accounting for the various updates that could happen: a Product or Plan can be created, updated, or deleted.

Let’s write a couple of classes to do just that. We’ve commented out the blocks of code for clarity.

class SynchronizeBillingProducts
  def call
    # First, we gather our existing products
    existing_products_by_stripeid = BillingProduct.all.each_with_object({}) do |product, acc|
      acc[product.stripeid] = product
    end

    # We're also going to keep track of the products we confirm exist on Stripe's end
    confirmed_existing_stripeids = []

    # Fetch all of our active products from Stripe
    Stripe::Product.list({ active: true })["data"].each do |product|
      # If we are already aware of the product. let's just update the non-static fields on our end
      if existing_products_by_stripeid[product["id"]].present?
        existing_products_by_stripeid[product["id"]].update!({ stripe_product_name: product["name"] })
      # If we're not already aware of the product, let's create it on our end
      else
        BillingProduct.create!({
          stripeid: product["id"],
          stripe_product_name: product["name"],
        })
      end

      confirmed_existing_stripeids << product["id"]
    end

    # Lastly, delete any products on our end that no longer exist (or are not active) on Stripe
    BillingProduct.where.not({ stripeid: confirmed_existing_stripeids }).destroy_all

    nil
  end
end

class SynchronizeBillingPlans
  def call
    # First, we gather our existing plans
    existing_plans_by_stripeid = BillingPlan.all.each_with_object({}) do |plan, acc|
      acc[plan.stripeid] = plan
    end

    # We're also going to keep track of the plans we confirm exist on Stripe's end
    confirmed_existing_stripeids = []

    # Fetch all of our active plans from Stripe
    Stripe::Plan.list({ active: true })["data"]
      .each do |plan|
        # If we are already aware of the plan, let's just update the non-static fields on our end
        if existing_plans_by_stripeid[plan["id"]].present?
          existing_plans_by_stripeid[plan["id"]].update!({
            stripe_plan_name: plan["nickname"],
            amount: plan["amount"],
          })
        # If we're not already aware of the plan, let's create it on our end
        else
          BillingPlan.create!({
            billing_product: BillingProduct.find_by({ stripeid: plan["product"] }),
            stripeid: plan["id"],
            stripe_plan_name: plan["nickname"],
            amount: plan["amount"],
          })
        end

        confirmed_existing_stripeids << plan["id"]
      end

    # Lastly, delete any plans on our end that no longer exist (or are not active) on Stripe
    BillingPlan.where.not({ stripeid: confirmed_existing_stripeids }).destroy_all

    nil
  end
end

These services can be invoked manually when you know you’ve made changes from the Stripe dashboard. We’ll also discuss hooking them up to webhooks below.

🛠 Before moving on, create a Product and Plan in Stripe and call your new services. They should now be in your database as BillingProducts and BillingPlans!

Subscribing a user

Now that we’re able to synchronize our core billing entities, we can get started actually subscribing a user to our product via one of the plans.

First, we need to be able to create a Customer for one of our users. To create a paid customer, this requires a Stripe token,
most often generated client-side using one of their fantastic JavaScript libraries.
A Customer can be created without a token, but will not be eligible for any paid products (only free or free trials).

We’re going to assume here that you have a User class with both email and name fields.

class CreateStripeBillingCustomer
  def call(user:, stripe_token: nil)
    # First, we fetch all users with the same email
    existing_customers_with_email = Stripe::Customer.list({ email: user.email })["data"]

    # If we've found any matching customers for the user, grab it
    if existing_customers_with_email.size.positive?
      stripe_customer = existing_customers_with_email.first
    # Otherwise, let's create a new customer for the user
    else
      stripe_customer = Stripe::Customer.create({
        name: user.name,
        email: user.email,
        source: stripe_token,
      })
    end

    # Lastly, let's make sure we persist the customer on our end
    BillingCustomer.create!({
      user: user,
      stripeid: stripe_customer.id,
      default_source: stripe_customer.default_source,
    })
  end
end

Now that we’re able to create a Customer and associate it with one of our users, we’re ready to subscribe them to a plan.

🛠 Before moving on, try to subscribe a test user to one of your products (invoke a service manually if necessary). The subscription should now appear in your Stripe dashboard, and your user should have a BillingCustomer with a BillingSubscription!

Staying in sync using webhooks

The last thing we’re going to cover is handling webhooks from Stripe when anything occurs or changes
related to any part of our billing system. This ensures we’ll always stay in sync and avoid any unknown billing bugs or issues.

First, you’ll need to activate webhooks and specify an endpoint in your Stripe dashboard. When doing so, you’ll
be required to specify the types of events you want to be notified about. For the purposes of this walkthrough, these are:

plan.updated
plan.deleted
plan.created
product.updated
product.deleted
product.created
customer.updated
customer.deleted
customer.subscription.updated
customer.subscription.deleted
customer.subscription.created

Next, we’ll need to add a new route handler at the endpoint you provided to Stripe.
Here we need to both verify the signature of the webhook request as well as handle the event itself.

class StripeWebhooksController
  def receive
    # Get the event payload and signature
    payload = request.body.read
    sig_header = request.headers["Stripe-Signature"]

    # Attempt to verify the signature. If successful, we'll handle the event
    begin
      Stripe::Webhook::Signature.verify_header(payload, sig_header, ENV["STRIPE_WEBHOOK_SIGNING_KEY"])
      HandleStripeEvent.new.call(payload)
    # If we fail to verify the signature, then something was wrong with the request
    rescue Stripe::SignatureVerificationError
      head 400
      return
    end

    # We've successfully processed the event without blowing up
    head 200
  end
end

You’ll notice there’s a new environment variable here: STRIPE_WEBHOOK_SIGNING_KEY. This should be available in your Stripe dashboard for the webhooks endpoint you just created.

Lastly, we need to make sure we’re handling each of the individual events we’ve subscribed to. We’re not going to go into detail here on each of the handlers we’ve implemented, as you should now have the basis to move forward and write those yourselves.

The few exceptions are those related to Products and Plans: since we expect these to be updated so rarely, we can just re-invoke our overall synchronizer services that we wrote earlier!

class HandleStripeEvent
  def call(event:)
    case event["type"]
    when "product.created", "product.updated", "product.deleted"
      SynchronizeBillingProducts.new.call
    when "plan.created", "plan.updated", "plan.deleted"
      SynchronizeBillingPlans.new.call
    when "customer.updated"
      HandleStripeCustomerUpdatedEvent.new.call({ event: event })
    when "customer.deleted"
      HandleStripeCustomerDeletedEvent.new.call({ event: event })
    when "customer.subscription.updated"
      HandleStripeSubscriptionUpdatedEvent.new.call({ event: event })
    when "customer.subscription.deleted"
      HandleStripeSubscriptionDeletedEvent.new.call({ event: event })
    when "customer.subscription.created"
      HandleStripeSubscriptionCreatedEvent.new.call({ event: event })
    else
      raise("Unexpected event from Stripe: #{event['type']}")
    end
  end
end

🛠 Now that we’re handling these various events from Stripe, you should now be able to update any of your entities (Product, Plan, Customer, Subscription) in the Stripe dashboard and see the changes reflected on your end.

Wrapping up

This walkthrough should get you set up with a simple subscription billing system so that you can start charging for your product.

In a later blog post, we’ll talk about doing something a little more complex: incentivizing in-app actions (such as referrals) with coupons on the user’s billing plan.

❗️ Are you a software engineer?

At Monolist, we're building software to help engineers be their most productive.
If you want to try it for free, just click here.

Optimizing for Iteration: Best Practices for Automating Everything

Jake Marsh — Thu, 26 Sep 2019 16:37:14 +0000

As we’ve discussed in a previous blog post, product development is hypothesis testing. This is especially true in the early stages of a company when you need to confirm or reject your hypothesis as quickly as possible.
This process is then repeated until you (hopefully) reach product-market fit. To get there, your team needs to be able to work and build at a pace that allows for this constant and rapid iteration.

Monolist is the command center for engineers — tasks, pull requests, messages, docs — all in one place. Learn more or try it for free.

📝 Document what needs to be documented

Documentation is one possibly un-obvious form of automation. For everything that’s well-documented, a later employee doesn’t need to waste time figuring it out on their own. However, creating and maintaining documentation requires a fair amount of time from members of the team.

A happy medium we’ve found here at Monolist is to only focus on documentation for anything that falls into the category of “one-time process” documentation.

One-Time Process Documentation

When a new engineer joins the team there’s likely to be a large number of tools, services, and permissions to configure manually before they can truly get to work. This can be a long and painful process, especially for the new employee excited to start building.
To avoid this, as much of the process should be documented as possible. This ensures future engineers have a guidebook to reference and don’t have to waste time finding solutions for themselves.

Similar to the onboarding process, there are likely other processes that occur rarely enough that full automation is not worth the effort. One example is deploying an internal service that rarely changes. For cases like these,
it’s good to maintain documentation so that anyone on the team is able to execute the process in the future.

⚙ Automate all of your tests

Testing should be a priority from day one, and your test suite should be run often (ideally on every commit). With those two requirements in mind, it doesn’t make sense to have to run any part of your test suite manually.
If it’s hard to do and you have to do it often, someone will inevitably end up skipping the testing step.

To ensure it’s easy and fast to both write and maintain your automated tests, here are a couple of things to keep in mind.

Balancing unit tests versus integration tests

One of the everlasting struggles in software testing is maintaining a balance between unit testing and integration testing.
Although they both aim to cover and test the various code paths in your application, their opposite approaches result in different tradeoffs.

Unit tests serve to cover the more granular functionality of your modules. This means they’re great at testing the smaller details and relatively easy to maintain, but they’re prone to missing gaps between your various modules.

Integration tests, on the other hand, test your code paths from top to bottom with no (or less) mocking. This means every invoked module is actually run. These tests are more fragile and harder to write or maintain,
but they offer more reassurance that your app is functioning as expected.

Due to the relative ease of unit testing, you should aim to unit test most of your codebase. Any new or modified code should generally have an associated automated test or test update. When it comes to integration testing,
this should be used more sparingly to confirm the expected behavior of more critical code paths. Your onboarding flow, for example, is a crucial part of the new user experience and so is likely worth integration testing.

Writing implementation-independent tests

Lastly, another key point to remember when writing your automated tests is to ensure they’re as implementation-independent as possible. This means that whenever possible,
a module should be tested by asserting strictly on its input and outputs rather than by asserting on the internal behaviors or calls of that module.

The reason for this is that as your team is moving quickly and iterating often, you’re going to be refactoring large swaths of your codebase fairly frequently. The less your code has to change,
in this case your tests, the quicker you’ll be able to make these changes.

🙌 Our Recommendations

react-testing-library: Although this specific library is for React, the same testing-library org has created similar libraries for many other frameworks. These aim to eliminate implementation-specific tests by forcing you to interact with your modules the same way a user would.
Cypress: Another Javascript library, but for end-to-end (integration) testing your application as a whole. This is the most painless experience I’ve ever had writing resilient integration tests.

💨 Streamline code review

Code review should be a central part of your development process. Peer reviews ensure the team is aligned on and aware of any changes, while also providing the opportunity to catch any bugs or issues.
The importance of code review means it’s a very frequent occurrence for the average engineer. When they’re reviewing pull requests so often, it’s best to optimize and automate that process as much as possible.

Automate discovery of pull requests and their updates

The current way most engineers become aware of a new pull request to review is through email or Slack. Although these methods are instant, they’re easy to miss and are immediately out-of-date.
This results in engineers unaware of pull requests they’re blocking, and their teammates blocked from further progress.

As much as possible, your team should optimize the process of discovering pull requests or updates/comments to those pull requests. This will prevent engineers from blocking each other and ensure everyone is working with the same context.
It may take iteration to discover what works best for your team, as every approach will have its drawbacks.

Eliminate discussion about non-crucial details

When it comes to reviewing the code of your teammates, it’s often easy to fall into the trap of commenting on the obvious things: style and formatting. These comments cause unrelated discussion that not only do not
require actual comprehension of the PR, but also waste the time of the engineers involved.

Whenever possible, these decisions and discussions should be automated away. One common practice is through the use of linters: automated processes to compare your codebase and any
updates against a set of rules you define. A newer approach that takes it a step further is auto-formatting all code in a pre-commit hook, completely eliminating any further thought or discussion about things such as formatting.

🙌 Our Recommendations

Monolist: Designed to be an engineer’s command center, Monolist synchronizes in real time to help them discover their pull requests, messages, and tasks.
Prettier: As someone who’s rather opinionated about their code styles, I was reluctant to try Prettier. We’ve now fully adopted it and I’ll never go back to manual formatting or style debates in pull requests.

🚢 Ship easily and often

As mentioned earlier, your goal as an early-stage startup should be to iterate and ship as often and as quickly as possible to maximize learning. This means that you should be able to deploy a new version across all platforms (API, web, mobile) multiple times a day.
The only way to achieve this, without dedicating a large amount of manual time and effort, is through complete automation of your deployment process.

CI/CD

Continuous integration/continuous delivery allows us to achieve this full automation of the deployment process. By automating the entire process from commit, to testing, to building, to deploying,
you’re eliminating the need to ever do it manually and enabling your team to merge and deploy often.

🙌 Our Recommendations

GitLab: GitLab’s all-in-one approach to code management and simple CI pipelines makes it extremely easy to get started with CI and integrate it gradually across your existing process or codebase.

🔥 Catch fires automatically

Naturally, the last thing we’ll talk about automating is ensuring we catch, handle, and triage any errors or abnormalities once the app is out in the wild. With a small, fast team it’s inevitable that you’ll ship a bug here or there.
What’s important is quickly recognizing and addressing the issue so your users are not experiencing sustained difficulty.

Monitoring

The first half of continued app reliability is accurate and reliable monitoring. In the early stages, monitoring should be done for things like server health (CPU usage, RAM usage) and general app health (can the app be loaded by a user? Are async jobs processing?). Any exceptions triggered in the app (API or client) should also be tracked.

Although it can be valuable to have metrics around actual user statistics (posts liked, comments created), these should not be relied upon for any alerting as they’re likely to be volatile in the early stages.

Alerting

When you have sufficient monitoring in place, thresholds can be defined for the various metrics you’re tracking. When these thresholds are violated, the team (or a responsible engineer) should be automatically notified to ensure that the issue is investigated and addressed if necessary.

🙌 Our Recommendations

Sentry: Sentry provides automatic exception reporting for a large variety of languages and frameworks. We use it for both Rails and React to capture and centralize our exceptions for triaging.
Prometheus: A powerful, customizable open-source tool for monitoring your services. Can be configured to handle alerts in many days, i.e. sending to PagerDuty.

❗️ Are you a software engineer?

At Monolist, we're following these tips to rapidly ship new features that help software engineers
be their most productive. If you want to try it for free, just click here.

Running Effective Bug Bashes That Your Team Won’t Dread

Jake Marsh — Mon, 23 Sep 2019 16:44:08 +0000

“Bug bash” is a term thrown around often in software engineering and product development. In general, it means all stakeholders in a project placing all of their focus into finding (and resolving) any outstanding bugs in a feature or product.

Some companies or teams conduct bug bashes in a reactionary manner, meaning they pause everything when they’ve accumulated too many bugs in the product. At that point, they tell everyone involved to go out and “bash” as many bugs as they can. Here at Monolist, we like to conduct them proactively: sitting down and working through everything together, in an organized manner, right before we release something new to our users.

We already have (QA|automated testing). Do we really need to do bug bashes too?

If your company has dedicated QA engineers whose job it is to manually test each and every new feature from top to bottom, then you’ve got it made (and if you’re one of them, I’m sorry). This does probably mean a bug bash, as we define it at Monolist, is unnecessary for your team. But they can never hurt!

Automated test coverage, on the other hand, is the direction that more and more software companies are moving. This often means a combination of unit testing and integration testing (among various other approaches). Although we are firm believers in automating everything here at Monolist, we still aim to bug bash every new feature we ship as a team to do the following:

1. Catch unknown edge cases.

No matter how comprehensive your test suite is, it’s still likely to have some gaps. With unit tests, as is hinted at by its name, you’re testing individual units and missing any of the logic in between. Integration testing aims to solve this, but still requires you to define and properly test every possible user path. Although you should always strive for that goal, it may not always be realistic.

2. Get all stakeholders in front of the final product.

We all dream of the perfect product process in which the feature is well defined from the beginning, no requirements change, and everything is delivered as expected. In an ideal world, all product questions should be raised and addressed before you reach the bug bash. Unfortunately, that’s rarely reality.

A final bug bash with all stakeholders involved (product, design, engineering, etc.) ensures that everyone is getting to see the product in its (near) final state. This should help to ensure that any discrepancies or miscommunications that have slipped through the preceding product process can be ironed out before public release.

How to maximize stress and minimize efficacy

The very nature of a bug bash lends itself to stress and anxiety. After all, you’re sitting down with your whole team, poring over the product with a fine-toothed comb, finding and resolving any number of new bugs in a rushed environment. I don’t have the stats, but I assume that the number of engineers excited about that prospect would be fairly low.

Due to the stress-inducing nature, there are a number of things that you should avoid when conducting a bug bash.

Coming unprepared or without a test plan.

Throwing a group of people into a room with the single instruction of “break it” is a pretty ineffective strategy from the get-go. Without coordination between parties, you’re likely to end up with:

Multiple reports of the same bug, wasting the time and energy of both reporter and reportee.
Missed bugs, because without a plan, there’s no chance your team will get through all of the test-cases.
A stressed and confused team trying to play whack-a-mole with the bugs they’re hearing.

Lacking organization around the bug discovery/reporting process.
When you do have multiple people all looking to find and report issues with a product, this can quickly devolve into any number of them vying for the attention of the relevant stakeholder, or calling out their issues, or asking the people around them if they’re seeing the same thing. This all distracts from the actual bug bash, and makes it more likely that the team will miss real issues.

Allowing non-stakeholders to participate (or even be in the room).

Other parties who are not involved in the building and shipping of the feature should not be in the room for the bug bash (sorry). Without the context involved with the project, they’re likely to interject thoughts or opinions that have no place in a bug bash, and that are likely to cause stress, confusion, or misdirection late in the process.

Trying to discuss or address feedback unrelated to bugs, such as on the design or user experience.

When issues arise in the bug bash unrelated to actual bugs, i.e. design tweaks or UX concerns, it’s easy to get distracted and dive into a conversation about that specific issue. Although it should be tracked and addressed, a bug bash is not the best forum.

How to do it right

Now that we’ve discussed the various things you should not do when organizing and running a bug bash, here are some of the things we’ve codified at Monolist to ensure all bug bashes run smoothly, are frustration-free, and address as many outstanding issues as possible.

Come prepared with a formal list of user stories and/or specific paths that need to be tested.

These should be as granular as possible, as if to serve as a step-by-step guide for the tester(s). If you’ve already written a thorough product spec outlining the various user stories, this can probably double as your testing plan. If you haven’t already written a product spec (tsk tsk), writing the test plan might help.

Below is a screenshot of our actual test plan for our recent Asana integration revamp. As you can see, it is quite simple. All it does is lay out clearly which specific scenarios need to be tested, and what the expected outcome is. You can even tell we had a bug bash follow-up from the story outlined in red.

Assign roles.

As discussed earlier, it’s not ideal to throw everyone into a room and have them start bashing away. There should be a set of pre-assigned roles for the stakeholders, dividing responsibilities to ensure a smooth process. At Monolist, we use the roles below:

“Actor” - One person responsible for acting out all of the outlined user stories within your application.
“Conductor” - One person responsible for walking the actor (and larger group) through the test plan in the necessary order.
“Recorder” - One person responsible for recording and assigning any and all bugs that do occur.

If you have any remaining stakeholders involved in the bug bash, they should be paying close attention for any possible product issues, visual bugs, or anything else that should be noted.

Create a task for any issue that you encounter. Assign it immediately.

As the actor proceeds through the test plan, the recorder should be paying close attention for any bugs that occur or issues that are raised. These should immediately be tracked and assigned in whatever task management system your team uses. This is to ensure that nothing is forgotten about later.

If necessary, pause and immediately schedule the follow-up bug bash.

There’s always that occasional bug bash where the first bug that occurs is quite early in the experience, preventing the bug bash from continuing. If the cause is not immediately obvious or the bug cannot quickly be resolved, the bug bash should be paused. You don’t want to make everyone wait or put the audience pressure on the responsible engineer. Before pausing, though, be sure to schedule the follow-up at a time when all parties will again be present.

Always start from the top.

When your team is ready for a follow-up bug bash, always be sure to start from the very beginning of the test plan regardless of how far you made it last time. Any tweaks or bug fixes could have affected previously tested paths, and so everything should be covered.

In Conclusion...

As your team continues to conduct bug bashes, always pay attention to how effective they are and how the team feels about them. The process can and should be tweaked along the way.

Although bug bashes are a manual effort and should never fully replace your other testing approaches, they’re a worthwhile method of testing your new feature end-to-end just as a user would. The key is to have a system and stick to it, ensuring your bug bashes are efficient and valuable for everyone involved.

Monolist is a global inbox for engineers. Try it out now!

Optimizing for Iteration: Choosing Your Early Startup's Tech Stack

Jake Marsh — Thu, 19 Sep 2019 19:21:10 +0000

Product development is hypothesis testing. This is especially true in the early stages of a company when you need to confirm or reject your hypothesis as quickly as possible.
This process is then repeated until you (hopefully) reach product-market fit. To get there, your team needs to be able to work and build at a pace that allows for this constant and rapid iteration.

Your company’s tech stack will immediately be a fundamental part of how your engineering team works and operates. This is even more important in a small company where the engineering team represents
an outsize portion of the team as a whole.

Many people will recommend to early founders that they use the technologies they know and write in whatever language they're familiar with. Although this is good advice, like all other decisions it should be weighed carefully.
While ideally you're fully familiar with the stack you choose in order to move as fast as you can, you should also be putting some thought into how these choices will affect you and your engineering team moving forward. For example, it may not always be best to pick the brand new (and unproven) technology on the block when you need to scale quickly and painlessly.

What to Optimize For

The overall goal can be summarized as this: minimize time spent on non-feature engineering work.

For every hour you or another engineer spend configuring, debugging, or learning a new system,
that's an hour not spent iterating on the product to maximize learnings and value delivered to your users.

Here are the things to aim for when choosing your startup's early tech stack.

🤯 Easy to understand

On a small engineering team, everyone is going to be working everywhere in your codebase. Additionally, if things are going well,
you'll be adding new engineers to the team fairly regularly. For these reasons, your codebase and systems should remain easy to understand and get started with. No one wants to spend multiple days banging their ahead against a spaghetti codebase or tangled dev environment.

There's a few things that can help with maintaining the grokkability:

Well-known languages or frameworks

Technologies often come and go quickly in software development. However, there are those libraries that are nearly ubiqitous. These are the languages and frameworks
that the majority of software engineers would be at least vaguely familiar with. Examples would be Rails or React, both incredibly popular libraries used and supported by a large number of people and companies. This also means they have large and healthy ecosystems surrounding them.

Typed languages

Large refactors of core business logic are common when you're an early-stage company iterating often on your product direction. These are no longer nerve wracking when you always know what data you’re working with and when.

Self (or well) documented code

While the concept of true "self-documenting code" is fairly controversial,
it can still be valuable when not taken to an extreme. Write and architect your code so that its purpose is clear and its execution path is easy to follow.
Leave clarifying comments when blocks of code become overly complex out of necessity. As mentioned above, typed languages also help a lot here.

🙌 Our Recommendations

Rails — The simplicity of Rails' MVC model, coupled with the easy to read and write language Ruby, means it's easy for most engineers to become comfortable working in Rails and shipping production features. Rails also continues to power many well-known, large-scale applications such as Shopify and GitHub.
- Caveat: Although Ruby is not typed by default, there is a new static type checker called Sorbet.
TypeScript — Defining your types and using TypeScript strictly results in code that’s easy to parse and safer to modify.

🔌 Plug and play

You should favor technologies that are easy to get up and running. On a small team without a dedicated devops team,
engineers should not be dedicating time to setup complex and/or custom infrastructure. There are two things you should
be on the lookout for:

A large community/ecosystem

If it even needs to be said, open-source is your friend. High numbers of users (downloads) and contributors are a good signal
of a healthy ecosystem for an open-source library, meaning bugs should be resolved fairly quickly and new features will likely be shipped. A few quick (and imprecise) measures we use to quickly get a read:

The number of stars a repo has on GitHub
The date of the last significant update
The number of outstanding (and/or stale) issues and pull requests.

"Setup-free"

This one is fairly self-explanatory. I provide the quotations because I've yet to find a library that is truly and literally setup-free for anything beyond the most basic use case.
However, it is still good to aim for libraries that will not require a large amount of someone's time to configure.

None of this means, however, that you should always avoid the route that requires a little more work initially if it pays off in the long run. We'll talk more about that below in "Automate everything".

🙌 Our Recommendations

Rails — One of our picks again. The long history and large community around Rails means you can find a gem for practically anything your application could need to support. Many of them are even included in Rails itself.
Next.js — Next brings a Rails-like simplicity to handling an isomorphic React application. Data fetching and page definitions are unified, while you get to continue using any React patterns or components you prefer.

🔄 Aim for reusability

Every time you re-use a block of code, you're saving some fraction of the time originally spent writing and testing it. It also reduces the surface
area for bugs and for engineers to learn about in your codebase. Here are some ways to aim for reusability across your application's codebase.

Share languages or frameworks

Sharing a single language or framework across multiple parts of your system can increase the options for code sharing. JavaScript is often the
top choice in this sense, as it can be used for everything from your database ORM to your native mobile client.

Build modularly

When multiple parts of your system are using the same core language or framework, it becomes increasingly advantageous to build modularly.
While this always helps with separation of concerns and unit testing, it can now open up new ways to share and re-use code across your application.

For example, maintaining and publishing all of your app state across multiple clients becomes much more manageable when you can use
the exact same Redux code across web, iOS, and Android.

There are limits to reusability, however, as complexity often grows exponentially in the same direction. It is important to keep that in mind
as you still aim to achieve the first goal we discussed, "easy to understand".

🙌 Our Recommendations

React — React has become an incredibly popular framework choice to go alongside a universal JavaScript application. Many libraries exist to support code re-use across frameworks and platforms.
React Native — RN is one of those platforms that encourages code re-use with other React applications. Write your native mobile applications (iOS, Android) using your same modules in familiar architectures.
Gatsby — Another React-related library, Gatsby allows for easy creation and publishing of static websites using the same React files and patterns. Great for maintaining a scalable marketing site.
Lerna — Lerna helps to more easily maintain a monorepo of inter-dependent JS packages. Easily bump while keeping versions in sync, as well as publish to NPM.

🛠 Automate everything

As we discussed above, complex systems and configurations should be avoided whenever possible. However, there's one exception: automation.

Likely the place best suited for automation is your CI/CD process.
This should include everything from linting, to testing, to production deployment. Ideally it's happening quite often, but it can also include any
number of steps each of varying complexity.

Automating any task is going to require a varying amount of upfront effort. However, the ongoing time saved is a multiple of
the frequency and duration of these tasks. Additionally, the ongoing bugs and confusion that would arise from doing every process manually
are immeasurable.

🙌 Our Recommendations

Terraform — Terraform helps us to fully manage our cloud infrastructure in source-controlled and peer-reviewed code. This allows for consistency and self-documentation, while giving us much more confidence in our deployed systems.
Docker — Docker allows us to pre-define our various service environments (we have around 12) as reproducible and deployable containers. Again this allows for consistency, self-documentation, and confidence in our systems.

❗️ Are you a software engineer?

At Monolist, we're following these tips to rapidly ship new features that help software engineers be their most productive. If you want to try it for free, just click here.