disruptor

README

xk6-disruptor

"Like Unit Testing, but for Reliability"

xk6-disruptor is an extension adds fault injection capabilities to Grafana k6. It implements the ideas of the Chaos Engineering discipline and enables Grafana k6 users to test their system's reliability under turbulent conditions.

⚠️ Important xk6-disruptor is in the alpha stage, undergoing active development. We do not guarantee API compatibility between releases - your k6 scripts may need to be updated on each release until this extension reaches v1.0 release.

Why xk6-disruptor?

xk6-disruptor is purposely designed and built to provide the best experience for developers trying to make their systems more reliable:

• Everything as code.

  • No need to learn a new DSL.
  • Developers can use their usual development IDE
  • Facilitate test reuse and sharing

• Fast to adopt with no day-two surprises.

  • No need to deploy and maintain a fleet of agents or operators.

• Easy to extend and integrate with other types of tests.

  • No need to try to glue multiple tools together to get the job done.

Also, this project has been built to be a good citizen in the Grafana k6 ecosystem by:

• Working well with other extensions.
• Working well with k6's core concepts and features.

You can check this out in the following example:

export default function () {
    // Create a new pod disruptor with a selector 
    // that matches pods from the "default" namespace with the label "app=my-app"
    const disruptor = new PodDisruptor({
        namespace: "default",
        select: { labels: { app: "my-app" } },
    });

    // Disrupt the targets by injecting HTTP faults into them for 30 seconds
    const fault = {
        averageDelay: 500,
        errorRate: 0.1,
        errorCode: 500
    }
    disruptor.injectHTTPFaults(fault, "30s")
}

Features

The project, at this time, is intended to test systems running in Kubernetes. Other platforms are not supported at this time.

It offers an API for creating disruptors that target one specific type of the component (e.g., Pods) and is capable of injecting different kinds of faults, such as errors in HTTP requests served by that component. Currently, disruptors exist for Pods and Services, but others will be introduced in the future as well as additional types of faults for the existing disruptors.

Use cases

The main use case for xk6-disruptor is to test the resiliency of an application of diverse types of disruptions by reproducing their effects without reproducing their root causes. For example, inject delays in the HTTP requests an application makes to a service without having to stress or interfere with the infrastructure (network, nodes) on which the service runs or affect other workloads in unexpected ways.

In this way, xk6-disruptor make reliability tests repeatable and predictable while limiting their blast radius. These are essential characteristics to incorporate these tests in the test suits of applications deployed on shared infrastructures such as staging environments.

Learn more

Check the get started guide for instructions on how to install and use xk6-disruptor.

The examples section in the documentation presents examples of using xk6-disruptor for injecting faults in different scenarios.

If you encounter any bugs or unexpected behavior, please search the currently open GitHub issues first, and create a new one if it doesn't exist yet.

The Roadmap presents the project's goals for the coming months regarding new functionalities and enhancements.

If you are interested in contributing with the development of this project, check the contributing guide

Documentation

Overview

Package disruptor implement the k6 extension interface for calling disruptors from js scripts running in the goya runtime

Index

• type ModuleInstance
  • func (m *ModuleInstance) Exports() modules.Exports
• type RootModule
  • func (*RootModule) NewModuleInstance(vu modules.VU) modules.Instance

Types

type ModuleInstance

type ModuleInstance struct {
	// contains filtered or unexported fields
}

ModuleInstance represents an instance of the JS module.

func (*ModuleInstance) Exports

func (m *ModuleInstance) Exports() modules.Exports

Exports implements the modules.Instance interface and returns the exports of the JS module.

type RootModule

type RootModule struct{}

RootModule is the global module object type. It is instantiated once per test run and will be used to create `k6/x/disruptor` module instances for each VU.

func (*RootModule) NewModuleInstance

func (*RootModule) NewModuleInstance(vu modules.VU) modules.Instance

NewModuleInstance returns a new instance of the disruptor module for each VU.