Tutorial: Get started with k6 (#1192)

Test as code tutorial / getting started with k6

---------

Co-authored-by: Mihail Stoykov <[email protected]>
Co-authored-by: Pepe Cano <[email protected]>
Co-authored-by: Imma Valls <[email protected]>

Author: 4 people

.eslintignore

@@ -6,3 +6,6 @@ docs/sources/get-started/run-your-first-tests.md
 CONTRIBUTING_FILE_FORMAT.md
 src/data/markdown/docs/40 xk6-disruptor/04 Examples/01 Inject Grpc faults into Service.md
 src/data/markdown/docs/40 xk6-disruptor/04 Examples/02 Inject HTTP faults into Pod.md
+src/data/markdown/docs/05 Examples/02 Tutorials/01 Get started with k6/100 Test-for-functional-behavior.md
+src/data/markdown/docs/05 Examples/02 Tutorials/01 Get started with k6/200 Test for performance.md
+src/data/markdown/docs/05 Examples/02 Tutorials/01 Get started with k6/400 Reuse and re-run tests.md

src/data/doc-examples/links.json

@@ -141,55 +141,61 @@
   ],
   "tutorials": [
     {
-      "title": "How to use Datadog alerts and Thresholds to fail your load test",
-      "description": "This article will show how to use Datadog alerts and Thresholds to fail your load test.",
+      "title": "Get started with k6",
+      "description": "This tutorial provides some procedures for common real-life uses of k6.",
+      "to": "/examples/tutorials/get-started-with-k6/",
+      "url": ""
+    },
+    {
+      "title": "8 basic tasks to learn k6",
+      "description": "Challenges are great ways to learn. All the tasks in this blog provide a little context about particular k6 features.",
       "to": "",
-      "url": "https://k6.io/blog/datadog-alerts-fail-load-test"
+      "url": "https://k6.io/blog/learning-js-through-load-testing/"
     },
     {
-      "title": "Load Testing Your API with Postman",
-      "description": "How to use postman collections in k6?",
+      "title": "k6 Learn",
+      "description": "A set of modules to learn about performance testing principles, k6 foundations, and intermediate concepts.", 
       "to": "",
-      "url": "https://k6.io/blog/load-testing-with-postman-collections"
+      "url": "https://github.com/grafana/k6-learn"
     },
     {
-      "title": "Load testing with Swagger/OpenAPI",
+      "title": "Swagger/OpenAPI integration",
       "description": "How to generate a load test script out of an OpenAPI document.",
       "to": "",
       "url": "https://k6.io/blog/load-testing-your-api-with-swagger-openapi-and-k6"
     },
     {
-      "title": "Performance monitoring with cron and k6",
+      "title": "Schedule k6 tests with cron",
       "description": "This tutorial will show you how to schedule k6 tests with cron to monitor the performance of your system.",
       "to": "",
       "url": "https://k6.io/blog/performance-monitoring-with-cron-and-k6"
     },
     {
-      "title": "Load testing GraphQL with k6",
-      "description": "The popularity and adoption of GraphQL have been impressive in the last years, this post provides an example using k6 to load testing a GraphQL service.",
+      "title": "Load test a GraphQL service",
+      "description": "This post provides an example using k6 to load testing a GraphQL service.",
       "to": "",
       "url": "https://k6.io/blog/load-testing-graphql-with-k6"
     },
     {
-      "title": "Load Testing RESTful APIs with k6",
-      "description": "Let's take a look at how we can use the k6 open source load testing tool to performance test REST API endpoints.",
-      "to": "",
-      "url": "https://k6.io/blog/load-testing-restful-apis-with-k6"
-    },
-    {
-      "title": "Using TypeScript in k6 scripts",
+      "title": "Use TypeScript in k6 scripts",
       "description": "This repository provides a scaffolding project to start using Typescript in your k6 scripts.",
       "to": "",
       "url": "https://github.com/k6io/template-typescript"
     },
     {
-      "title": "Debugging Using a Web Proxy",
-      "description": "How to configure k6 to send HTTP traffic through a web proxy. Things to look out for when debugging your performance test.",
+      "title": "Debug using a Web Proxy",
+      "description": "How to configure k6 to send HTTP traffic through a web proxy for debugging k6 tests.",
       "to": "",
       "url": "https://k6.io/blog/k6-load-testing-debugging-using-a-web-proxy/"
     },
     {
-      "title": "Creating a k6 extension",
+      "title": "Distributed k6 tests on K8s",
+      "description": "Deploy the k6 operator in your Kubernetes cluster to run distributed k6 tests.",
+      "to": "",
+      "url": "https://k6.io/blog/running-distributed-tests-on-k8s/"
+    },
+    {
+      "title": "Create a k6 extension",
       "description": "This short tutorial will walk you through the steps to build a k6 extension for Redis and use it in your k6 test.",
       "to": "",
       "url": "https://k6.io/blog/extending-k6-with-xk6"

src/data/markdown/docs/05 Examples/02 Tutorials.md

@@ -0,0 +1,15 @@
+---
+title: 'Tutorials'
+excerpt: 'k6 Tutorials'
+---
+
+- [Get started with k6](/examples/tutorials/get-started-with-k6/)
+- [8 basic tasks to learn k6](https://k6.io/blog/learning-js-through-load-testing/)
+- [k6 Learn](https://github.com/grafana/k6-learn)
+- [Swagger/OpenAPI integration](https://k6.io/blog/load-testing-your-api-with-swagger-openapi-and-k6)
+- [Schedule k6 tests with cron](https://k6.io/blog/performance-monitoring-with-cron-and-k6)
+- [Load test a GraphQL service](https://k6.io/blog/load-testing-graphql-with-k6)
+- [Use TypeScript in k6 scripts](https://github.com/k6io/template-typescript)
+- [Debug using a Web Proxy](https://k6.io/blog/k6-load-testing-debugging-using-a-web-proxy/)
+- [Distributed k6 tests on K8s](https://k6.io/blog/running-distributed-tests-on-k8s/)
+- [Create a k6 extension](https://k6.io/blog/extending-k6-with-xk6)

src/data/markdown/docs/05 Examples/02 Tutorials/01 Get started with k6.md

@@ -0,0 +1,42 @@
+---
+title: 'Get started with k6'
+excerpt: A series of docs to learn how to use the major features of k6
+---
+
+This tutorial provides some procedures for common real-life uses of k6.
+They assume no prior knowledge of k6 or of JavaScript.
+
+These tasks are all reproducible, so open up your favorite editor and follow along.
+Imagine that you are a developer or tester who is responsible for performance in your development team.
+
+## Context: test a new endpoint
+
+Your development team has just developed a new login endpoint.
+Before releasing, you must test the endpoint for the following questions:
+  - Does it work?
+  - Does it perform within the service-level objectives under average load?
+  - At what load does performance degrade beyond objectives?
+  
+After you test the endpoint, your team wants you to compare different components of the user-facing application.
+
+Finally, after you test the API and web application, break your scripts down into reusable parts. 
+
+## Before you start
+
+We encourage you to open your terminal and actively experiment with these examples.
+The tutorial requires the following:
+- [ ] [k6 installed](/get-started/installation) 
+- [ ] A clean directory to experiment in.
+- [ ] Something to do during the minute or two when k6 runs the longest example tests
+- [ ] Optional: [`jq`](https://stedolan.github.io/jq/) to filter some results
+
+## Tutorials
+
+| In this tutorial                                                                | Learn how to                                                       |
+|---------------------------------------------------------------------------------|--------------------------------------------------------------------|
+| [Test for functional behavior](/examples/tutorials/get-started-with-k6/test-for-functional-behavior) | Use k6 to script requests and evaluate that performance is correct |
+| [Test for performance](/examples/tutorials/get-started-with-k6/test-for-performance)         | Use k6 to increase load and find faults                            |
+| [Analyze results](/examples/tutorials/get-started-with-k6/analyze-results)                           | Filter results and make custom metrics                             |
+| [Reuse and re-run](/examples/tutorials/get-started-with-k6/reuse-and-re-run-tests)                          | Modularize and re-run tests                                         |
+
+

src/data/markdown/docs/05 Examples/02 Tutorials/01 Get started with k6/100 Test-for-functional-behavior.md

@@ -0,0 +1,136 @@
+---
+title: Test for functional behavior
+excerpt: Use k6 to write requests and assert that they respond correctly
+---
+
+In this tutorial, learn how to write a test that does the following:
+- Sends a POST request to the new endpoint 
+- Creates a check for the response status
+
+## Script the Request
+
+The first thing to do is to add logic for the endpoint.
+To do that, you need to make an [HTTP request](/using-k6/http-requests):
+1. Import the HTTP module.
+2. Create a payload to authenticate the user.
+3. Use the [`http.post`](/javascript-api/k6-http/post/) method to send your request with the payload to an endpoint.
+
+To test, copy this file and save it as `api-test.js`.
+
+<CodeGroup labels={["api-test.js"]} lineNumbers={[]} showCopyButton={[true]}>
+
+```javascript
+// import necessary module
+import http from "k6/http";
+
+export default function () {
+
+  // define URL and payload
+  const url = "https://test-api.k6.io/auth/basic/login/";
+  const payload = JSON.stringify({
+    username: "test_case",
+    password: "1234",
+  });
+
+  const params = {
+    headers: {
+      "Content-Type": "application/json",
+    },
+  };
+
+  // send a post request and save response as a variable
+  const res = http.post(url, payload, params);
+}
+``` 
+
+</CodeGroup>
+
+Run the script using the `k6 run` command:
+
+```bash
+k6 run api-test.js
+```
+
+After the test finishes, k6 reports the [default result summary](/results-output/end-of-test/#the-default-summary).
+
+```bash
+          /\      |‾‾| /‾‾/   /‾‾/   
+     /\  /  \     |  |/  /   /  /    
+    /  \/    \    |     (   /   ‾‾\  
+   /          \   |  |\  \ |  (‾)  | 
+  / __________ \  |__| \__\ \_____/ .io
+
+  execution: local
+     script: api-test.js
+     output: -
+  ...
+```
+
+To make sure you're getting the right response, you could log the response body to the console as follows:
+
+```javascript
+const res = http.post(url, payload, params);
+console.log(res.body);
+```
+
+## Add response checks
+
+Once you're sure the request is well-formed, add a [check](/using-k6/checks) that validates whether the system responds with the expected status code.
+
+1. Update your script so it has the following check function.
+
+  <CodeGroup labels={["checks response is 200"]} lineNumbers={["true"]} showCopyButton={[true]}>
+
+  ```javascript
+  // Import necessary modules
+  import { check } from "k6";
+  import http from "k6/http";
+  
+  export default function () {
+    // define URL and request body
+    const url = "https://test-api.k6.io/auth/basic/login/";
+    const payload = JSON.stringify({
+      username: "test_case",
+      password: "1234",
+    });
+    const params = {
+      headers: {
+        "Content-Type": "application/json",
+      },
+    };
+  
+    // send a post request and save response as a variable
+    const res = http.post(url, payload, params);
+  
+    // check that response is 200
+    check(res, {
+      "response code was 200": (res) => res.status == 200,
+    });
+  }
+  ```
+  
+  </CodeGroup>
+
+1. Inspect the result output for your check.
+   It should look something like this.
+
+   ```
+   ✓ response code was 200
+   ```
+ 
+
+<Blockquote mod="note" title="">
+
+Under larger loads, this check will fail in some iterations.
+**Failed checks do not stop tests.**
+
+Rather, k6 tracks the success rate and presents it in your [end of test](/results-output/end-of-test/) summary.
+
+</Blockquote>
+
+## Next steps
+
+In this tutorial, you've used k6 to make a POST request and check that it responds with a `200` status.
+
+However, these tests make only one request, which doesn't say much about how the system will respond under load.
+For that, you need to [test under load](/examples/tutorials/get-started-with-k6/test-for-performance/).