fleet/docs/4-Contribution/2-Testing.md

Testing & Local Development

• Test suite
• End-to-end tests
• Email
• Database backup/restore
• Teams seed data
• MySQL shell
• Testing SSO

Test suite

To execute the basic unit tests, run the following from the root of the repository:

MYSQL_TEST=1 REDIS_TEST=1 make test

It is a good idea to run make test before submitting a Pull Request.

Go unit tests

To run all Go unit tests, run the following:

make test-go

Go linters

To run all Go linters and static analyzers, run the following:

make lint-go

Javascript unit tests

To run all JS unit tests, run the following:

make test-js

or

yarn test

Javascript linters

To run all JS linters and static analyzers, run the following:

make lint-js

or

yarn lint

MySQL tests

To run MySQL integration tests set environment variables as follows:

MYSQL_TEST=1 make test-go

Redis tests

To run Redis integration tests set environment variables as follows:

REDIS_TEST=1 make test-go

Email tests

To run email related integration tests using MailHog set environment as follows:

MAIL_TEST=1 make test-go

Viewing test coverage

When you run make test or make test-go from the root of the repository, test coverage reports are generated in every subpackage. For example, the server subpackage will have a coverage report generated in ./server/server.cover

To explore a test coverage report on a line-by-line basis in the browser, run the following:

# substitute ./datastore/datastore.cover, etc
go tool cover -html=./server/server.cover

To view test a test coverage report in a terminal, run the following:

# substitute ./datastore/datastore.cover, etc
go tool cover -func=./server/server.cover

End-to-end tests

E2E tests are run using Docker and Cypress.

Preparation

Make sure dependencies are up to date and the Fleet binaries are built locally.

make e2e-reset-db
make e2e-serve

This will start a local Fleet server connected to the E2E database. Leave this server running for the duration of end-to-end testing.

make e2e-setup

This will initialize the E2E instance with a user.

Run tests

Tests can be run in interactive mode, or from the command line.

Interactive

yarn cypress open

Use the graphical UI controls to run and view tests.

Command line

yarn cypress run

Tests will run automatically and results are reported to the shell.

Email

Manually testing email with MailHog

To intercept sent emails while running a Fleet development environment, make sure that you've set the SMTP address to localhost:1025 and leave the username and password blank. Then, visit http://localhost:8025 in a web browser to view the MailHog UI.

When Fleet sends emails, the contents of the messages are available in the MailHog UI.

Database Backup/Restore

In the course of development (particularly when crafting database migrations), it may be useful to backup and restore the MySQL database. This can be achieved with the following commands:

Backup:

./tools/backup_db/backup.sh

The database dump is stored in backup.sql.gz.

Restore:

./tools/backup_db/restore.sh

Note that a "restore" will replace the state of the development database with the state from the backup.

Teams seed data

When developing on both the master and teams branches, it may be useful to create seed data that includes users and teams.

Check out this Loom demo video that walks through creating teams seed data: https://www.loom.com/share/1c41a1540e8f41328a7a6cfc56ad0a01

For a text-based walkthrough, check out the following steps:

First, create a env file with the following contents:

export SERVER_URL=https://localhost:8080 # your fleet server url and port
export CURL_FLAGS='-k -s' # set insecure flag
export TOKEN=eyJhbGciOi... # your login token

Next, set the FLEET_ENV_PATH to point to the env file. This will let the scripts in the fleet/ folder source the env file.

export FLEET_ENV_PATH=/Users/victor/fleet_env

Finally run the teams/create bash script located in the /tools/api directory. This script will create 3 teams and 12 users with various roles.

./tools/api/fleet/teams/create

Each user generated by the script has their password set to user123#.

MySQL shell

Connect to the MySQL shell to view and interact directly with the contents of the development database.

To connect via Docker:

docker-compose exec mysql mysql -uroot -ptoor -Dfleet

Testing SSO

Fleet's docker-compose file includes a SAML identity provider (IdP) for testing SAML-based SSO locally.

Configuration

Configure SSO on the Organization Settings page with the following:

Identity Provider Name: SimpleSAML
Entity ID: https://localhost:8080
Issuer URI: http://localhost:8080/simplesaml/saml2/idp/SSOService.php
Metadata URL: http://localhost:9080/simplesaml/saml2/idp/metadata.php

The identity provider is configured with 2 users:

Username: user1
Email: user1@example.com
Password: user1pass

and

Username: user2
Email: user2@example.com
Password: user2pass

Use the Fleet UI to invite one of these users with the associated email. Be sure the "Enable Single Sign On" box is checked for that user. Now after accepting the invitation, you should be able to log in as that user by clicking "Sign On with SimpleSAML" on the login page.