feat(cli): add job status information to queue-status command

[gajeshbhat]

Description

This PR enhances the existing queue-status command to display job status information alongside the current agent status, addressing the feature request in issue #116.

Users need a way to get a summary of job statuses in a queue without polling individual job IDs. When running many jobs in sequence, it's difficult to get a quick overview of job progress and identify active work.

The solution extends the existing queue-status command to show both agent and job status in unified output, using a simple --verbose flag for detailed job information.

Resolved issues

Fixes #116

Documentation

• Tutorial updated to include queue-status command in CLI help example
• Command help text clearly describes all options and functionality
• Existing documentation patterns and usage remain valid

Web service API changes

No API changes required. Uses existing endpoints:

• /v1/queues/{queue}/agents for agent status information
• /v1/queues/{queue}/jobs for job status information

Tests

How this PR was tested:

1. Unit Tests (50/50 passing):

   uv run python -m pytest testflinger_cli/tests/test_cli.py -v

2. Linting & Formatting:

   uvx --with tox-uv tox -e lint

3. Manual Testing:

   # Test basic functionality
   testflinger-cli queue-status my-queue
   
   # Test verbose mode  
   testflinger-cli queue-status --verbose my-queue
   
   # Test JSON output
   testflinger-cli queue-status --json my-queue

Test coverage includes:

• Default output with enhanced job counts
• Verbose mode showing individual job details with timestamps
• JSON output with new job status keys
• Error handling for empty/nonexistent queues
• Backward compatibility validation

Key features implemented:

• Non-breaking: Existing behavior completely preserved
• Unified output: Always shows both agent and job status together
• Simple interface: Single --verbose flag for detailed information
• Smart categorization: Jobs grouped as waiting/running/completed (cancelled ignored)
• JSON compatibility: New keys added while maintaining backward compatibility

Example outputs:

Default (enhanced):

Agents in queue: 1
Available:       1
Busy:            0
Offline:         0
Jobs waiting:    0
Jobs running:    0    # new
Jobs completed:  2    # new

Verbose (new):

Agents in queue: 1
Available:       1
Busy:            0
Offline:         0
Jobs waiting:    1
Jobs running:    0
Jobs completed:  2

Waiting:
  de153d8f-7d32-47d7-9a05-a20f2ef6bb35 - 2023-10-13 15:22:46

Completed:
  8b0bb52f-08d8-4671-b275-55d84a965f7c - 2023-10-13 15:22:30

This implementation addresses the core need from issue #116 while maintaining full compatibility with existing usage and following established project patterns, and also helps the project close #CERTTF-248 internally.

[rene-oromtz]

Hi @gajeshbhat
Thanks again for taking the time to add enhancements to this repo.
I added few suggestions based on current behavior of this command, since we are already returning jobs that are "waiting" in both json/human readable format we can extend the functionality with your proposed --verbose to include all other statuses.

Based on the enhancement request, for the human readable output, I will probably just leave it as follows to preserve the current output:

testflinger-cli queue-status <agent>
Agents in queue: 1
Available:       1
Busy:            0
Offline:         0
Jobs waiting:    0
Jobs running:    0 # new
Jobs completed:    0 # new

The json can output can also include this two new keys (jobs_running, jobs_completed) with additional timestamp information for each job.

Please let me know what you think, if you have any question regarding my comments, don't hesitate to ask!

[gajeshbhat]

Hi @gajeshbhat Thanks again for taking the time to add enhancements to this repo. I added few suggestions based on current behavior of this command, since we are already returning jobs that are "waiting" in both json/human readable format we can extend the functionality with your proposed --verbose to include all other statuses.

Based on the enhancement request, for the human readable output, I will probably just leave it as follows to preserve the current output:

testflinger-cli queue-status <agent>
Agents in queue: 1
Available:       1
Busy:            0
Offline:         0
Jobs waiting:    0
Jobs running:    0 # new
Jobs completed:    0 # new

The json can output can also include this two new keys (jobs_running, jobs_completed) with additional timestamp information for each job.

Please let me know what you think, if you have any question regarding my comments, don't hesitate to ask!

Hello @rene-oromtz, Thanks for the detailed feedback! I've replied to your comments and made some changes:

Changes Made:

• Removed --jobs and --show-completed flags - only --verbose remains
• Restructured code exactly as suggested - helper functions return data, main formats
• Extended existing output format with "Jobs running: 0" and "Jobs completed: 0"
• Simplified job categorization (waiting/complete/running, ignore cancelled)
• Added JSON keys jobs_running, jobs_completed with timestamps
• Renamed functions to _get_agents_status() and _get_jobs_status()

Please let me know if you have any questions. Cheers.

[rene-oromtz]

Thanks for adding the suggestions! Overall I'm liking the current approach, I just leave couple more suggestions and one important consideration regarding on the current MongoDB structure

[codecov]

Codecov Report

❌ Patch coverage is 85.00000% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.49%. Comparing base (3e0822e) to head (48ca14c).
⚠️ Report is 54 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #774      +/-   ##
==========================================
+ Coverage   63.70%   64.49%   +0.79%     
==========================================
  Files          94       94              
  Lines        7772     7946     +174     
  Branches      746      764      +18     
==========================================
+ Hits         4951     5125     +174     
+ Misses       2680     2673       -7     
- Partials      141      148       +7     

Flag	Coverage Δ		*Carryforward flag
agent	69.49% <ø> (ø)		Carriedforward from 3e0822e
cli	80.55% <85.00%> (+2.14%)	⬆️
device	51.47% <ø> (ø)		Carriedforward from 3e0822e
server	84.80% <ø> (ø)		Carriedforward from 3e0822e

*This pull request uses carry forward flags. Click here to find out more.

Components	Coverage Δ
Agent	69.49% <ø> (ø)
CLI	80.55% <85.00%> (+2.14%)	⬆️
Common	∅ <ø> (∅)
Device Connectors	51.47% <ø> (ø)
Server	84.80% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gajeshbhat]

Thanks for adding the suggestions! Overall I'm liking the current approach, I just leave couple more suggestions and one important consideration regarding on the current MongoDB structure

Thank you @rene-oromtz for taking the time to look into this again. I have made the requested changes and requested re-review. Please let me know if you have any questions.

[rene-oromtz]

Thanks again for the changes!
Just added final nitpicks/suggestions that I didn't catch before (sorry for that, this are the final comments I have). Functionally, the code looks good to me!
Tested locally as well and its working as expected

[gajeshbhat]

Thanks again for the changes! Just added final nitpicks/suggestions that I didn't catch before (sorry for that, these are the final comments I have). Functionally, the code looks good to me! Tested locally as well, and it's working as expected

Thanks again for taking a look at this @rene-oromtz .I have updated the changes you asked for. I just wanted to let you know that there's no need to be sorry. I am happy to always work with the maintainers to make sure my code submission meets the repository standards and does not introduce more technical debt. Please let me know if you have any further questions. Cheers. :)

On a side note, I have also put up a PR for a bug that troubled me a lot in the past while running testflinger in production when agents crash due to intermittent network issues. I believe this bugfix would help many teams running TestFlinger. No rush/urgency on this. Take a look when you have free time. Cheers.

[rene-oromtz]

@gajeshbhat once again, thanks for the time you put on this PR, this looks good to me!