diff --git a/docs/sources/k6-studio/_index.md b/docs/sources/k6-studio/_index.md index 42dea7c815..8cf1225edd 100644 --- a/docs/sources/k6-studio/_index.md +++ b/docs/sources/k6-studio/_index.md @@ -16,9 +16,21 @@ cards: description: An overview of k6 Studio and its components. height: 24 - title: Installation - href: ./installation/ + href: ./set-up/install/ description: Learn how to install k6 Studio. height: 24 + - title: Record your first script + href: ./record-your-first-script/ + description: Get started with k6 Studio by recording a test, creating rules, and validating the generated script. + height: 24 + - title: Components + href: ./components/ + description: Understand how the Test Recorder, Test Generator, and Test Validator components work. + height: 24 + - title: Troubleshoot + href: ./troubleshoot/ + description: Troubleshoot common issues with k6 Studio. + height: 24 cascade: labels: products: diff --git a/docs/sources/k6-studio/components/_index.md b/docs/sources/k6-studio/components/_index.md new file mode 100644 index 0000000000..0c1f910a4c --- /dev/null +++ b/docs/sources/k6-studio/components/_index.md @@ -0,0 +1,17 @@ +--- +title: 'Components' +description: 'Understand the components that make up k6 Studio' +weight: 400 +--- + +# Components + +The k6 Studio desktop application consists of three components: + +- [**Test Recorder**](https://grafana.com/docs/k6-studio/components/test-recorder/): The Test Recorder can help you generate a HAR file. When you start a recording, the application uses a proxy recorder and launches an instance of Chrome, and records the traffic from your actions on the browser. +- [**Test Generator**](https://grafana.com/docs/k6-studio/components/test-generator/): The Test Generator takes the output of a test recording and gives you options to customize the test with a visual interface and generate a test script from it. You can use it to define a list of hosts to allow or remove from your script, include variables in your script, and configure rules to extract values, parameterize requests, and more. +- [**Test Validator**](https://grafana.com/docs/k6-studio/components/test-validator/): The Test Validator can help you validate that a test script is working as expected. You can use it to run one iteration of your test, and visualize the request and response of any requests on your test script. The Test Validator works with any k6 test script, not only scripts generated via the Test Generator. + +Each component can be used separately. If you have a HAR recording, you can add it to the Test Recorder folder to visualize the request and response data, or you can import a script you create manually to the Test Validator folder, and use it to run one iteration of that test. + +For more details about each components, refer to their individual pages. diff --git a/docs/sources/k6-studio/components/test-generator.md b/docs/sources/k6-studio/components/test-generator.md new file mode 100644 index 0000000000..94236742ae --- /dev/null +++ b/docs/sources/k6-studio/components/test-generator.md @@ -0,0 +1,224 @@ +--- +title: 'Test Generator' +description: 'Understand how the k6 Studio Test Generator works' +weight: 200 +--- + +# Test Generator + +The Test Generator takes the output of a test recording and gives you options to customize the test with a visual interface and generate a test script from it, without having to manually write JavaScript code. + +You can use it to define a list of hosts to allow or remove from your script, tweak the load profile for your test, include variables in your script, and configure rules to extract values, parameterize requests, and more. + +{{< figure src="/media/docs/k6-studio/screenshot-k6-studio-test-generator-panels-2.png" alt="k6 Studio Test Generator window, showing a test generator with three test rules, the requests panel open on the right side with several requests, and the correlation rule panel open and configured to search for a CSRF token" >}} + +The Test Generator window is composed of: + +1. **Test generator name**: The name of the test generator. This is automatically generated, but you can rename it to help keep your files organized. +2. **Test Generator actions**: On the top-right you can see the action buttons for the Test Recorder. From here you can click **Save Generator** to save changes to your test generator file, or click the menu icon to: + - **Validate script**: Opens the [Test Validator](https://grafana.com/docs/k6-studio/components/test-validator/) and starts a one iteration run of the test script. + - **Export script**: Opens the export script dialog box. You can enter a name for your script, and also select whether you want to overwrite a script if one with the same name already exists. + - **Delete generator**: Deletes the selected test generator. +3. **Test Generator options**: Below the test generator name, you can see: + - **Add rule**: Opens a list of rule types that you can add to the generator. + - **Test options**: Configure the load executor, think time, and test variables. + - **Allowed hosts**: Shows a list of hosts for the recording, and lets you select which ones to include or remove from the script. +4. **Test rules list**: The list of test rules applied to this particular generator. The rules can be reordered, and you can see some details about how they're configured. +5. **Request, response, script, and rule inspector**: When you click on a request from the requests list, a panel opens on the right side which shows the request and response details for that request. You can use it to inspect the headers, payload, cookies, and content of the requests. + +## Test options + +The test options tab lets you configure three separate parts of your test script: + +- Load profile +- Think time +- Test data + +### Load profile + +The load profile controls how k6 schedules VUs and iterations to run your performance test. + +There are two executors available under load profiles: + +- **Ramping VUs**: A variable number of VUs execute as many iterations as possible for a specified amount of time. +- **Shared iterations**: A fixed number of iterations are shared between a number of VUs, and the test ends once all iterations have been executed. + +Each executor has different variables you can configure. For more details, refer to [Executors](https://grafana.com/docs/k6/latest/using-k6/scenarios/executors/). + +### Think time + +The think time option lets you configure a fixed or random delay, between groups or iterations, to simulate a more realistic test. This isn't required, but it's a best practice when creating and running performance tests. + +### Test data + +The test data option lets you define variables, which you can then use in your [custom code](#custom-code-rule) and [parameterization](#parameterization-rule) rules. + +After you define a variable, you can refer to them in your custom code rules by using: `VARS["VARIABLE_NAME"]`. + +## Allowed hosts + +The **Allowed hosts** option lets you configure which hosts you want to include in your test script. It shows all the hosts that are identified from your HAR recording file, and you can choose to select which ones you want to include or remove from your test script. + +For performance testing, it's common to not include static assets, or remove hosts from 3rd-party services from your tests, but you can include them depending on your use case. + +## Rules + +Test rules are rules you can add and configure to your test generator, that allow you to customize the generated test script. These rules can use the information from a test recording, to then generate code changes to help make your test scripts more reliable, and reusable. + +The available rules are: + +- Verification rule +- Correlation rule +- Parameterization rule +- Custom code rule + +You can add multiple correlation and custom code rules to your test generator. + +### Verification rule + +The verification rule is a default rule that's created for every test generator. It adds a [check](https://grafana.com/docs/k6/latest/using-k6/checks/) statement after every request that validates if the response status code is the same as the one from the test recording. + +The verification rule is useful for making sure that your systems are performing as expected. Failed checks do not cause a test to abort, or interrupt a test run. Checks generate a metric that you can inspect after a test run is completed to understand how your system performed. + +For more details about checks, refer to [Checks](https://grafana.com/docs/k6/latest/using-k6/checks/). + +### Correlation rule + +The correlation rule lets you extract data from your test recording, and reuse it across your test script. This is a common use case when working with applications that have unique IDs that are generated for a request, and then are passed to every subsequent request, for example. + +The correlation rule includes an Extractor and a Replacer. They both have the same configuration options, but the Extractor can be used to find and extract the value you want to use across the script, and the Replacer can be used to find the places where you want to replace and use the extracted value. + +The configuration fields are: + +- **Filter**: Define a request path that this filter applies to. Plain text and regular expression are supported. +- **Target**: Select the headers, body, or URL path as the target for the extractor or replacer. +- **Type**: Select Begin-End, Regex, or JSON as the way to search for the value to be extracted or replaced. + - **Begin-End**: Define the Begin and End values as the strings immediately before and after the value to be extracted or replaced. + - **Regex**: Define the regular expression to match the value to be extracted or replaced. + - **JSON**: Define the JSON path to match the value to be extracted or replaced. + +When creating or editing a correlation rule, you can use the **Rule preview** panel to check that your configuration options are working as intended, and being applied to the correct requests and values in your test script. + +### Parameterization rule + +The parameterization rule lets you parameterize your requests to use a text value, or the value from a variable. For example, you can replace a `userId` value in all requests with a test user ID defined as a text value in the rule tab, or use a variable name from the **Test variables** tab. + +The configuration fields are: + +- **Filter**: Define a request path that this filter applies to. Plain text and regular expression are supported. +- **Target**: Select the headers, body, or URL path as the target for the extractor or replacer. +- **Type**: Select Begin-End, Regex, or JSON as the way to search for the value to be replaced. + - **Begin-End**: Define the Begin and End values as the strings immediately before and after the value to be replaced. + - **Regex**: Define the regular expression to match the value to be replaced. + - **JSON**: Define the JSON path to match the value to be replaced. +- **Replace with**: Select **Text value** or **Variables** for the value to be used as a replacement for the request data. For **Variables**, make sure that you configure the variable value to be used under **Test options** -> **Test data**. + +When creating or editing a parameterization rule, you can use the **Rule preview** panel to check that your configuration options are working as intended, and being applied to the correct requests and values in your test script. + +### Custom code rule + +The custom code rule lets you insert a custom JavaScript code snippet in your test script. + +The custom code rule has two options: + +- **Filter**: Define a request path that this filter applies to. Plain text and regular expression are supported. +- **Placement**: Select between **Before matched requests** or **After matched requests**. + +### Rule selectors + +For correlation and parameterization rules, you can use the following selectors: + +- **Begin-end**: Match a value between two strings. +- **JSON**: Use dot notation to match a value in the JSON payload or response body. +- **Regex**: Use a regular expression to match a value. + +#### Begin-end selector + +This selector is useful when your target value is between two known strings. For example, to match a value in a URL: + +``` +https://example.com/products/1234/details +``` + +To replace `1234` with another value, use the following configuration: + +``` +Target: URL +Type: Begin-end +Begin: /products/ +End: /details +``` + +#### JSON selector + +This selector is ideal when your target value is in a JSON payload or response body. It uses dot notation to access nested properties. For example, in this JSON: + +```json +{ + "name": "Product name", + "details": { + "id": 1234 + }, + "tags": ["electronics", "sale"], + "variants": [ + { + "color": "blue", + "stock": 5 + }, + { + "color": "red", + "stock": 3 + } + ] +} +``` + +You can replace values use the following configurations: + +``` +# Replace nested object value +Target: Body +Type: JSON +Path: details.id + +# Replace array element +Target: Body +Type: JSON +Path: tags.0 + +# Replace nested array object value +Target: Body +Type: JSON +Path: variants.0.stock +``` + +### Regex selector + +When the previous selectors don't meet your needs, you can use regular expressions for more granular matching. For example, to match an authorization token in a header: + +``` +Headers +Authorization: Bearer eyJhbGciOiJIUzI1NiI +``` + +To replace `eyJhbGciOiJIUzI1NiI` with another value, use the following configuration: + +``` +Target: Headers +Type: Regex +Regex: Bearer (.+) +``` + +{{< admonition type="note" >}} + +The regular expression must include a capturing group `()` to specify the value you want to replace. + +{{< /admonition >}} + +## Validate and export script + +After you're done configuring the test options and rules for your test generator, you can click the menu icon on the top-right to validate and export your script. + +When clicking on validate script, the Test Validator opens and runs one iteration of your test script. You can click on each request to inspect the request and response, and view the logs, checks, and script tab to review the output of the test generator. + +After validating your script, you can export it so you can run it using the k6 CLI, or using Grafana Cloud k6. diff --git a/docs/sources/k6-studio/components/test-recorder.md b/docs/sources/k6-studio/components/test-recorder.md new file mode 100644 index 0000000000..3708da6087 --- /dev/null +++ b/docs/sources/k6-studio/components/test-recorder.md @@ -0,0 +1,32 @@ +--- +title: 'Test Recorder' +description: 'Understand how the k6 Studio Test Recorder works' +weight: 100 +--- + +# Test Recorder + +The Test Recorder is the first component of k6 Studio. With it, you can start a recording which opens a browser window, and then navigate through a website or application to record a user flow you want to test. k6 Studio collects every request and response, and once you stop the recording, it generates a HAR file. You can then inspect every request and response to see if your test recording accurately reflects a user flow, and can be used as the source for your test script. + +{{< figure src="/media/docs/k6-studio/screenshot-k6-studio-test-recorder-panels.png" alt="k6 Studio Test Recorder window, showing a completed test recording with eight requests, and numbers next to each section of the application" >}} + +The Test Recorder window is composed of: + +1. **Test recording name**: The name of the test recording and HAR file. This is automatically generated, but you can rename it to help keep your recordings organized. +2. **Test Recorder actions**: On the top-right you can see the action buttons for the Test Recorder. Depending on whether you're starting a recording or inspecting a recording, you might see: + - **Start recording** or **New recording**: Starts a new recording. + - **Stop recording**: Stops the existing recording. + - **Discard and start over**: Discard the existing recording and starts a new one. + - **Create test generator**: Creates a test generator from the selected test recording. +3. **Test Recorder options**: Below the test recording name, you can see: + - **Requests**: The total number of requests in the recording + - **Show static assets**: A toggle that controls whether you can see all static assets requests in the Requests list. The static assets requests are hidden by default. + - **Filter**: A search box that lets you filter the list of requests by URL, method (such as GET or POST), and status code. +4. **Requests and groups list**: The list of requests, and groups if any, in the HAR file. The requests are organized by time, and you can see the method, status code, host, and path for each one. You can also collapse and expand groups to inspect them more easily. +5. **Request and response inspector**: When you click on a request from the requests list, a panel opens on the right side which shows the request and response details for that request. You can use it to inspect the headers, payload, cookies, and content of the requests. + +{{< admonition type="note" >}} + +The recorder uses a proxy to catch requests from the specific browser window, which is powered by [mitmproxy](https://github.com/mitmproxy/mitmproxy). + +{{< /admonition >}} diff --git a/docs/sources/k6-studio/components/test-validator.md b/docs/sources/k6-studio/components/test-validator.md new file mode 100644 index 0000000000..61257af83a --- /dev/null +++ b/docs/sources/k6-studio/components/test-validator.md @@ -0,0 +1,67 @@ +--- +title: 'Test Validator' +description: 'Understand how the k6 Studio Test Validator works' +weight: 300 +--- + +# Test Validator + +The Test Validator can help you validate that a test script is working as expected. You can use it to run one iteration of your test, and visualize the request and response of any requests on your test script, as well as [checks](https://grafana.com/docs/k6/latest/using-k6/checks/) and [logs](https://grafana.com/docs/grafana-cloud/testing/k6/analyze-results/inspect-test-results/inspect-logs/). The Test Validator works with any k6 test script, not only scripts generated in k6 Studio. + +{{< figure src="/media/docs/k6-studio/screenshot-k6-studio-test-validator-panels-2.png" alt="k6 Studio Test Validator window, showing a test script that has been executed, with a list of requests and their status code, as well as the request and response panels on the right, and the script preview" >}} + +The Test Validator window is composed of: + +1. **Test script name**: The name of the test script. +2. **Test Validator actions**: On the top-right you can see the action buttons for the Test Validator. From here you can click **Validate script** to run one iteration of your test script, or click the menu icon to: + - **Open external script**: Open a k6 test script from your computer. After opening it, click **Validate script** to run one iteration of the test. + - **Delete**: Deletes the selected test script. +3. **Test Validator options**: Below the test recording name, you can see: + - **Requests**: The total number of requests in the recording + - **Filter**: A search box that lets you filter the list of requests by URL, method (such as GET or POST), and status code. +4. **Requests and groups list**: The list of requests, and groups if any, that were executed in the test run. The requests are organized by time, and you can see the method, status code, host, and path for each one. You can also collapse and expand groups to inspect them more easily. +5. **Request, response, script, and rule inspector**: When you click on a request from the requests list, a panel opens on the right side which shows the request and response details for that request. You can use it to inspect the headers, payload, cookies, and content of the requests. +6. **Logs, checks, and script inspector**: Any logs or checks generated by test run can be found on their respective tabs. You can also visualize the script that was executed here, to help you debug the behavior from the test run results. + +## Validate a test + +There are two ways to validate a test: + +- Use the **Test Generator** component: + 1. Open a test generator + 2. Click the menu icon on the top-right, and select **Validate script**. +- Use the **Scripts** component: + 1. Open a script + 2. Click **Validate script** on the top-right. + +After you click **Validate script**, k6 Studio runs one iteration of the test script and shows you the results of the test as the script is executed. + +## Inspect test results + +During a test script run, and once it's completed, you can inspect the test results. Similar to the Test Recording component, you can click on any requests from the **Requests** list to view the request and response data, including the header, payload, and cookies. + +You can also view any [logs](https://grafana.com/docs/grafana-cloud/testing/k6/analyze-results/inspect-test-results/inspect-logs/) and [checks](https://grafana.com/docs/k6/latest/using-k6/checks/) generated by the test run in the **Logs** and **Checks** tabs to help you debug your test script. + +## Validate external script + +You can use the Test Validator to validate scripts that are created outside k6 Studio as well: + +1. From the k6 Studio homepage, click **Validate script**. +2. Click **Open external script**. + +Alternatively, from the Test Validator screen you can: + +1. Click the menu options icon on the top-right. +2. Click **Open external script**. + +You can then select a script located outside of k6 Studio, and then click **Validate script** to execute one iteration of the test. + +If you want to view the script under the **Scripts** section of the k6 Studio application, you can: + +1. Open the k6-studio Scripts folder. + - For macOS, that can be found in `~/Documents/k6-studio/Scripts`. + - For Windows, that can be found in `C:\Users\\Documents\k6-studio`. + - If you have a script in k6 Studio already, you can right-click on it and click **Open containing folder**. +2. Copy your script to the Scripts folder. + +After that, you should be able to see your test script in k6 Studio under **Scripts**. diff --git a/docs/sources/k6-studio/introduction.md b/docs/sources/k6-studio/introduction.md index c34afbbc2c..c702d7f2a4 100644 --- a/docs/sources/k6-studio/introduction.md +++ b/docs/sources/k6-studio/introduction.md @@ -8,9 +8,9 @@ weight: 100 k6 Studio is a free, open source desktop application designed to help you create k6 test scripts using a visual interface. -![k6 Studio homepage](/media/docs/k6-studio/screenshot-k6-studio-homepage.png) +{{< figure src="/media/docs/k6-studio/screenshot-k6-studio-homepage-2.png" alt="k6 Studio homepage" >}} -[Grafana k6](https://grafana.com/docs/k6/latest/) is an open source performance testing tool that allows you to run JavaScript scripts to test your applications. One of the biggest challenges users face when they're getting started with k6 is generating test scripts from scratch, especially when working with applications that you might not have easy access to the source code or documentation. +[Grafana k6](https://grafana.com/docs/k6/latest/) is an open source performance testing tool that you can use to run JavaScript scripts to test your applications. One of the biggest challenges users face when they're getting started with k6 is generating test scripts from scratch, especially when working with applications that you might not have easy access to the source code or documentation. For users that have less experience with JavaScript or k6, k6 Studio can help you create a script from a browser session and allow you to quickly get started running test scripts to test your application. For developers who are already familiar with k6, k6 Studio can optimize the time it takes to create a new script, and give you tools to validate and debug your scripts outside of the CLI. diff --git a/docs/sources/k6-studio/record-your-first-script.md b/docs/sources/k6-studio/record-your-first-script.md new file mode 100644 index 0000000000..a96f626002 --- /dev/null +++ b/docs/sources/k6-studio/record-your-first-script.md @@ -0,0 +1,194 @@ +--- +title: 'Record your first script' +description: 'Learn the basics of k6 Studio. Create a test recording, configure a test generator, and run a test script' +weight: 300 +--- + +# Record your first script + +This tutorial shows how to create a recording, set up custom rules, and generate a test script using k6 Studio. + +In this tutorial, you will: + +- Create a test recording using the https://test-api.k6.io/ service. +- Learn how to create groups to organize your test recordings. +- View the request and response data from a test recording. +- Use the Test Generator to create a correlation and a custom code rule. +- Validate your test script from the Test Generator. +- Export your test script. + +## Before you begin + +To complete this tutorial, you'll need to: + +- Have a Windows or macOS machine. +- [Install k6 Studio](https://grafana.com/docs/k6-studio/set-up/install/). +- [Install Google Chrome](https://www.google.com/chrome/). + +{{< admonition type="note" >}} + +This tutorial uses the `test-api.k6.io` service, which is a public shared environment. You can use it and follow along this tutorial, or you can use a service that you own. The `test-api.k6.io` service is also [open source](https://github.com/grafana/test-api.k6.io) if you’d like to deploy a private instance. + +{{< /admonition >}} + +## Create a test recording + +To create a test recording: + +1. Open the k6 Studio desktop application. +1. Click **Record Flow**. +1. Type "test-api.k6.io" under **Starting URL**. +1. Click **Start recording**. You should see a Google Chrome window open after a few seconds, and the **Requests** header in the k6 Studio application. + + {{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-1-test-recorder.png" >}} + +1. In k6 Studio, click the edit button next to **Default group**, rename it to "Homepage", and press **Enter**. +1. Next click **Create group**, name it “Go to Create Crocs”, and press **Enter**. Groups can help organize your test scripts so they're easier to edit and maintain in the future, and give you timing metrics for each group in your test script. +1. In the browser window, under **Private APIs**, click on **/my/crocodiles** next to the **POST** method. You should see an authentication dialog box in the next screen. +1. For username, enter "studio-user". For password, enter "password". + +You'll be logged in to the test service, and this will complete the requests for the "Go to Create Crocs" group. + +{{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-2-test-api-service.png" >}} + +### Create a crocodile + +In this next step, you'll use the form for the test service to create a crocodile. + +To create a crocodile: + +1. In k6 Studio, click **Create group**, name it "Create Croc", and press **Enter**. +1. In the browser window, you should have successfully authenticated in the previous step and be able to see the **My Crocodiles** page. Fill out the **Name**, **Sex**, and **Date of birth** fields of the HTML form section. + + {{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-3-create-crocodile.png" >}} + +1. Click **POST** to submit the API request. +1. In k6 Studio, click **Stop recording**. + +After you click **Stop recording**, k6 Studio saves the recording as a HAR file. + +{{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-4-save-test-recording.png" >}} + +### Rename the recording + +In the sidebar, you can change the name of the recording after it's created. To do that: + +1. In k6 Studio, right click on the recording you just created in the left sidebar. +1. Rename the recording to `createc crocs`. +1. Press **Enter** to confirm the changes. + +### Inspect response and request data + +After you finish a recording, you can visualize the request and response data for each request included in your test recording. + +To view the request and response data for a request, click on the request you would like to inspect from the **Requests** list. + +{{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-5-test-recording-inspector.png" >}} + +The Request and Response panels have tabs where you can view the headers, payload, or cookies for a request, and the headers, content, and cookies for a response. For the response content tab, you can also view it in different formats, such as the raw data, or a preview. + +## Generate a script from a test recording + +To generate a script from a test recording: + +- If you still have the test recording open from the last step, click **Create test generator** on the top-right. +- You can also click **+** next to Test Generator on the left side, and then select your recording on the right side under **Requests**. + +A dialog box shows up that lets you select the hosts to use from the recording for generating the script. Select `test-api.k6.io` and press **Continue**. + +{{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-6-test-generator-allowed-hosts.png" >}} + +The Test Generator lets you generate and modify a k6 test script via the user interface, without having to write JavaScript code. + +On the right side, you can inspect the recording from this view, similar to the Test Recorder. On the left side, you can see the list of **Test rules**, with a **Verification rule** already added. And on the right side, you can inspect the recording, similar to the **Test Recorder** view. + +{{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-7-test-generator.png" >}} + +**Test rules** are objects that you can add to your generator file to modify the script generated from the recording. The **Verification rule** that's created by default modifies the script to add [Checks](https://grafana.com/docs/k6/latest/using-k6/checks/). These checks verify that when you run your script, the status codes you receive from responses are the same as the one you previously recorded. That's a nice safety measure for your system that you get by default. + +You can also inspect the script that would be generated by selecting the **Script** tab in the right panel where you can see the requests. + +## Correlate dynamic data + +If you inspect the data of the **POST** request, you can see that it makes use of a `csrf` token. + +{{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-8-form-csrf-token-2.png" >}} + +This is a token that was generated from a previous request and that was present in the form for security reasons. That's an example of a dynamic value that you can't possibly know when generating the script because that value is generated by the server when you reach the form, and the server expects it back when you submit the form. + +You'll need a way to generate the script so that it knows to get this value at runtime and replace the value from the recording from this extraction. You can do that by using the **Correlation Rule**. + +To add a correlation rule: + +1. In k6 Studio, press **+ Add rule** and select **Correlation** from the entries. +1. Under **Extractor**, in the **Begin** field, type `csrfmiddlewaretoken" value="`. +1. In the **End** field, type `"`. + +{{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-9-correlation-rule.png" >}} + +On the right side, you can notice that a new panel appears called **Rule preview**. This panel shows the request that matches the **Filter** field for the value extraction, the extracted value, and the matched requests where this value was replaced with the runtime correlation. + +{{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-10-rule-preview.png" >}} + +The **Rule preview** panel updates in real-time as you edit your rule. It's useful to see when you actually have a match and where you are actually replacing values. For the extraction, only the first request matched will extract the value. For replacing it, by default the rule will try to find occurrences of that value and automatically replace those. If you need more control over it you can open the toggle to customize the replacer selector. + +With this rule in place, you have added dynamic data correlation to your script without having to touch any code. + +## Insert a custom JavaScript snippet + +You can make use of the **Custom Code** rule to insert a custom JavaScript snippet in your script. + +1. In k6 Studio, press **+ Add rule** and select **Custom Code** from the entries. +1. In the **Snippet** input, type `console.log('hello k6')`. + +{{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-11-custom-code-rule.png" >}} + +If you have the script panel open, you can see the script getting updated in real-time with the snippet inserted. + +## Validate a test script + +To validate a test script: + +1. In k6 Studio, click the menu options icon on the top right. +1. Click **Validate script**. + +The Test Validator runs your script in a single iteration and lets you inspect the requests and responses sent, and see any logs and checks from k6. + +{{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-12-test-validator.png" >}} + +The checks generated by the default **Verification rule** that can give you a quick glimpse if the script is working as expected. + +{{< figure src="/media/docs/k6-studio/tutorial/screenshot-k6-studio-tutorial-13-test-validator-checks.png" >}} + +In the Test Validator, you can also inspect requests details similar to the Test Recorder and Generator, giving you a powerful tool to debug your script. + +## Export a test script + +To export a test script: + +1. In k6 Studio, click the menu options icon on the top right. +1. Click **Export script**. +1. Enter a name for the script. +1. Click **Export**. + +After you save the script, it'll show up under **Scripts** on the left side. You can right click on the script and click **Open containing folder** to find it in your system, and then use `k6` to run it. + +## Summary + +To summarize: + +- You created a test recording using the https://test-api.k6.io/ service. +- You created groups to organize a test recording into logical steps. +- You learned how to view request and response data from a test recording. +- You created a Test Generator from a test recording, and learned how to use the correlation and custom code rules. +- You learned how to validate a test script after setting up rules in the Test Generator. +- You exported a test script from your test recording and rules setup. + +Now you can use the same steps to create a test recording for an application or service that you own and generate test scripts. You can then use those scripts to run performance tests by using the k6 CLI, or Grafana Cloud k6. + +## Next steps + +Now that you learned the basics of how to use k6 Studio, you can: + +- Learn how to [install and run a test using the k6 CLI](https://grafana.com/docs/k6/latest/get-started/running-k6/). +- Learn how to [run your test using Grafana Cloud k6](https://grafana.com/docs/grafana-cloud/testing/k6/get-started/run-cloud-tests-from-the-cli/). diff --git a/docs/sources/k6-studio/set-up/_index.md b/docs/sources/k6-studio/set-up/_index.md new file mode 100644 index 0000000000..5e63b2febd --- /dev/null +++ b/docs/sources/k6-studio/set-up/_index.md @@ -0,0 +1,11 @@ +--- +title: 'Set up' +description: 'Learn how to install and configure k6 Studio' +weight: 200 +--- + +# Set up + +This section includes the following topics: + +{{< section menuTitle="true" withDescriptions="true">}} diff --git a/docs/sources/k6-studio/installation.md b/docs/sources/k6-studio/set-up/install.md similarity index 93% rename from docs/sources/k6-studio/installation.md rename to docs/sources/k6-studio/set-up/install.md index 4a4a39e4c2..e3488b56f4 100644 --- a/docs/sources/k6-studio/installation.md +++ b/docs/sources/k6-studio/set-up/install.md @@ -1,10 +1,10 @@ --- -title: 'Installation' +title: 'Install k6 Studio' description: 'Learn how to download and install k6 Studio' -weight: 200 +weight: 100 --- -# Installation +# Install k6 Studio You can install k6 Studio on Windows and macOS. diff --git a/docs/sources/k6-studio/set-up/settings.md b/docs/sources/k6-studio/set-up/settings.md new file mode 100644 index 0000000000..38a0bb58bb --- /dev/null +++ b/docs/sources/k6-studio/set-up/settings.md @@ -0,0 +1,38 @@ +--- +title: 'Settings' +description: 'Learn how to configure k6 Studio settings' +weight: 200 +--- + +# Settings + +k6 Studio includes a few settings you can configure by clicking on **Settings** on the bottom-left side of the application. + +## Recorder settings + +### Automatically detect browser + +When this setting is enabled, k6 Studio looks for Google Chrome in the default installation path in your system. + +You can turn off this setting and provide a custom path to a Google Chrome executable file. + +## Proxy settings + +### Port number + +The port number that the proxy recorder should listen to. By default, it's set to `6000`. You can customize this value and turn on or off the option to allow k6 Studio to find a different port if the one that's specified is in use. + +### Proxy mode + +There are two configuration options for proxy mode: + +- **Regular**: The default mode where k6 Studio proxies requests. +- **Upstream**: k6 Studio forwards requests to a server you specify. This mode is useful when your system is already behind another proxy, and you need k6 Studio to forward requests to it instead. + +If you choose the **Upstream** mode, you have to configure a **Server URL** value, and you can optionally provide authentication credentials and a certificate file. + +## Usage report + +### Send anonymous usage data + +k6 Studio sends anonymous usage data of the k6 Studio application to Grafana. This is enabled by default, and you can turn it off if you'd like not to send any data. Refer to [Usage collection](https://grafana.com/docs/k6-studio/set-up/usage-collection/) for more details. diff --git a/docs/sources/k6-studio/set-up/usage-collection.md b/docs/sources/k6-studio/set-up/usage-collection.md new file mode 100644 index 0000000000..d0240f60a6 --- /dev/null +++ b/docs/sources/k6-studio/set-up/usage-collection.md @@ -0,0 +1,18 @@ +--- +title: 'Usage collection' +description: 'Learn what data k6 Studio collects and stores' +weight: 300 +--- + +# Usage collection + +By default, k6 Studio sends an anonymous usage report so that we can track how users are using the product and its features. We use that information to prioritize the roadmap with the features that will benefit a majority of users, and reduce the impact of any changes we make. + +The usage report doesn't contain any information about you or what you are testing. The contents included in the report are: + +- The running program’s operating system (`mac` or `win`). +- The running program’s architecture (`arm64` or `x86_64`). +- The k6 Studio version (for example, `0.4.0`). +- The timestamp of when the data was collected (for example, `2024-10-22T16:02:56.261Z`). + +Grafana k6 is also bundled with k6 Studio, and it also collects and sends an anonymous usage report. For more details about the Grafana k6 data that's collected, refer to [Usage collection](https://grafana.com/docs/k6/latest/set-up/usage-collection/). diff --git a/docs/sources/k6-studio/troubleshoot.md b/docs/sources/k6-studio/troubleshoot.md new file mode 100644 index 0000000000..09f60a8d35 --- /dev/null +++ b/docs/sources/k6-studio/troubleshoot.md @@ -0,0 +1,32 @@ +--- +title: 'Troubleshoot' +description: 'Common issues with k6 Studio and how to fix them' +weight: 600 +--- + +# Troubleshoot + +This section details common issues with k6 Studio and how to fix them. + +## `localhost` requests are not being recorded + +The proxy doesn't capture traffic when sent directly to `localhost`. To fix that, you can assign a hostname to it and make requests through that name. To do that, modify the hosts file on your system. For example, you can add the following line to your hosts file: + +``` +127.0.0.1 myapp +``` + +After, if you have an application running on port 8000, you can make requests in your browser at `myapp:8000`, and they'll show up in k6 Studio. + +## "Proxy failed to start" error + +If you're on a Mac, make sure you're not running the k6 Studio application from the Downloads folder. If that's the case, close the app, move the application file to the Applications folder, and start the app again. + +## Application logs + +The application logs are saved in the following directory: + +- On macOS: ~/Library/Logs/k6 Studio/k6-studio.log +- On Windows: %USERPROFILE%\AppData\Roaming\k6 Studio\logs\k6-studio.log + +If have any issues with k6 Studio, include a tail of your log file when [opening an issue on GitHub](https://github.com/grafana/k6-studio).