k6 is an open-source, javascript-based load testing framework.

With k6 and brainCloud's JavaScriptK6 client library, developers can easily create load tests that mimic an app's behavior by calling brainCloud APIs and custom Cloud Code scripts.

Note - this is not a formal endorsement of k6. We do not have a relationship with them k6, nor are you limited to using k6 for your load tests.

When working to load test your brainCloud apps, we highly recommend the following:

You choose a load testing framework that can utilize one of the available brainCloud client libraries. (Our client protocol is complicated, and not suitable for simple HTTP or REST-based load testing frameworks).
You coordinate your approach and tests with a member of the brainCloud Engineering/Support Team. What is a test to you may look like a Denial-of-Service attack to us!

This tutorial is a simple example of how to create a simple load test for your app using k6. A similar approach can be taken with other tools.

---

Installation

To get started:

Install K6 on your local machine
Request the K6.zip example package from brainCloud support

Once unzipped, you will find the following:

lib/brainCloudK6.js - a K6 compatible version of the brainCloud JavaScript library
simpleExample/simpleTestScript.js - an example test script
simpleExample/config.js - customizable config parameters to run the script

You should be able to configure and run the example script from within the simpleExample directory.

---

App Preparation

To run this example, you will first need to create an example app that meets the following criteria:

Is enabled for the Web platform <- JavaScript apps always show as "web"
Has a leaderboard named "daily"
Has RTT enabled
Has Chat enabled, with a global chat channel named "main"

The instructions for quickly creating such an app are:

Log in to the Design Portal
Go to Team | Manage | Apps, and click [+ New App]
Give the app a Name, choose to Enable Game Features (if asked), and be sure to enable at least the Web platform. Then click [Save].
Go to Design | Core App Info | Advanced Settings, and check Real-time Tech (RTT) Enabled
Go to Design | Leaderboards | Leaderboard Configs, and click the (+) in the top-right corner. Enter "daily" for the LeaderboardId, and change the Rotation Type to Daily as well. Click [Save & Close].
Go to Design | Messaging | Chat, and enable the Chat service. Click [Save].
Go to Design | Messaging | Chat Channels, click [+ New Channel], and create a channel with a Channel Code of "main". The Channel Name and Description can be whatever you want. Click [Save].
Finally, go to Design | Core App Info | Application IDs and note the AppId and Secret for your newly created app. You will need them for the config.js file.

Note - if created on the brainCloud Public BaaS, the app will be limited to 100 Daily Active Users. You will need to upgrade the plan if you want to load test higher usage levels.

---

Test Configuration

Clone (or rename) the simpleExample/config-template.js file - creating a new file called config.js.

Use a text editor to edit the simpleExample/config.js file.

// Configure brainCloud API Server and App information
export const BRAINCLOUD_APIURL     = "https://api.bc.xxxxxxx.com";
export const BRAINCLOUD_APPID      = "<your-app-id>";
export const BRAINCLOUD_APPSECRET  = "<your-app-secret>";
export const BRAINCLOUD_APPVERSION = "1.0.0";

// Configure K6 project information
export const K6_CLOUD_PROJECT_ID = "<your-k6-project-id>";

// Configure which scenario to run. Note can also override
// by setting K6_TEST_SCENARIO env or command line parameter
export const K6_TEST_SCENARIO = "sanity5UserTestScenario";

// User prefix - prefix to use for generated users.
// The script will add a count to the end for each user 
// - so user+1, user+2, etc. 
// If running manually on multiple servers, vary this prefix 
// to avoid server users clashing with each other 
// - set to "load1+user" for 1st server, "load2+user" for 2nd, etc.
export const USERNAME_PREFIX = "user+";

At a minimum, you must replace the following:

BRAINCLOUD_APIURL - set to the API endpoint for your brainCloud instance. If using the brainCloud Public BaaS, use https://sharedprod.braincloudservers.com. For most private instances, you can simply replace the "portal" at the beginning of the Design Portal URL with "api"
BRAINCLOUD_APPID - the appId from your newly created app
BRAINCLOUD_APPSECRET - the secret from your newly created app

Note that the K6_CLOUD_PROJECT_ID is only required if you are running the test via the k6.io cloud service. It is not required for running locally.

Test Script

Examine the simpleExample/simpleTestScript.js script.

You will note the following:

It starts with importing various K6 libs, the brainCloudK6 lib, and the config.js file
It then defines some custom stats to collect, and thresholds to evaluate the test results against
The next section defines various test scenarios - from simple 5 and 50 user sanity tests to larger 100, 500, and 1000 staged scenarios. The specific scenario to run is specified via the K6_TEST_SCENARIO property in config.js
Finally the tests themselves aren't that complicated -- see the excerpt below

// 4 - Retrieve a channel id in prep for next step
var channelId = "";
_bc.chat.getChannelId("gl", "main", result =>
{
  if ( checkForAndRecordErrors("chat.getChannelId()", result) ) {
    channelId = result.data.channelId;
  }
});
sleep(INTERVAL);

// 5 - Connect to a chat channel
_bc.chat.channelConnect( channelId, 10, result =>
{
  checkForAndRecordErrors("chat.channelConnect()", result);
});
sleep(INTERVAL);
			
// 6 - Post a chat message
_bc.chat.postChatMessageSimple(channelId, "Chat message from K6", true, result => 
{
  checkForAndRecordErrors("chat.postChatMessageSimple()", result);
});
sleep(INTERVAL);

Running K6 Locally

To run the test, execute the following from within the simpleExample directory:

> k6 run simpleTestScript.js

You will see console logs and some status as the tests progress:

Once complete, the test results will be displayed.

Note - the k6 utility offers the ability to customize the results format, and integrate with several external systems.

Running via K6.io

K6.io offers a service running distributed scripts via the cloud. You can get a free account good for 50 small tests.

To run a test via the cloud service - you copy the projectId from K6.io into the K6_CLOUD_PROJECT_ID property in the config.js file.

First, you will need to log in via the command-line tool:

> k6 login cloud
email: john@smith.com
password: xxx

Then run the script via the following:

> k6 cloud simpleTestScript.js

You can then view the results via K6.io.

Note that the results available via k6.io (see above) are more impressive than the standard results available via the command-line tool.

Summary

K6 is a useful tool + service for quickly creating and executing simple brainCloud load tests.