CircleCI Integration Guide

This guide explains how to integrate the LoadFocus JMeter API Client with CircleCI for automated performance testing.

Setup Steps

1. Add Environment Variables

Store your LoadFocus API credentials as environment variables in CircleCI:

1. Navigate to your project in CircleCI
2. Go to Project Settings > Environment Variables
3. Add the following variables:
   • LOADFOCUS_API_KEY: Your LoadFocus API key
   • LOADFOCUS_TEAM_ID: Your LoadFocus team ID

2. Configure CircleCI Workflow

Create or update your .circleci/config.yml file to include performance testing:

version: 2.1
jobs:
  performance_test:
    docker:
      - image: cimg/node:16.13
    steps:
      - checkout
      - run:
          name: Install LoadFocus JMeter API Client
          command: npm install -g @loadfocus/loadfocus-api-client
      - run:
          name: Configure LoadFocus API Client
          command: |
            loadfocus-api config set apikey $LOADFOCUS_API_KEY
            loadfocus-api config set teamid $LOADFOCUS_TEAM_ID
      - run:
          name: Run Performance Tests
          command: |
            loadfocus-api jmeter run-test \
              --name "CircleCI_${CIRCLE_PROJECT_REPONAME}_${CIRCLE_BRANCH}" \
              --thresholds "avgresponse<=200,errors==0,p95<=250" \
              --format json > performance_results.json
      - store_artifacts:
          path: performance_results.json
          destination: performance-test-results

workflows:
  version: 2
  build_test_deploy:
    jobs:
      - build_and_test
      - performance_test:
          requires:
            - build_and_test
      - deploy:
          requires:
            - performance_test
          filters:
            branches:
              only: main

3. Fail the Build on Performance Issues

To make your pipeline fail when performance thresholds are not met, modify the "Run Performance Tests" step:

- run:
    name: Run Performance Tests
    command: |
      loadfocus-api jmeter run-test \
        --name "CircleCI_${CIRCLE_PROJECT_REPONAME}_${CIRCLE_BRANCH}" \
        --thresholds "avgresponse<=200,errors==0,p95<=250" \
        --format json > performance_results.json
      
      # Check exit code - the command will exit with code 1 if thresholds are not met
      if [ $? -ne 0 ]; then
        echo "Performance test failed to meet thresholds"
        exit 1
      fi

Advanced Configuration

Parallel Testing

For running multiple performance tests in parallel:

performance_tests:
  docker:
    - image: cimg/node:16.13
  parallelism: 3
  steps:
    - checkout
    - run:
        name: Install LoadFocus JMeter API Client
        command: npm install -g @loadfocus/loadfocus-api-client
    - run:
        name: Configure LoadFocus API Client
        command: |
          loadfocus-api config set apikey $LOADFOCUS_API_KEY
          loadfocus-api config set teamid $LOADFOCUS_TEAM_ID
    - run:
        name: Run Performance Tests
        command: |
          # Get test name based on index
          TESTS=("API_Test" "Frontend_Test" "Database_Test")
          INDEX=$(( $CIRCLE_NODE_INDEX % 3 ))
          TEST_NAME=${TESTS[$INDEX]}
          
          echo "Running test: $TEST_NAME"
          
          loadfocus-api jmeter run-test \
            --name "$TEST_NAME" \
            --thresholds "avgresponse<=200,errors==0,p95<=250" \
            --format json > "performance_results_${TEST_NAME}.json"
    - store_artifacts:
        path: performance_results_*.json
        destination: performance-test-results

Tips for CircleCI Integration

1. Resource Allocation: Ensure your CircleCI plan has sufficient resources for running performance tests, especially if they're long-running.

2. Timeout Settings: For longer tests, adjust the job timeout in CircleCI:

   - run:
       name: Run Performance Tests
       command: loadfocus-api jmeter run-test --name "Test_Name" --waitTimeout 3600
       no_output_timeout: 60m

3. Conditional Testing: Only run performance tests on specific branches or for specific commits:

   performance_test:
     # Only run if commit message contains [PERF-TEST]
     when:
       condition:
         or:
           - equal: [ main, << pipeline.git.branch >> ]
           - matches:
               pattern: ".*\\[PERF-TEST\\].*"
               value: << pipeline.git.commit.message >>

4. Notifications: Set up notifications for performance test failures:

   - run:
       name: Notify on Performance Test Failure
       command: |
         if [ $? -ne 0 ]; then
           curl -X POST -H "Content-Type: application/json" \
             -d '{"text":"Performance test failed for $CIRCLE_PROJECT_REPONAME"}' \
             $SLACK_WEBHOOK_URL
         fi
       when: on_fail

For more information, refer to the CircleCI documentation and the LoadFocus API Client documentation.