Introduction to the Gatling Recorder

    Learn Gatling concepts and use the Recorder to create a runnable Gatling simulation.

    Introduction

    The Gatling Recorder allows you to capture browser-based actions to create a realistic user scenario for load testing. The Recorder application is launched from Gatling, using either the bundle, the Maven, Gradle, or sbt plugins, or the JavaScript SDK.

    In this tutorial, we use Gatling to load test a simple cloud-hosted web server and introduce you to the basic elements of the Recorder. We strongly recommend completing the Introduction to scripting tutorial before starting to work with the Recorder.

    This tutorial uses Java and the Maven-based Gatling bundle. Gatling recommends that developers use the Java SDK unless they are already experienced with Scala or Kotlin. Java is widely taught in CS courses, requires less CPU for compiling, and is easier to configure in Maven and Gradle. You can adapt the steps to your development environment using reference documentation links provided throughout the guide.

    Prerequisites

    This tutorial requires running Gatling on your local machine and using the Mozilla FireFox browser to create your Gatling Script. Additionally, the tutorial uses Gatling Enterprise Cloud to run tests with dedicated load generators and enhanced data reporting features. Use the following links to access each of the prerequisites:

    Plan the user scenario

    This tutorial uses an application named Computer-Database, which is deployed at the URL: http://computer-database.gatling.io. This application is for demonstration purposes and is read-only. Please be kind and only run small proof of concept load tests against the site.

    To test the performance of the Computer-Database application, create scenarios representative of what happens when users navigate the site.

    The following is an example of what a real user might do with the application.

    1. The user arrives at the application.
    2. The user searches for ‘macbook’.
    3. The user opens one of the search results.
    4. The user goes back to the home page.
    5. The user browses through pages of records.
    6. The user creates a new entry in the computer database.

    Launch the Recorder

    Using the Recorder requires running Gatling in your local development environment. To install Gatling, follow the Gatling installation instructions. Once you have installed Gatling, open the project in your IDE or terminal and launch the recorder:

        
    ./mvnw gatling:recorder

    mvnw.cmd gatling:recorder

    For the JavaScript SDK:

    npm run recorder

    Once launched, the Recorder application opens, allowing you to configure the settings before recording a web browser session.

    Set it up with the following options:

    • Recorder Mode set to HTTP Proxy
    • computerdatabase package
    • RecordedSimulation name
    • Follow Redirects? checked
    • Infer HTML resources? checked
    • Automatic Referers? checked
    • Remove cache headers? checked
    • No static resources clicked
    • Select the desired format. This tutorial assumes “Java 17”

    After configuring the recorder, all you have to do is click Start!.

    Record a website session

    Once the Recorder is launched, there are 4 buttons to control the session recording:

    • Add - adds a tag to organize actions in your session.
    • Clear - clears the Executed events.
    • Cancel - cancels the Recorder session.
    • Stop & Save - stops and saves the current Recorder session.

    Based on the scenario described in Launch the Recorder perform the following actions in your configured web browser. Try to act as a real user would, don’t immediately jump from one page to another without taking the time to read. This makes your scenario similar to how a real user would behave.

    1. Enter a ‘Search’ tag in the Recorder application and click Add.
    2. Go to the website: http://computer-database.gatling.io
    3. Search for models with ‘macbook’ in their name.
    4. Select ‘Macbook pro’.
    5. Return to the Recorder application.
    6. Enter a ‘Browse’ tag and click Add
    7. Go back to the home page.
    8. Browse through the model pages by clicking on the Next button.
    9. Return to the Recorder application.
    10. Enter an ‘Edit’ tag and click Add.
    11. Return to the browser and Click on Add new computer.
    12. Fill the form.
    13. Click on Create this computer.
    14. Return to the Recorder application and click Stop

    The simulation is generated in the folder:

        
    src/test/java/

    src/

    Run the simulation on Gatling Enterprise Cloud

    Gatling Enterprise Cloud is a feature-rich SaaS platform that is designed for teams and organizations to get the most out of load testing. With the trial account, you created in the Prerequisites section, you can upload and run your test with advanced configuration, reporting, and collaboration features.

    From Gatling 3.11 packaging and running simulations on Gatling Enterprise Cloud is simplified by using configuration as code. In this tutorial, we only use the default configuration to demonstrate deploying your project. You can learn more about customizing your configuration with our configuration-as-code guide.

    To deploy and run your simulation on Gatling Enterprise Cloud, use the following procedure:

    1. Generate an API token with the Create permission in your Gatling Enterprise Cloud account.

    2. Add the API token to your current terminal session by replacing <your-API-token> with the API token generated in step 1 and running the following command:

          
      export GATLING_ENTERPRISE_API_TOKEN=<your-API-token>

      set GATLING_ENTERPRISE_API_TOKEN=<your-API-token>

      JavaScript SDK:

      Coming soon

    3. Run the following command in your terminal to deploy and start your simulation:

          
      ./mvnw gatling:enterpriseStart

      mvnw.cmd gatling:enterpriseStart

      JavaScript SDK:

      Coming soon

    Watch the Simulation deploy automatically and generate real-time reports.

    Run the simulation locally for debugging

    The open-source version of Gatling allows you to run simulations locally, generating load from your computer. Running a new or modified simulation locally is often useful to ensure it works before launching it on Gatling Enterprise Cloud. Using the terminal, you can launch your test with the following command in the project root directory:

        
    ./mvnw gatling:test

    mvnw.cmd gatling:test

    JavaScript SDK:

        
    npx gatling run  --simulation  <simulation-name>

    npx gatling run  --typescript --simulation  <simulation-name>

    The Gatling interactive CLI starts and asks a series of questions. Answer the questions as follows:

    1. Press 1 and then enter to select Run the Simulation locally.
    2. Press 0 and then enter to select RecordedSimulation
    3. (optional) Enter a run description.
    4. Press enter.

    The simulation should start on your local machine, with the progress displayed in your terminal. When the test has finished, there is an HTML link in the terminal that you can use to access the static report.

    Keep learning

    Now that you have completed the Introduction to scripting and Introduction to the Recorder tutorials, you have a solid foundation of Gatling and load testing knowlege. We strongly recommend you complete the Writing realistic tests tutorial to learn the essential skills for writing clean and concise tests.

    Edit this page on GitHub

    ← Create your first JavaScript-based simulation
    Writing realistic Gatling tests →