Skip to main content
Testing is critical to ensuring Terra packages work correctly across different systems and configurations. This guide covers local testing, CI/CD validation, and troubleshooting.

​
Why Testing Matters

Proper testing prevents:
  • Broken packages in the repository
  • Dependency conflicts
  • Runtime failures
  • Security vulnerabilities
  • Wasted maintainer time reviewing broken PRs
All packages must pass testing before they can be merged. Untested packages will be rejected.

​
Local Testing Workflow

​
Prerequisites

Ensure your testing environment is set up: 
# Install build tools
sudo dnf install anda mock rpm-build rpmdevtools

# Add yourself to mock group
sudo usermod -a -G mock $USER
newgrp mock

# Install Terra mock configs
sudo dnf install terra-mock-configs

​
Build Testing

1

Clean build test

Always test in a clean environment:
# Build with anda
anda build anda/category/package-name/pkg -c terra-frawhide-x86_64
This simulates the CI build environment.
2

Check build output

Verify the build completed successfully:
# List generated RPMs
ls -lh anda-build/rpm/rpms/x86_64/
ls -lh anda-build/rpm/srpm/
You should see:
  • Binary RPM(s) in rpms/x86_64/
  • Source RPM in srpm/
3

Inspect package contents

# List files in the package
rpm -qlp anda-build/rpm/rpms/x86_64/package-name-*.rpm

# Check package metadata
rpm -qip anda-build/rpm/rpms/x86_64/package-name-*.rpm

# Verify dependencies
rpm -qRp anda-build/rpm/rpms/x86_64/package-name-*.rpm
4

Run rpmlint

Check for packaging issues:
rpmlint anda-build/rpm/rpms/x86_64/package-name-*.rpm
rpmlint anda-build/rpm/srpm/package-name-*.src.rpm
Some rpmlint warnings are acceptable. Focus on errors and unexpected warnings.

​
Installation Testing

1

Install the package

sudo dnf install anda-build/rpm/rpms/x86_64/package-name-*.rpm
Watch for:
  • Dependency resolution issues
  • File conflicts
  • Scriptlet errors
2

Verify installation

# Check package is installed
rpm -q package-name

# List installed files
rpm -ql package-name

# Verify file ownership and permissions
rpm -V package-name
3

Test basic functionality

# Run the command
package-name --version
package-name --help

# Test core functionality
package-name test-command
4

Test upgrade path

If updating an existing package:
# Install old version first
sudo dnf install package-name-1.0.0

# Upgrade to new version
sudo dnf upgrade anda-build/rpm/rpms/x86_64/package-name-1.1.0*.rpm

# Verify upgrade succeeded
rpm -q package-name
package-name --version
5

Test removal

# Remove the package
sudo dnf remove package-name

# Verify complete removal
rpm -q package-name

# Check for leftover files (should be minimal)
find /usr /etc -name "*package-name*" 2>/dev/null

​
Multi-Architecture Testing

If you have access to multiple architectures: 
anda build anda/category/package/pkg -c terra-frawhide-x86_64
CI automatically tests both x86_64 and aarch64. Focus on x86_64 locally unless your package has architecture-specific code.

​
Automated CI Testing

When you submit a PR, GitHub Actions automatically runs:

​
Build Matrix Generation

The CI determines what changed: 
# From .github/workflows/autobuild.yml
- name: Generate build matrix
  id: generate_build_matrix
  run: anda ci >> $GITHUB_OUTPUT
This creates a matrix of:
  • Package(s) to build
  • Architectures (x86_64, aarch64)
  • Build labels (mock, large, etc.)

​
Package Building

Each package is built in an isolated container: 
container:
  image: ghcr.io/terrapkg/builder:frawhide
  options: --cap-add=SYS_ADMIN --privileged
Steps:
  1. Install build dependencies
  2. Build with anda
  3. Generate artifacts
  4. Upload RPMs

​
AppStream Generation

For GUI applications, AppStream metadata is generated: 
- name: Generate test catalog
  run: |
    appstream-builder -v \
      --packages-dir=artifacts/rpms \
      --icons-dir=icons \
      --include-failed \
      --output-dir=output
Check the CI summary for AppStream warnings about missing metadata in desktop applications.

​
Monitoring CI Builds

​
Viewing Build Status

  1. Go to your PR on GitHub
  2. Click the “Checks” tab
  3. View build progress for each job

​
Understanding CI Output

1

Manifest Job

Determines what to build:
{
  "pkg": "anda/tools/package/pkg",
  "arch": "x86_64",
  "labels": {"mock": "1"}
}
2

Build Jobs

One job per package + architecture:
  • Install Build Dependencies
  • Build with Andaman
  • Upload artifacts
  • Publish to repository (on push to frawhide)
3

AppStream Job

Validates GUI application metadata:
  • Extracts desktop files
  • Generates AppStream catalog
  • Reports vetoed packages

​
Common CI Failures

