Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicotine-plus/nicotine-plus/llms.txt

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

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 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

​
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

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