Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/terrapkg/packages/llms.txt

Use this file to discover all available pages before exploring further.

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