QA Testing

QA Testing Setup Instructions

Prerequisites

Before starting, ensure you have:

1. Arch Linux or Arch-based distribution (EndeavourOS, Manjaro, CachyOS, Artix)
2. System tools:
   • pacman (package manager)
   • paru or yay (AUR helper) — at least one required for AUR testing
   • sudo access (for password prompt tests)
3. Terminal emulator (at least one of: alacritty, kitty, ghostty, xterm, gnome-terminal, konsole, xfce4-terminal, tilix, mate-terminal)
4. Rust toolchain (stable)

Important Notes

• Always use --dry-run during initial testing to avoid system changes
• Test in a VM or isolated environment when possible
• For password-related tests, ensure you have sudo access configured
• Check the PR description or release notes for specific features being tested
• Report bugs with detailed logs and steps to reproduce

Step-by-Step Setup

Step 1: Install Rust toolchain

sudo pacman -S rustup
rustup default stable

Verify installation:

rustc --version
cargo --version

Step 2: Install build dependencies

sudo pacman -S --needed base-devel git

Step 3: Clone the repository

git clone https://github.com/Firstp1ck/Pacsea.git
cd Pacsea

Step 4: Check out the branch or version to test

If you need to test a specific branch:

git fetch origin
git checkout <branch-name>

To test the latest main branch:

git checkout main
git pull origin main

To test a specific release tag:

git fetch origin --tags
git checkout <tag-name>

Verify you're on the correct branch/tag:

git branch --show-current
# or for tags:
git describe --tags

Step 5: Verify AUR helper availability

Check if you have an AUR helper installed:

which paru || which yay

If neither is found, install one (required for AUR testing):

# For paru:
git clone https://aur.archlinux.org/paru.git
cd paru && makepkg -si && cd ..

# OR for yay:
git clone https://aur.archlinux.org/yay.git
cd yay && makepkg -si && cd ..

Step 6: Build the project

cargo build --release

This may take several minutes on first build. Subsequent builds will be faster.

Step 7: Verify the build

Run a quick check to ensure everything compiles:

cargo check

Step 8: Run tests (optional, but recommended)

Before testing manually, verify the test suite passes:

cargo test -- --test-threads=1

Note: Some tests are marked as ignored (e.g., password validation tests). To run those:

cargo test -- --ignored --test-threads=1

Step 9: Run the application

Recommended for initial testing (dry-run mode):

cargo run -- --dry-run

For actual testing (will execute commands):

cargo run --release

Or use the built binary directly:

./target/release/pacsea

With debug logging (useful for troubleshooting):

RUST_LOG=pacsea=debug cargo run -- --dry-run

Or with verbose flag:

cargo run -- --dry-run --verbose

Testing Environment Recommendations

1. Use a VM or test system to avoid affecting your main system
2. Start with --dry-run to verify behavior without making changes
3. Use a test user with sudo access for password prompt tests
4. Ensure network connectivity for package operations

Quick Verification Checklist

Before starting QA testing, verify:

• Rust toolchain installed (rustc --version works)
• Repository cloned and on the correct branch/tag
• Project builds successfully (cargo build --release completes)
• Tests pass (cargo test -- --test-threads=1 passes)
• pacman is available (which pacman)
• AUR helper is available (which paru or which yay)
• Terminal emulator is installed (at least one from the list)
• Sudo access works (sudo -v succeeds)

Testing Reference

If available, use the testing checklist at:

dev/PR/TESTING_CHECKLIST.md

Common testing areas include:

• Package installation/removal flows
• Preflight modal workflows
• Password prompt behavior
• Security scan flows
• System update flows
• Error handling
• Edge cases
• BlackArch (if [blackarch] is configured): After cargo run -- --dry-run, confirm the official index loads without errors; search for a known BlackArch package (e.g. a tool you know is only in BlackArch); verify the BlackArch label on rows; confirm the [BlackArch] chip appears in the Results title bar and toggles visibility on click; open Preflight for an install that pulls BlackArch deps and check badge coloring. On a system without BlackArch, confirm there is no chip and behavior matches mainline Arch/EOS/CachyOS expectations.
• Custom repos (repos.conf / Options → Repositories, Linux): Prefer a VM. With --dry-run, open Repositories, toggle Space on a managed row, verify the printed apply plan; confirm all-disabled apply still produces a safe comment-only drop-in message in the plan text. On a throwaway system, run a real apply, then confirm post-apply overlap wizard only after the log completes; exercise Esc/q on step 0 vs migration path. Queue a mixed official+AUR install and confirm helper invocations use -S --aur for the AUR-only segment. See How to use Pacsea — Custom repositories.
• Privilege setup assistants (sudo_timestamp_setup, doas_persist_setup): From Optional Deps, open both helpers and verify modal flow, key navigation, and instruction rendering. Confirm sudo helper shows timeout preset variants and safe visudo/permission steps; confirm doas helper presents persist-policy snippets plus checklist/validation hints. In --dry-run, verify no unintended privileged mutations execute.
• Long-run auth readiness warnings: Trigger install/update/remove/downgrade paths with auth settings that may expire credentials; verify warning appears once per continuation path, text is clear, and continue/cancel behavior is correct.
• Security baseline checks: Run ./dev/scripts/security-check.sh locally and confirm no high/critical blockers before final QA sign-off.

For specific feature testing, check for PR documentation files in dev/PR/ directory.

Configuration startup repair (optional)

When testing branches that touch theme or settings loading:

1. Backup ~/.config/pacsea/ (or use a throwaway user / HOME in a test environment).
2. Partial theme.conf: Replace theme.conf with a minimal file (for example one valid line like base = #111111), start Pacsea, confirm the TUI loads. Inspect theme.conf afterward—missing palette keys should be appended (see Configuration).
3. Empty theme.conf: Truncate theme.conf to zero bytes or delete it; on next start, Pacsea should recreate a full default skeleton.
4. --dry-run: Config files may still be updated on startup; use a copy of your config dir if you must not touch production files.

Troubleshooting

Build fails:

• Ensure Rust stable is installed: rustup default stable
• Update Rust: rustup update stable
• Clean and rebuild: cargo clean && cargo build --release

Tests fail:

• Run with single thread: cargo test -- --test-threads=1
• Some tests require specific system state; check test output for details

Application won't start:

• Check terminal emulator availability
• Verify pacman is in PATH
• Run with debug logging: RUST_LOG=pacsea=debug cargo run
• If the log mentions theme or config parse errors, open ~/.config/pacsea/theme.conf and fix reported lines (duplicates, invalid colors). For expected auto-repair behavior, see Configuration and Troubleshooting

AUR operations don't work:

• Verify paru or yay is installed and in PATH
• Test AUR helper directly: paru -S --help or yay -S --help

Next Steps

1. Review any available PR documentation in dev/PR/ for feature details
2. Review dev/PR/TESTING_CHECKLIST.md for test scenarios (if available)
3. Start with dry-run mode: cargo run -- --dry-run
4. Follow the testing checklist systematically
5. Report issues with logs: RUST_LOG=pacsea=debug cargo run -- --dry-run > test.log 2>&1

You're ready to start QA testing.