Maeris logo
Sign In

Setup CI/CD with CircleCI

Integrate Maeris test automation into your CircleCI CI/CD pipeline to run tests automatically on code commits, pull requests, and deployments. This ensures continuous quality validation throughout your development workflow.

CircleCI Integration Overview

The CircleCI integration allows you to execute Maeris tests as part of your continuous integration and deployment pipeline. Tests run automatically when code is committed, merged, or deployed, providing immediate feedback on code quality.

Integration Benefits

  • Automated Testing: Run tests automatically on every commit or PR
  • Early Detection: Catch bugs before code reaches production
  • Deployment Gates: Prevent deployments if tests fail
  • Parallel Execution: Run tests in parallel with other CI jobs
  • Status Reporting: See test results directly in CircleCI
  • Fast Feedback: Get test results quickly in your development workflow

Setting Up CircleCI Integration

Step 1: Get Maeris API Credentials

Obtain API credentials from Maeris to authenticate CircleCI jobs.

  • Navigate to Platform Settings → API Keys
  • Generate a new API key for CI/CD
  • Copy the API key (you'll add it to CircleCI)
  • Note your Maeris organization/project ID

Step 2: Configure CircleCI Project

Set up your CircleCI project to run Maeris tests.

  1. Add your project to CircleCI
  2. Create or update .circleci/config.yml file
  3. Add Maeris API key as environment variable
  4. Configure test execution job

Step 3: Create CircleCI Configuration

Write the CircleCI config to execute Maeris tests.

Configure jobs, workflows, and test execution steps in config.yml

CircleCI Configuration

Basic Configuration Example

version: 2.1

jobs:
  run-maeris-tests:
    docker:
      - image: cimg/node:latest
    steps:
      - checkout
      - run:
          name: Run Maeris Tests
          command: |
            npm install -g @maeris/cli
            maeris run \
              --api-key $MAERIS_API_KEY \
              --project $MAERIS_PROJECT_ID \
              --suite smoke-tests

workflows:
  test:
    jobs:
      - run-maeris-tests

Environment Variables

  • MAERIS_API_KEY: Your Maeris API key (set in CircleCI project settings)
  • MAERIS_PROJECT_ID: Your Maeris project/organization ID
  • MAERIS_ENVIRONMENT: Target environment (optional)

Setting Environment Variables in CircleCI

  1. Go to CircleCI project settings
  2. Navigate to "Environment Variables"
  3. Add MAERIS_API_KEY with your API key value
  4. Add MAERIS_PROJECT_ID with your project ID
  5. Save the variables

Common Workflow Patterns

Pattern 1: Run Tests on Every Commit

Execute tests automatically on every code commit.

Useful for: Continuous validation, early bug detection

Pattern 2: Run Tests on Pull Requests

Execute tests when pull requests are created or updated.

Useful for: PR validation, preventing bad merges

Pattern 3: Run Tests Before Deployment

Execute tests as a deployment gate before production releases.

Useful for: Deployment safety, production readiness

Pattern 4: Parallel Test Execution

Run different test suites in parallel for faster feedback.

Useful for: Large test suites, faster CI times

Advanced Configuration

Conditional Test Execution

  • Run tests only when specific files change
  • Execute different test suites based on branch
  • Skip tests on certain commit messages
  • Run full regression on main branch, smoke tests on feature branches

Test Result Handling

  • Fail CI build if tests fail
  • Generate test reports and artifacts
  • Send notifications on test results
  • Update status checks in GitHub/GitLab

Performance Optimization

  • Cache test dependencies
  • Run tests in parallel jobs
  • Use test result caching to skip unchanged tests
  • Optimize test execution order

Using Maeris CLI in CircleCI

CLI Commands

Run specific test suite:

maeris run --suite smoke-tests

Run tests by tag:

maeris run --tag @regression

Run with specific environment:

maeris run --env staging

Best Practices

  • Start with Smoke Tests: Run quick smoke tests on every commit

    Fast feedback without slowing down CI

  • Use Parallel Execution: Run tests in parallel to reduce CI time

    Faster feedback for developers

  • Fail Fast: Configure CI to fail immediately on test failure

    Prevents bad code from progressing

  • Secure Credentials: Store API keys securely in CircleCI environment variables

    Never commit credentials to code

  • Optimize Test Selection: Run only relevant tests based on changes

    Reduces CI execution time

  • Monitor CI Performance: Track test execution times and optimize

    Keeps CI pipeline fast and efficient

Troubleshooting

Common Issues

  • Authentication Failures: Verify API key is correctly set in CircleCI
  • Test Timeouts: Increase timeout values or optimize test execution
  • Network Issues: Check network connectivity from CircleCI to Maeris
  • Configuration Errors: Verify CircleCI config.yml syntax and structure

Debugging Tips

  • Check CircleCI job logs for detailed error messages
  • Test Maeris CLI commands locally before adding to CI
  • Verify environment variables are set correctly
  • Review Maeris API documentation for command options

Next Steps

After setting up CircleCI integration: