Diagnosing CI Failures When Adding Algorithms to TheAlgorithms Repository

The Problem

You've implemented a new algorithm for TheAlgorithms repository, opened a pull request, and the GitHub Actions workflow fails. The log shows one of three common signals: Test file missing, AssertionError, or a linting error from flake8 (Python) or checkstyle (Java). This guide walks through diagnosing the exact cause and applying the minimal fix so the CI passes.

Recognizable Condition

The PR triggers a GitHub Actions run that ends with a red status. Typical log snippets include:

• No tests found for algorithm/your_algorithm.py
• AssertionError: expected 5 but got 4
• flake8: E302 expected 2 blank lines, found 1

These map directly to three root causes: missing test file, failing assertions, or style violations.

Cause and Diagnostic Table

Observed Failure	Likely Cause	Log Evidence
"No tests found" or "Test file missing"	Test file not present in the language directory	Workflow step "Run tests" exits with collected 0 items
AssertionError with expected/actual values	Test logic or test data does not match algorithm output	Stack trace points to a specific assert line in the test file
Linting errors (flake8, checkstyle, etc.)	Source code violates the language style guide	Lint step prints line numbers and rule codes (e.g., E302, W291)

Ordered Diagnostic Checks

Run these in sequence; stop when you identify the matching symptom.

1. Verify test file existence. In the repository root, confirm a test file exists under the same language folder with a name matching your algorithm (e.g., python/test_sorting/quick_sort_test.py for python/sorting/quick_sort.py).
2. Run the test suite locally. From the repo root, execute the language-specific test command. For Python:

   cd python
   python -m pytest test_sorting/quick_sort_test.py -v

   Requires pytest installed (pip install pytest). Watch for FAILED lines indicating assertion mismatches.
3. Run the project linter. For Python, run flake8 on the algorithm file:

   flake8 python/sorting/quick_sort.py

   For Java, run checkstyle with the project config:

   mvn checkstyle:check

   Install linters first (pip install flake8 or ensure Maven wrapper exists). Zero output means clean style.
4. Inspect the workflow logs. Open the failed GitHub Actions run, expand the failing job, and locate the exact error line. This confirms which of the three categories applies.

Fixes Tied to Findings

Missing Test File

Create a test file following the repository's naming convention. For a Python algorithm quick_sort.py, add test_sorting/quick_sort_test.py with at least one test case:

import pytest
from sorting.quick_sort import quick_sort

def test_quick_sort():
    assert quick_sort([3, 1, 2]) == [1, 2, 3]
    assert quick_sort([]) == []
    assert quick_sort([5]) == [5]

Commit and push; the CI test step should now collect and pass the new tests.

Failing Assertions

Examine the assertion error. Common issues:

• Algorithm bug: The implementation returns incorrect output. Fix the algorithm, not the test.
• Test data mismatch: The test expects a different return type (e.g., list vs. generator). Align the test with the documented API.
• Edge case omission: Add tests for empty input, single element, duplicates, and already-sorted data.

After correcting either the algorithm or the test, rerun the local test command (step 2) to verify before pushing.

Linting Errors

Apply the project's auto-formatter where available:

• Python: autopep8 --in-place --aggressive python/sorting/quick_sort.py then re-run flake8.
• Java: mvn com.coveo:fmt-maven-plugin:format (if configured) or run google-java-format manually.

If auto-fix doesn't resolve all warnings, address remaining lines manually (e.g., remove trailing whitespace, fix import order).

Escalation Criteria

Escalate to maintainers when:

• All three fixes above have been applied and the CI remains red.
• The failure is unrelated to tests or linting (e.g., docker pull timeout, missing secret, environment setup error).
• The workflow file itself appears misconfigured (wrong Python version, missing cache key).

Action: comment on the PR with the exact log excerpt and steps you've tried, then open an issue labeled ci-failure if the problem appears systemic.

Limitations and Verification

This guide assumes the repository continues to use GitHub Actions with the current workflow names (test.yml, lint.yml). A migration to GitLab CI or Azure Pipelines would change log locations and step names. Language-specific linters must be installed locally to replicate CI checks; missing tools produce false-negative verification.

Practical verification: After applying a fix, push a commit and watch the Actions tab. A green checkmark on the workflow run confirms the fix. For linting, a local flake8 (or checkstyle) clean run is a reliable proxy before pushing.