App & Browser Testing Made Easy

Give your users a seamless experience by testing on 3000+ real devices and browsers. Don't compromise with emulators and simulators

Get Started free
Home Guide How to run test on GitLab CI Locally

How to run test on GitLab CI Locally

By Pratik Barjatiya, Community Contributor -

GitLab CI is a continuous integration and continuous delivery & deployment (CI/CD) server. It helps agile teams to test code from a concentrated area, all while furnishing built-in integration with Git repositories. In this guide, we will examine how to utilize GitLab CI to run tests locally.

To employ GitLab CI, all we require is an application’s code hosted in a GitLab repository, and a file named gitlab-ci.yml, located in the root path of our repository, This must be outlined for our build, test, and deployment scripts.

Pre-requisites to run test on GitLab locally

  • Create GitLab Account and Log In to GitLab
  • Automation Project (Java-based automation project used in this article)
  • GitLab Runner
  • Understanding of maven lifecycle
  • GitLab CI pipeline file (gitlab-ci.yml)

Project Creation on GitLab to run Test Locally

Follow the below steps to create a project in GitLab.

  1. Log in to GitLab using your credentials.
  2. Click New Project on the landing dashboardgitlab new project
  3. Validate New project screen gets displayed. Select Create a blank project. You will be navigated to a new screen, which needs the following inputs 
    • Project Name – Add the project name (For example my_gitlab_ci_project)
    • Project Description (Optional) – Add appropriate description for reference 
    • Visibility Level – Select the Visibility Level for the project. 
  4. Opt the Initialize repository with a README option, this creates a README file so that the Git repository is initialised and has a default branch that can be cloned.blank project
  5. Click Create project.
  6. Now clone the project on local.

sample local project

  • Add the automation files and push the changes. 

# Clone the project

git clone <project_clone_with_https_link>

# Navigate to the repository

cd <project_name> 

# Add the automation project files

cp -R <automation_local_project> <project_name>  

# Push the changes to gitlab, ensure you are in git repo

git add .  # add all files

git commit -m “adding local automation project”  # commit to git local stage environment

# Run this command post local testing 

git push origin master # push local stage changes to gitlab server

  • Check all the files are available in the GitLab repository.

How to execute Local Tests using GitLab Runner

  • Ensure a runner is available in GitLab to run the jobs. If there is no runner, install GitLab Runner and register a runner for the project.
  • We can follow the below steps to install GitLab Runner Locally and register gitlab-runner by URL and token. Let’s mention the local testing and project description. This will display in our Settings > CI / CD > Runners tab.

Runners tab to run GitLab CI

# Download the binary for the system 

# macOS amd64

sudo curl --output /usr/local/bin/gitlab-runner ""

# macOS Apple Silicon/arm64

sudo curl --output /usr/local/bin/gitlab-runner ""

# provide root permission and execute

sudo chmod +x /usr/local/bin/gitlab-runner

# Register a gitlab runner

gitlab-runner register

  • You must also select the executor type (GitLab provides a few executor types for runners. For example – shell, docker)
  • To view the available runners go to Settings > CI/CD and expand Runners. As long as you have at least one runner that is active, with a green circle close to it, you have a runner accessible to handle your jobs.
  • Define a .gitlab-ci.yml file at the root of the repository. gitlab-ci.yml file defines our CI/CD jobs.

Defining gitlab-ci.yml

We can outline the scripts that we require to execute in this gitlab-ci.yml file.

  • Define the include and cache dependencies.
  • Reap commands that we need to execute in sequence and the one’s in parallel
  • Define the path where we want to deploy the application
  • Decide if we wish to execute the scripts automatically or spark them manually.

The contents are gathered into jobs and run as a feature of a bigger pipeline. We can bunch numerous independent jobs into stages that execute in a characterized order.

When our gitlab-ci.yml configuration file has been added to our repository, GitLab can ascertain it and execute our scripts with the GitLab Runner app, which functions precisely like our terminal and predominantly helps us reproduce production- alike scripts.

