Skip to content
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 37 additions & 32 deletions docs/testing/unit-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,62 +107,67 @@ describe('when adding a token', () => {

## Use `it` to specify the desired behavior for the code under test

As each test [should focus on a single aspect of that behavior](#keep-tests-focused), its description should describe that behavior. This description helps to anchor the purpose of the test, understand the intended behavior, and debug differences with the actual behavior that may occur down the road.
As each test [has to focus on a single aspect of that behavior](#keep-tests-focused), its description must describe that behavior using these guidelines:

Do not repeat the name of the function or method in the name of the test.

Do not use "should" at the beginning of the test name. The official Jest documentation [omits this word from their examples](https://jestjs.io/docs/next/getting-started), and it creates noise when reviewing the list of tests printed after a run.
1. Start with an active verb in present tense
2. Focus on what is being tested, not how
3. Be explicit about the context when needed
4. Keep names concise but descriptive
5. Avoid "should", "when", and other unnecessary words
Comment thread
NicolasMassart marked this conversation as resolved.
Outdated
6. Do not state obvious successful outcomes ("works successfully", "correctly")
7. Do not list test parameters; describe what they represent instead

### Examples

🚫
🚫 Don't
Comment thread
NicolasMassart marked this conversation as resolved.
Outdated

```typescript
it('should not stop the block tracker', () => {
it('should successfully add token when address is valid and decimals are set and symbol exists', () => {
// ...
});
```


```typescript
it('does not stop the block tracker', () => {
it('should fail and show error message when invalid address is provided', () => {
// ...
});
```

🚫
it('works correctly when processing the transaction', () => {
// ...
});

```typescript
describe('TokensController', () => {
it('addToken', () => {
Comment thread
NicolasMassart marked this conversation as resolved.
// ...
});
it('should throw error when balance is insufficient and user tries to send tokens', () => {
// ...
});
```

🚫
✅ Do

```typescript
describe('TokensController', () => {
it('adds a token', () => {
// ...
});
it('stores valid token in state', () => {
// ...
});
```

it('displays invalid address error', () => {
// ...
});

```typescript
describe('TokensController', () => {
describe('addToken', () => {
it('adds the given token to "tokens" in state', () => {
// ...
});
});
it('processes transaction', () => {
// ...
});

it('prevents sending with insufficient balance', () => {
// ...
});
```

The test description should communicate the expected behavior clearly and directly. Avoid:

- Repeating the name of the function or method being tested
- Using "should" at the beginning of the test name
- Including implementation details in the name
- Stating obvious successful outcomes
- Listing test parameters instead of what they represent
- Using words like "fail", "error", or "throw" when the error is the expected behavior
Comment thread
NicolasMassart marked this conversation as resolved.
Outdated

### Read more

- ["Tests as Specification"](http://xunitpatterns.com/Goals%20of%20Test%20Automation.html#Tests%20as%20Specification) and ["Tests as Documentation"](http://xunitpatterns.com/Goals%20of%20Test%20Automation.html#Tests%20as%20Documentation) in xUnit Patterns
Expand Down