# cob-cli test command

cob-cli test [-d --dashboard <name>, --localOnly, --servername <servername> --verbose --environment <env_name> --help]

When performing changes to a server (properly initalized with cob-cli init) it is a good practice to test said changes before deploying them. To do that, use the cob-cli test int the root of a CoB server repository. Running this command will deploy a local Webpack server running in the command line, to stop it, press Q or Ctrl + C with the terminal in focus. This server is accessible through https://localhost:8040. You can view your local test in the brower by pressing O in the terminal.

When changing a server there are usually two kinds of possible modifications, which are handled differently: UI and Scripts. Changes to the UI, present in recordm/customUI folder are NOT propagated (copied) to the CoB server, and are served and accessed locally. However, any other changes (such as IntegrationM scripts) are copied to the server for the duration of the test (until the local process is stopped).

Requests

Requests to local server URLs that do not start with /customUI are redirected to the CoB server

When the local process is properly terminated , the files that were copied to the CoB server are reverted back to their original state in that machine. When a file is changed locally throughout the test, it is automatically synced to the server.

Everyone is affected

Because the scripts are copied into the external server, anyone else using it at the time will also experience their effects. As such, even though the modified files in the production server are reverted back at the end of the test, changes made to production data by these scripts will persist. These scripts, even in testing, can alter the reality in production.

As a precaution, cob-cli test will give you a warning and show the user the list of new/modified files which will be copied into the server, and ask for confirmation before doing so:.

Changes that will be done in training.cultofbits.com:
	create integrationm/concurrent/my_concurrent_script.groovy
	modified integrationm/action/my_action_script.groovy
	Continue? [y/N]

# Execution Details

Before starting the testing process cob-cli must make a series of consistency checks, which are explained below. Once validated, changes can be applied to the server for testing.

# Consistency Checks

cob-cli's goal is to ensure that no previous work is replaced/deleted/modified without authorization. When running this command, cob-cli will go over a checklist to ensure that no breaking changes are made and the user is aware of all the changes that will be made (so that there are no accidental modifications). This checklist will be displayed as follows:

Start testing…
Checking test conditions for <server_name>.cultofbits.com
   Check connectivity and permissions
   Check there's no other 'cob-cli test' running locally
   find out branch-for-HEAD
   find out SHA for last-deploy on specified server
   git stash --include-untracked
   git checkout SHA for last-deploy
   Apply last enviroment specifics
   Check last-deploy == serverLive
   Undo last enviroment specifics
   git checkout branch-for-HEAD
   git stash pop

Check connectivy and permissions It starts by verifying if the user has permission to connect to the server itself.
Check there's no other 'cob-cli test' running locally Then it makes sure that no other cob-cli test's are running locally.
find out branch-for-HEAD cob-cli checks in which branch you are currently operating.
find out SHA for last-deploy on specified server Every CoB server contains a file in /opt/others/cob-cli/lastDeploySha. It contains the signature (SHA) of the git commit used for the last deploy. In this step, cob-cli will fetch this SHA.
git stash --include-untracked Every uncommited change in your current directory will be stashed (don't worry, these changes are not lost) - they are temporarily "stored as a backup".
git checkout SHA for last-deploy Your local repository will be checked out to the SHA used in the server's last deploy (fetched in step 4). This means your local files will be changed to match the server's files when it was last deployed.
Apply last enviroment specifics Each CoB server might have multiple (previously configured) environments associated to it, such as 'production' or 'quality'. These environments allow for specific files to be copied only to them. If you want a file important.txt to be only available in the 'production' environment, you'd alter the name to important.ENV__production__.txt. In this step, files with the discriminated environment names that match the environment being tested against, are temporarily renamed to their correct name (in this case, it would become important.txt) and files corresponding to other environments are (temporarily) removed and/or ignored.
Check last-deploy == serverLive When reaching this step, it will check if the server content is the same as to when it was last deployed. It does this by comparing the server's current files to the ones now in the local machine. If this step fails (and warns the users), it means that an unauthorized change was made to the server's content - meaning someone could've altered the server directly or without using cob-cli. To avoid losing previous work, cob-cli aborts at this step if it finds unexpected changes. You can check our Troubleshooting page (opens new window) for more information on this type of failures, possible solutions and ways to avoid/mitigate such issues.
Undo last enviroment specifics After the comparison in the previous step, cob-cli will now re-add the environment prefixes to your local files to match the reality: important.txt -> important.ENV__production__.txt
git checkout branch-for-HEAD Now that cob-cli has confirmed that everything is OK with both yours and the server's contents, it returns to the branch in which the local repository was when the process started.
git stash pop Restores the stashed changes, thus restoring the user's local files (and the changes he made)

# Applying Changes

Once the previous checks have been validated or confirmed, then cob-cli will begin applying the changes in the server for the test.

Running tests. Before actually applying anything, cob-cli will first verify whether there are any tests running in the server. It does this by checking the /opt/cob-cli/test.in.execution, which holds all the files currently modified by other tests. These files are shown to the user, along with their current testing user. Local changes made to the files in question are not applied on the server - as cob-cli will warn - meaning that, for each listed file, only one user can work on it.
Re-apply Enviornment specifics. Applies the same logic as step 7 in the consistency checks, thus changing the names of environment specific files.
Syncs with server. Finally, it synchronizes, through the tool rsync the folders onto the CoB server. It also deploys the local server with a reverse proxy for /customUI paths.

# Ending the tests

When the user is done with the test it is necessary that it is stopped with one of the two ways mentioned previously (Q or Ctrl + C). Closing the terminal while the process is running, for example, is not a correct way of terminating the test. This is because there are procedures done at the end of the execution, which will not run if the program is not properly closed.

Revert server files. if not properly terminated, cob-cli will not have the opportunity to revert the changes made by this test in the CoB server. This means that any change will persist, continuing to affect the data and users until it is manually reverted.
Update tests on server. If cob-cli does not terminate the right way, it will not remove the files that it added to the test.in.execution file on the CoB server. This is misleading, as there are no tests running and other processes will fail or show warning because pf this.
Undo Environment specifics. cob-cli will not correctly revert the names of files with environment-specific discriminators in the user's machine.

# Options

-V, --verbose
		Verbose execution of tasks with individual descriptions of each check
-e, --environment <name>
		Environment to use (default: 'prod')
-d, --dashboard <name>         
		Aditionally specify a VUE dashboard customization to test (further explained below)
-l, --localOnly                
		Test only localFiles (customUI), scripts and files in other folders are no pushed and thus do not impact the CoB server
-s, --servername <servername> 
		Use <servername>.cultofbits.com (i.e. name without the FQDN), thus ignoring the name in env/server. Note: cob-cli still uses the select envrionment's specific files.
-h, --help
		Display help for command

# -d --dashboard <dash_name> option

To test a dashboard customization (most of the times, the dash customization) this argument must be included in the cob-cli test command, which launches an additional server in https://localhost:8041. This server's only purpose is to allow for hot reloading of dashboard components - accesssing the browser is still done through the previous port 8040. Requests to URLs ending with <dash_name> are redirected to the additional server.

This is necessary because dashboards are built with the Vue.js (opens new window) framework (version 2). Vue has a specific syntax and has to be first compiled down into HTML before it can be used. The additional server that is launched compiles this HTML on file changes, allowing for hot reload of dashboards.

← init command deploy command →