A sample gitlab-ci.yml looks like 

# Adding variables to set maven local environment


MAVEN_OPTS: -Dmaven.repo.local=.m2/repository

# Docker image to use latest maven distribution

image: maven:latest

# setting up maven lifecycle stages


  - build

  - test

  - package

  - deploy

# setting up cache paths 



    - .m2/repository

    - target


  stage: build


    - docker


    - echo “Maven compile started”

    - “mvn compile”


  stage: test


    - docker 


    - echo "Maven test started"

    - “mvn test”


  stage: package


    - docker


    - echo “Maven packaging started”

    - “mvn package”


  stage: deploy


    - docker


    - echo “Maven deploy started”

In the above gitlab-ci.yml build job will run the scripts under build_job then test_job will execute the test scripts under test_job and so on with the package and deploy stages.

Let’s explore shell executor

gitlab-runner exec shell test_job

Gitlab-runner exec is the command that helps us test locally. The exec command should be executed directly from the root directory because .gitlab-ci.yml will be kept in the root directory. While executing this, we need to specify the executor type (shell in this case)  and the name of the job( test_job).

The above command will clone our project from GitLab, install the dependencies and execute the tests.

Execute Selenium Tests in Gitlab CI locally using Browserstack

For the most recent documentation, visit here.

  1. Add BrowserStack Access Key as a variable in Variables under Settings -> CI/CD
  2. Set the variable name as BROWSERSTACK_ACCESS_KEY as Key. Please note that the variable name set in Key is used in the test scripts that we want to integrate with BrowserStack.
  3. Enter the value, which is our Access Key. The Access Key is present in the BrowserStack Automate dashboard.
  4. Repeat above step to add BROWSERSTACK_USERNAME as a variable.

Run GitLab test locally on BrowserStack

Now we need to update our test scripts with local environment BROWSERSTACK_LOCAL and environment identifier BROWSERSTACK_LOCAL_IDENTIFIER

String username = System.getenv("BROWSERSTACK_USERNAME");

String accessKey = System.getenv("BROWSERSTACK_ACCESS_KEY");

String browserstackLocal = System.getenv("BROWSERSTACK_LOCAL");

String browserstackLocalIdentifier = System.getenv("BROWSERSTACK_LOCAL_IDENTIFIER");

String buildName = System.getenv("BROWSERSTACK_BUILD_NAME");

DesiredCapabilities capabilities = new DesiredCapabilities();

capabilities.setCapability("os", "Windows");

capabilities.setCapability("browser", "chrome");

capabilities.setCapability("build", buildName);

capabilities.setCapability("browserstack.local", browserstackLocal);

capabilities.setCapability("browserstack.localIdentifier", browserstackLocalIdentifier);

driver = new RemoteWebDriver(new URL("https://" + username + ":" + accessKey + ""), capabilities);

You also need to configure our gitlab-ci.yml file to use the BrowserStack Local binary and route our tests through the local server

You can add pre-test steps to add the BrowserStack binary in our gitlab-ci.yml as shown below.


   # Download the browserstack binary file

   - wget ""

   #use the following command For OS X systems   

#- wget ""

   # Unzip the BrowserStack Local binary file

#For Windows systems use the following command

#- wget ""

#- powershell.exe D:\BrowserStackLocal.exe

   - unzip

   # Run the file with your access key

   - ./BrowserStackLocal --key $BROWSERSTACK_ACCESS_KEY --daemon start



         - <our_test_command>

         - ./BrowserStackLocal --key $BROWSERSTACK_ACCESS_KEY --daemon stop

Now you are familiar with how to execute local testing by rolling GitLab CI successfully. 

Sign up for BrowserStack and start automating your testing pipeline with GitLab CI/CD.

Start Testing on BrowserStack with GitLab CI for Free

Automation Testing CI CD Tools Testing Tools

Featured Articles

Difference between Jenkins vs Gitlab CI

How to run parallel tests with CircleCI

App & Browser Testing Made Easy

Seamlessly test across 20,000+ real devices with BrowserStack