github-desktop/docs/technical/adding-tests.md

Adding tests to the project

This document explains a bit about our testing infrastructure, and how you can contribute tests to go with changes to the codebase.

Overview

The tests we have in the repository are found under app/test and are organized into these subdirectories:

• unit - unit tests for small parts of the codebase. This currently makes up the majority of our tests.
  • the subdirectories defined here are intended to match the layout of the app/src/ directory, but this has not been rigorously defined and will be affected by our plans in #5645 to evolve the source layout
• integration - these tests are for end-to-end testing and involve launching and driving the app using UI automation

Other important folders:

• fixtures - this folder contains Git repositories which can be used in tests
• helpers - modules containing logic to help setup, manage and teardown tests
• __mocks__ - this is a special Jest folder that contains mocks for Electron APIs, which are only stubbed out when tests require it

Adding Unit Tests

Unit tests are ideal for functions that don't depend on the DOM or Electron APIs, so if you are working on some code that will benefit from writing tests here is a guide to getting this working.

First , check under app/test/unit for an existing test module related to the area you are working in - we want to ensure each test module corresponds to a specific application module.

Creating a new test module

If no test module exists, create a new file named [app-module]-test.ts where [app-module] is the filename of the application module you are working in.

Start with this for the contents of the file:

describe('module being tested', () => {
  it('can test some code', () => {
    expect(true).toEqual(false)
  })
})

If you run yarn test:unit from a shell you should see this error, which indicates the file is loaded into our Jest runner successfully.

Once you're happy that the test is being run, feel free to write some proper tests to exercise your work.

Adding tests to a test module

Feel free to borrow ideas from our current test suite, but here are some guidelines to help you figure out what to test.

• focus on a specific module or function when writing unit tests - complex unit tests are a sign that the code isn't organized in an ideal way for testing, or that the test is doing too much
• write tests to cover the scenarios you think we should care about in the long-term (these are great to help us not accidentally regress your work)
• keep tests simple and easy to read - code comments shouldn't be necessary
• if you're not confident in writing tests, the Arrange-Act-Assert pattern is a nice way to get started

As you're writing your tests, don't forget to yarn test:unit to verify that your tests are working as expected.

Specific Testing Scenarios

State updates in AppStore

If you find yourself writing complex rules as part of updating application state, consider whether you can extract the logic to a function that lives outside of AppStore.

This has some important benefits:

• by extracting it from AppStore, we can write a pure function that avoids any implicit state and clearly declares what it needs as parameters
• by following a pattern of writing functions that take the current state and generate new state, we keep each function focused on a particular task
• because the function only depends on the arguments it receives, this becomes much easier to test

An example of this is updateChangedFiles in app/src/lib/stores/updates/changes-state.ts which updates the repository state to ensure selection state is remembered correctly.

export function updateChangedFiles(
  state: IChangesState,
  status: IStatusResult,
  clearPartialState: boolean
): ChangedFilesResult {
  ...
}

This uses the current IChangesState, as well as additional parameters and returns an object containing the changes that should be applied to create a new IChangesState for the repository:

/**
 * Internal shape of the return value from this response because the compiler
 * seems to complain about attempts to create an object which satifies the
 * constraints of Pick<T,K>
 */
type ChangedFilesResult = {
  readonly workingDirectory: WorkingDirectoryStatus
  readonly selectedFileIDs: string[]
  readonly diff: IDiff | null
}

And the return value is merged into the current state:

this.repositoryStateCache.updateChangesState(repository, state =>
  updateChangedFiles(state, status, clearPartialState)
)