Testing Guidelines

Run tests, validate code quality, and ensure your changes work correctly across platforms

Nicotine+ uses comprehensive testing to ensure code quality and cross-platform compatibility. All changes must pass unit tests, integration tests, and code quality checks.

Continuous Integration

It is important that all changes pass unit and integration testing. Continuous integration (CI) is implemented using GitHub Actions workflows, which run tests on various platforms for each commit.

Although you can run tests locally, local testing should not be relied upon for changes that affect packaging or are likely to break on other platforms. GitHub Actions provides the authoritative test environment.

Running Tests Locally

Unit and Integration Tests

Run the test suite using Python’s unittest module:

python3 -m unittest

Tests are defined in the pynicotine/tests/ folder and should be expanded to cover larger parts of the client when possible.

Code Style Checks

Verify code follows style guidelines using pycodestyle:

python3 -m pycodestyle

Code Linting

Perform static code analysis using Pylint:

python3 -m pylint --recursive=y .

Build Testing

Test that the application builds correctly:

python3 -m build

Test Categories

Unit Tests

Unit tests verify individual components and functions in isolation.

Location: pynicotine/tests/

Run Command:

python3 -m unittest

Tests cover:

• Protocol message parsing
• Configuration management
• Data structure operations
• Utility functions

Integration Tests

Integration tests verify components work together correctly.

Included in: Standard unittest run

Tests cover:

• Component initialization
• Event system interactions
• Network message routing
• File transfer workflows

Code Quality

Automated checks ensure code quality and consistency.

Tools:

• pycodestyle - PEP 8 style compliance
• Pylint - Static analysis and linting

Commands:

python3 -m pycodestyle
python3 -m pylint --recursive=y .

Creating Tests

When adding new functionality or fixing bugs, expand the test coverage:

1. Identify test location

   Find or create the appropriate test file in pynicotine/tests/ that corresponds to your changes

2. Write test cases

   Create test methods that verify the expected behavior:

   import unittest
   
   class TestMyFeature(unittest.TestCase):
       def test_basic_functionality(self):
           # Arrange
           expected_result = "expected"
           
           # Act
           actual_result = my_function()
           
           # Assert
           self.assertEqual(actual_result, expected_result)
   
3. Run tests locally

   Verify your tests pass:

   python3 -m unittest
   
4. Push and verify CI

   Ensure GitHub Actions runs all tests successfully

Aim to cover both positive cases (expected behavior) and negative cases (error handling) in your tests.

Manual Testing Platforms

Before releases, maintainers ensure Nicotine+ works on these platforms:

• Windows - Latest version
• macOS - Latest version
• Ubuntu 18.04 - Oldest supported GTK 3 and Python 3 versions
• Ubuntu 22.04 - Oldest supported GTK 4 version
• Latest Ubuntu/Fedora - Current stable releases

You don’t need to test on all platforms for typical contributions, but be aware that CI tests across multiple operating systems and Python versions.

Testing Development Builds

Test your changes using various installation methods:

Git Development Build

The recommended method for active development:

1. Clone and navigate

   git clone https://github.com/nicotine-plus/nicotine-plus.git
   cd nicotine-plus
   
2. Make your changes

   Edit source files as needed

3. Run directly

   ./nicotine
   
4. Update and test again

   git pull
   ./nicotine
   

This method allows immediate testing of changes without reinstallation.

Pip Install from Git

Test installation from Git:

pip3 install git+https://github.com/nicotine-plus/nicotine-plus.git
nicotine

Update to latest:

pip3 install --upgrade git+https://github.com/nicotine-plus/nicotine-plus.git

Profiling and Performance Testing

Use py-spy for real-time performance profiling:

1. Install py-spy

   pip3 install py-spy
   
2. Run with profiling

   py-spy top ./nicotine
   
3. Analyze output

   • Press L to aggregate by line number
   • Press R to reset the view
   • Identify performance bottlenecks

Profiler output shows real-time CPU usage by function, helping identify performance issues before they become problems.

Debug Testing

Enable verbose debug logging during testing:

1. Show log pane

   Click the ellipsis icon in the bottom right corner of the main window

2. Enable log categories

   Right-click the log pane and select categories:

   • Connections - Network operations
   • Messages - Protocol messages
   • Transfers - File transfers
   • Miscellaneous - General debug messages
3. Log to file (optional)

   Menu -> Preferences -> Logging -> Log debug messages to file

Disable debug logging when not needed, as it impacts performance significantly.

Pre-Commit Checklist

Before committing changes, verify:

1. All tests pass

   python3 -m unittest
   
2. Code style is correct

   python3 -m pycodestyle
   
3. No linting errors

   python3 -m pylint --recursive=y .
   
4. Application runs

   ./nicotine
   

   Verify basic functionality works

Testing Translation Updates

When modifying translatable strings:

1. Update translation template

   python3 data/scripts/update_translation_template.py
   
2. Verify template

   Check po/nicotine.pot for new/modified strings

3. Test in different locales

   Run the application with different language settings if possible

Weblate handles translation updates automatically via pull requests. Use “Create a merge commit” when merging to preserve translator attribution.

Continuous Integration Details

GitHub Actions automatically runs:

• Unit tests on multiple Python versions
• Integration tests across Windows, macOS, and Linux
• Code style checks with pycodestyle
• Linting with Pylint
• Build tests to verify packaging
• Platform-specific installers for Windows and macOS

CI test results appear on pull requests and commits. All checks must pass before changes can be merged.

Unstable Build Testing

Test the latest unstable builds across platforms:

GNU/Linux

Ubuntu/Debian PPA

sudo add-apt-repository ppa:nicotine-team/unstable
sudo apt update && sudo apt install nicotine

Windows and macOS

Unstable installers are built automatically after each commit:

• Windows x64/ARM64 installers and portable packages
• macOS Intel/Apple Silicon installers

Download from the GitHub Actions artifacts.

Next Steps

• Review Development Overview for best practices
• Understand the Architecture for deeper insights
• Check Setup for dependency information