Skip to main content
Mapagam

Managing Artifacts and Test Results

1. Storing Build Artifacts

Property Description Example
artifacts Defines where and how to store build artifacts 
artifacts:
  paths:
    - /tmp/artifacts
paths List of directories or files to store as artifacts 
artifacts:
  paths:
    - coverage.xml
    - logs/
destination Optional subdirectory in the artifact store 
artifacts:
  paths:
    - build/
  destination: builds/

Example: Store Build Artifacts

jobs:
  build:
    steps:
      - run: |
          mkdir -p artifacts
          echo "Build completed" > artifacts/build.log
      - store_artifacts:
          path: artifacts
Note: Artifacts are stored for 30 days by default in CircleCI.

2. Specifying Artifact Paths

Path Description Notes
artifacts Directory to store artifacts Default is ~/circleci-artifacts
paths List of paths to save as artifacts Can include wildcards like **/*.log

Example: Saving Test Results

workflows:
  version: 2
  build_and_test:
    jobs:
      - build
      - test:
          requires:
            - build
          artifacts:
            paths:
              - ./test-results/
              - ./logs/

3. Setting Artifact Destinations

Destination Description Configuration Notes
local Stores artifacts on the local runner store_artifacts: Default storage for artifacts
S3 Stores artifacts on Amazon S3 store_artifacts: Requires AWS credentials
GCS Stores artifacts on Google Cloud Storage store_artifacts: Requires GCP credentials
Azure Blob Storage Stores artifacts on Azure Blob Storage store_artifacts: Requires Azure credentials
Artifactory Stores artifacts on JFrog Artifactory store_artifacts: Requires Artifactory credentials

Example: Store Artifacts to Local Storage

jobs:
  build:
    steps:
      - run:
          name: Build Artifacts
          command: |
            mkdir -p dist
            cp -r src dist/
      - store_artifacts:
          path: dist

Example: Store Artifacts to S3

jobs:
  build:
    steps:
      - run:
          name: Build Artifacts
          command: |
            mkdir -p dist
            cp -r src dist/
      - store_artifacts:
          path: dist
          destination: s3://my-bucket/artifacts/

4. Accessing Artifacts via UI

Steps to Access Artifacts in CircleCI UI

  1. Go to the CircleCI Dashboard and select your project.
  2. Navigate to the Build you want to inspect.
  3. Click on the build number to open the build details page.
  4. In the left sidebar, click Artifacts.
  5. Artifacts are listed with their file names and sizes.
  6. Click on any artifact to download or view its contents in the browser.
Artifact Type Description Access Method Notes
Build Artifacts Files generated during the build process (e.g., logs, reports) CircleCI UI Available for 30 days by default
Test Results JUnit or JUnit-compatible XML test reports CircleCI UI Can be viewed in the Test Results tab
Screenshots Visual snapshots from test runs (e.g., browser automation) CircleCI UI Stored as part of the build artifacts
Note: Artifacts are stored in the cloud and can be accessed by any team member with CircleCI access. Ensure proper permissions are set if sensitive data is included.

5. Downloading Artifacts via API

Field Description Example
artifact_id Unique identifier for the artifact 1234567890
job_id Job ID associated with the artifact 9876543210
project_slug Project identifier in the format owner/name circleci/repo

Example: Download Artifact via API

curl -H "Circle-Token: <TOKEN>" \
  https://circleci.com/api/v2/project/<PROJECT_SLUG>/artifact/<ARTIFACT_ID>
Note: You must have appropriate permissions to access the artifact. The Circle-Token must be a valid personal API token with read access.
Warning: Artifacts are only available for jobs that have completed successfully. Failed jobs do not generate artifacts.

6. Storing Test Results

Property Description Values Notes
store_test_results Configuration to store test results path/to/test-results Path where test results are stored
store_artifacts Configuration to store artifacts path/to/artifacts Path where artifacts are stored

Example: Storing Test Results

jobs:
  test:
    steps:
      - run:
          name: Run Tests
          command: npm test
      - store_test_results:
          path: test-results

Example: Storing Artifacts

jobs:
  build:
    steps:
      - run:
          name: Build Project
          command: npm run build
      - store_artifacts:
          path: dist

7. Using JUnit XML Format

Property Description Values Notes
junit Path to JUnit XML report file path/to/junit.xml Required for test result reporting
junit_file Name of JUnit XML file test-results.xml Default is TEST-*.xml
junit_path Directory path for JUnit XML files reports/junit Used to store test results

Example: Configuring JUnit XML Output

version: 2.1
jobs:
  test:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Run Tests with JUnit Output
          command: |
            npm test -- --reporter junit --outputFile reports/junit/test-results.xml
      - store_test_results:
          path: reports/junit
Note: CircleCI automatically parses JUnit XML files to provide detailed test result summaries in the UI.

8. Using Custom Test Reporters

Property Description Values
test_reporter Path to custom test reporter script ./custom-reporter.js
format Output format for test results junit, json, xml

Example: Custom Test Reporter Configuration

version: 2.1
jobs:
  test:
    docker:
      - image: circleci/node:18
    steps:
      - checkout
      - run:
          name: Run Tests with Custom Reporter
          command: npm test -- --reporter ./custom-reporter.js --reporter-options format=junit
Note: Custom test reporters must be compatible with the testing framework in use (e.g., Jest, Mocha).

9. Understanding Artifact Retention

Retention Policy Description Default Duration Notes
artifacts.retention Defines how long artifacts are kept before deletion 30 days Can be overridden per project
artifacts.retention.days Number of days to retain artifacts 30 Set to 0 to disable retention
artifacts.retention.count Maximum number of artifacts to keep 10 Applies to builds in descending order

Example: Setting Artifact Retention

workflows:
  version: 2
  build-and-test:
    jobs:
      - build
      - test

jobs:
  build:
    steps:
      - run:
          name: Build Artifact
          command: |
            mkdir -p build/
            echo "Build output" > build/output.txt
      - store_artifacts:
          path: build/
          destination: build/

  test:
    steps:
      - run:
          name: Run Tests
          command: |
            npm test
      - store_test_results:
          path: test-results/
Note: Artifact retention is managed at the project level in CircleCI. You can configure it via the CircleCI web UI or using the circleci CLI.
Warning: Setting artifacts.retention.days to 0 disables retention entirely, which may lead to storage limits being exceeded.

10. Optimizing Artifact Storage

Option Values Notes
store_artifacts path/to/artifacts Directory to store artifacts from the job
store_test_results path/to/test-results Directory to store test results from the job
paths artifacts/ Path to artifacts directory in the job

Example: Storing Artifacts

jobs:
  build:
    steps:
      - run:
          name: Build Artifacts
          command: |
            mkdir -p artifacts/
            echo "Build successful" > artifacts/build.log
      - store_artifacts:
          path: artifacts/

Example: Storing Test Results

jobs:
  test:
    steps:
      - run:
          name: Run Tests
          command: |
            mkdir -p test-results/
            python -m pytest --junitxml=test-results/results.xml
      - store_test_results:
          path: test-results/
Note: Artifacts are stored for 30 days by default in CircleCI.
Warning: Large artifact sizes can slow down job execution and increase costs.
Storage Optimization Description Best Practice
artifact compression Compressing artifacts before storage Use gzip or similar tools to reduce size
artifact filtering Only storing necessary files Exclude logs, temporary files, or build artifacts not needed for later jobs
artifact retention Setting custom retention policies Use CircleCI's store_artifacts with destination to define custom paths and lifecycle rules

Was this article helpful?

Related Cheat Sheets