xen-orchestra/packages/xo-server-test/.USAGE.md

Tests are ran sequentially to avoid concurrency issues.

Adding a test

Organization

src
├─ user
|   ├─ __snapshots__
|   |     └─ index.spec.js.snap
|   └─ index.spec.js
├─ job
|   └─ index.spec.js
├─ issues
¦   └─ index.spec.js
¦
├─ _xoConnection.js
└─ util.js

The tests can describe:

• XO methods or scenarios:

src/user/index.js

import xo from '../_xoConnection'

describe('user', () => {
  // testing a method
  describe('.set()', () => {
    it('sets an email', async () => {
      // some tests using xo methods and helpers from _xoConnection.js
      const id = await xo.createTempUser(SIMPLE_USER)
      expect(await xo.call('user.set', params)).toBe(true)
      expect(await xo.getUser(id)).toMatchSnapshot({
        id: expect.any(String),
      })
    })
  })

  // testing a scenario
  test('create two users, modify a user email to be the same with the other and fail trying to connect them', () => {
    /* some tests */
  })
})

• issues

src/issues/index.js

describe('issue', () => {
  test('5454', () => {
    /* some tests */
  })
})

Best practices

• The test environment must remain the same before and after each test:

  • each resource created must be deleted
  • existing resources should not be altered

• Make a sentence for the title of the test. It must be clear and consistent.

• If the feature you want to test is not implemented : write it and skip it, using it.skip().

• Take values ​​that cover the maximum of testing possibilities.

• If you make tests which keep track of large object, it is better to use snapshots.

• _xoConnection.js contains helpers to create temporary resources and to interface with XO. You can use it if you need to create resources which will be automatically deleted after the test:

  import xo from '../_xoConnection'
  
  describe('.create()', () => {
    it('creates a user without permission', async () => {
      // The user will be deleted automatically at the end of the test
      const userId = await xo.createTempUser({
        email: 'wayne1@vates.fr',
        password: 'batman1',
      })
      expect(await xo.getUser(userId)).toMatchSnapshot({
        id: expect.any(String),
      })
    })
  })
  

  The available helpers:

  • createTempUser(params)
  • getUser(id)
  • createTempJob(params)
  • createTempBackupNgJob(params)
  • createTempVm(params)
  • getSchedule(predicate)

Usage

• Before running the tests, you have to create a config file for xo-server-test.

  > cp sample.config.toml ~/.config/xo-server-test/config.toml
  

  And complete it.

• To run the tests:

  > npm ci
  > yarn start
  

  You get all the test suites passed (PASS) or failed (FAIL).

  > yarn test
  yarn run v1.9.4
  $ jest
   PASS  src/user/user.spec.js
   PASS  src/job/job.spec.js
   PASS  src/backupNg/backupNg.spec.js
  
  Test Suites: 3 passed, 3 total
  Tests:       2 skipped, 36 passed, 38 total
  Snapshots:   35 passed, 35 total
  Time:        7.257s, estimated 8s
  Ran all test suites.
  Done in 7.92s.
  

• You can run only tests related to changed files, and review the failed output by using: > yarn start --watch

• ⚠ Warning: snapshots ⚠ After each run of the tests, check that snapshots are not inadvertently modified.

• ⚠ Jest known issue ⚠ If a test timeout is triggered the next async tests can fail, it's due to an inadvertently modified snapshots. As a workaround, you can clean your git working tree and re-run jest using a large timeout: > yarn start --testTimeout=100000