Best Practices

This guide outlines recommended practices for getting the most out of TestPig.io in your testing workflow.

Environment Variables

Why Use Environment Variables?

Using environment variables for TestPig.io configuration offers several advantages:

1. Security: Keeps sensitive information like API keys out of your code and version control
2. Flexibility: Easily change configuration between environments without modifying code
3. CI/CD Integration: Seamless integration with all major CI/CD platforms
4. Consistency: Works across all reporters and testing frameworks

Recommended Implementation

Set up your environment variables before running tests:

export TESTPIG_PROJECT_ID=your-project-id
export TESTPIG_RUN_ID=your-run-id  # Optional
export TESTPIG_API_KEY=your-api-key

For Windows command prompt:

set TESTPIG_PROJECT_ID=your-project-id
set TESTPIG_RUN_ID=your-run-id  # Optional
set TESTPIG_API_KEY=your-api-key

For PowerShell:

$env:TESTPIG_PROJECT_ID="your-project-id"
$env:TESTPIG_RUN_ID="your-run-id"  # Optional
$env:TESTPIG_API_KEY="your-api-key"

Loading from .env Files

For local development, consider using .env files with a package like dotenv:

// In your test setup file
require('dotenv').config();

// Now process.env.TESTPIG_PROJECT_ID is available

caution

Never commit .env files to version control. Add them to your .gitignore.

Understanding Run IDs

To Set or Not to Set a Run ID

The TESTPIG_RUN_ID environment variable is optional and determines how your test results are organized:

• When you set a Run ID: All test results using that ID will be consolidated into a single test run in TestPig.io. This is useful for:

  • Aggregating results from different test frameworks (e.g., Jest and Cypress tests for the same feature)
  • Combining results from multiple CI jobs or parallel test runs
  • Creating a comprehensive view of all tests for a specific feature or release

• When you don't set a Run ID: TestPig.io will automatically create a new test run for each execution and use the git branch name as the Run ID (if available). This is beneficial for:

  • Keeping separate runs isolated (default behavior)
  • Automatic organization by git branch
  • Scenarios where you want each test execution to have its own distinct record

tip

If you're running multiple test suites that logically belong together (e.g., unit, integration, and E2E tests for the same feature), consider using the same Run ID for all of them to create a unified test report.

CI/CD Integration

GitHub Actions Example

name: Run Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test
        env:
          TESTPIG_PROJECT_ID: ${{ secrets.TESTPIG_PROJECT_ID }}
          TESTPIG_RUN_ID: ${{ github.ref_name }}
          TESTPIG_API_KEY: ${{ secrets.TESTPIG_API_KEY }}

GitLab CI Example

test:
  stage: test
  image: node:16
  script:
    - npm ci
    - npm test
  variables:
    TESTPIG_PROJECT_ID: ${TESTPIG_PROJECT_ID}
    TESTPIG_RUN_ID: ${CI_COMMIT_REF_NAME}
    TESTPIG_API_KEY: ${TESTPIG_API_KEY}

Jenkins Pipeline Example

pipeline {
    agent { docker { image 'node:16' } }
    environment {
        TESTPIG_PROJECT_ID = credentials('testpig-project-id')
        TESTPIG_RUN_ID = "${env.BRANCH_NAME}"
        TESTPIG_API_KEY = credentials('testpig-api-key')
    }
    stages {
        stage('Test') {
            steps {
                sh 'npm ci'
                sh 'npm test'
            }
        }
    }
}

Effective Run IDs

Strategic Run ID Naming

The TESTPIG_RUN_ID determines how your test results are grouped. Consider these strategies:

• Git branch name: Ideal for feature branch testing

  TESTPIG_RUN_ID=$(git rev-parse --abbrev-ref HEAD)

• Commit hash: Useful for pinpointing exact code versions

  TESTPIG_RUN_ID=$(git rev-parse --short HEAD)

• Build numbers: Great for CI/CD pipelines

  TESTPIG_RUN_ID="build-${BUILD_NUMBER}"

• Timestamp: Useful for scheduled runs

  TESTPIG_RUN_ID="run-$(date +%Y%m%d-%H%M%S)"

• Semantic versioning: Ideal for release testing

  TESTPIG_RUN_ID="v1.2.3-beta"

Run ID Best Practices

1. Be consistent: Use the same naming convention across all test types
2. Keep them meaningful: Run IDs should help you quickly identify the test context
3. Consider automation: Generate Run IDs programmatically when possible
4. Include environment: For multi-environment testing, include environment indicators

Reporter Configuration

Minimal Configuration

When using environment variables, keep reporter configurations clean:

// Jest configuration
module.exports = {
  reporters: ['default', '@testpig/jest-reporter']
};

// WebdriverIO configuration
exports.config = {
  reporters: [['@testpig/wdio-reporter']]
};

// Playwright configuration
export default defineConfig({
  reporter: ['@testpig/playwright-reporter']
});

Additional Reporter-Specific Options

For advanced scenarios where you need reporter-specific options:

// Jest with custom options
module.exports = {
  reporters: [
    'default',
    ['@testpig/jest-reporter', {
      // Only explicitly set options that differ from defaults
      includeConsoleOutput: true
    }]
  ]
};

Troubleshooting

Common Issues

1. Missing results: Verify your API key and project ID
2. Incomplete reporting: Check network connectivity during test runs
3. Authentication errors: Regenerate your API key
4. Duplicated data: Ensure unique run IDs for separate test runs

Logging

For debugging reporter issues, increase the log level:

export TESTPIG_LOG_LEVEL=debug

This will provide more detailed output about what the reporter is doing.

Security Considerations

1. Store API keys securely: Use your CI/CD platform's secrets management
2. Rotate keys periodically: Regularly update your API keys
3. Least privilege: Create separate API keys for different projects or teams
4. Review access: Periodically audit who has access to your TestPig.io account

By following these best practices, you'll ensure a smoother, more secure integration of TestPig.io into your testing workflow.