Cause: Missing or incorrect BuildRequiresFix:
# Add missing dependencies
BuildRequires:  missing-package-devel
Test locally:
sudo dnf builddep anda/category/package/*.spec
Cause: Source incompatibility, missing patches, wrong flagsFix:
  • Check upstream build instructions
  • Add necessary patches
  • Adjust build flags in %build section
Test locally with same container:
podman run --rm -it -v $PWD:/work ghcr.io/terrapkg/builder:frawhide bash
cd /work
dnf builddep -y anda/category/package/*.spec
rpmbuild -ba anda/category/package/*.spec
Cause: File path wrong or file not installedFix:
# Debug what was installed
%install
%make_install
find %{buildroot} -type f  # See what's actually there
Update %files to match actual paths.
Cause: Caching issues with incremental buildsFix: Disable sccache for this package:
project pkg {
  rpm {
    spec = "package.spec"
  }
  labels {
    sccache = 0
  }
}
Cause: Code not portable or missing arch-specific depsFix: Add architecture conditionals:
%ifarch x86_64
BuildRequires: x86-specific-dep
%endif

%ifarch aarch64  
BuildRequires: arm-specific-dep
%endif

​
Integration Testing

​
Testing with Dependent Packages

If your package is a library or dependency: 
# Install your package
sudo dnf install anda-build/rpm/rpms/x86_64/your-lib-*.rpm

# Install and test dependent package
sudo dnf install dependent-package
dependent-package --test

​
Testing in Clean Environment

Use a container or VM: 
# Test in Fedora container
podman run -it --rm -v $PWD:/packages fedora:rawhide bash

# Inside container
dnf install -y /packages/anda-build/rpm/rpms/x86_64/package-*.rpm
package-name --version
Or use systemd-nspawn: 
# Create minimal Fedora root
sudo dnf -y --releasever=rawhide --installroot=/var/lib/machines/test-fedora install systemd dnf

# Boot into it
sudo systemd-nspawn -D /var/lib/machines/test-fedora

# Test package inside

​
Performance Testing

​
Build Performance

Monitor build times: 
# Time the build
time anda build anda/category/package/pkg -c terra-frawhide-x86_64
For large packages, consider:
  • Enabling parallel builds (-j%{?_smp_mflags})
  • Using faster linkers (mold for Rust/C++)
  • Adding large = 1 label for bigger runners

​
Runtime Performance

Benchmark critical operations: 
# Example: test command performance
time package-name benchmark-command

# Compare with upstream builds
./upstream-binary benchmark-command
package-name benchmark-command

​
Security Testing

​
Check Binary Security Features

# Check for security hardening
checksec --file=/usr/bin/package-name

# Should show:
# RELRO: Full RELRO
# Stack: Canary found
# NX: NX enabled  
# PIE: PIE enabled

​
Scan for Vulnerabilities

# Scan with rpm-inspector
rpm-inspector anda-build/rpm/rpms/x86_64/package-*.rpm

# Check dependencies for known issues
rpm -qR package-name | while read dep; do
  dnf info "$dep" 2>/dev/null | grep -i security
done

​
Regression Testing

When updating packages:
1

Document current behavior

Before updating, note:
  • Current version and features
  • Known working use cases
  • Configuration files and formats
2

Test upgrade path

# Install current version from Terra
sudo dnf install package-name

# Note version
rpm -q package-name

# Upgrade to new build
sudo dnf upgrade anda-build/rpm/rpms/x86_64/package-*.rpm

# Test same use cases
3

Verify no regressions

  • All previous functionality still works
  • Configuration migrates correctly
  • No new warnings or errors
  • Performance hasn’t degraded

​
Testing Checklist

Before submitting your PR:

​
Build Tests

  • Package builds successfully on x86_64
  • Package builds successfully on aarch64 (or CI passes)
  • No rpmlint errors (warnings reviewed)
  • All files have correct paths and permissions
  • Source RPM can be rebuilt

​
Installation Tests

  • Package installs without errors
  • All dependencies resolve correctly
  • No file conflicts with other packages
  • Scriptlets execute successfully

​
Functionality Tests

  • Main program/library works as expected
  • Help/version commands work (CLI tools)
  • GUI launches without errors (GUI apps)
  • Services start and run correctly (daemons)
  • Configuration files load properly

​
Integration Tests

  • Upgrades from previous version work
  • Removal cleans up correctly
  • Dependent packages still work (if library)
  • No regressions from previous behavior

​
Documentation Tests

  • Man pages display correctly (if included)
  • README and docs are readable
  • License files are present
  • Changelog is updated

​
Manual Test Report Template

Include in your PR description: 
## Test Results

### Build Environment
- Fedora version: rawhide
- Architecture: x86_64
- anda version: X.Y.Z

### Build Status
- [x] Clean build successful
- [x] rpmlint warnings reviewed
- [x] All files packaged correctly

### Installation Testing
- [x] Fresh install successful  
- [x] Upgrade from version X.Y works
- [x] Removal clean

### Functionality Testing
- [x] `package-name --version` works
- [x] Basic usage: [describe what you tested]
- [x] Advanced usage: [describe what you tested]

### Notes
- Any warnings or issues observed
- Workarounds applied
- Known limitations

​
Debugging Failed Tests

​
Enable Verbose Output

# Build with verbose output
anda build anda/category/package/pkg -c terra-frawhide-x86_64 --verbose

# Or for spec file debugging
rpmbuild -ba --verbose anda/category/package/*.spec

​
Interactive Build Debugging

# Enter build container
podman run -it --rm -v $PWD:/work ghcr.io/terrapkg/builder:frawhide bash

cd /work/anda/category/package

# Install deps
dnf builddep -y *.spec

# Try build steps manually
rpmbuild -bp *.spec  # Just %prep
rpmbuild -bc *.spec  # %prep and %build
rpmbuild -bi *.spec  # Through %install

​
Check Build Logs

# Mock build logs are in
ls -la /var/lib/mock/terra-frawhide-x86_64/result/

# View build log
less /var/lib/mock/terra-frawhide-x86_64/result/build.log

# Check root log for dnf issues  
less /var/lib/mock/terra-frawhide-x86_64/result/root.log

​
Getting Help with Testing

If you encounter testing issues:
  1. Check similar packages - See how similar packages are tested
  2. Review CI logs - Often contain helpful error messages
  3. Ask in community chat - Join our chats
  4. Search issues - Someone may have had the same problem

​
Next Steps

Package Guidelines

Review packaging best practices

Getting Started

Back to contribution basics

Build docs developers (and LLMs) love

Get started for freeTalk to us