grafana · heitortsergent · Oct 31, 2024 · Oct 18, 2024 · Oct 18, 2024 · Oct 18, 2024
@@ -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:

@@ -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.
@@ -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.
@@ -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 >}}