canonical / canonical/testflinger
docs: some tutorial issues
- Dominant language
- Python
- Stars
- 26
- Forks
- 49
- Avg merge
- 4d 8h
- Merged PRs (30d)
- 16
Description
I ran into a few issues while going through the tutorial:
## Job yaml in /tmp
The tutorial says to save the file as `test-job.yaml`, so being a throwaway learning exercise, I put it in `/tmp/test-job.yaml`. But for some reason, testflinger doesn't like files in `/tmp`:
```
/tmp # $ testflinger-cli submit test-job.yaml
ERROR: 2025-04-30 14:41:42 __init__.py:531 -- [Errno 2] No such file or directory: 'test-job.yaml'
Traceback (most recent call last):
File "/snap/testflinger-cli/201/lib/python3.10/site-packages/testflinger_cli/__init__.py", line 527, in submit
data = self.args.filename.read_text(
File "/usr/lib/python3.10/pathlib.py", line 1134, in read_text
with self.open(mode='r', encoding=encoding, errors=errors) as f:
File "/usr/lib/python3.10/pathlib.py", line 1119, in open
return self._accessor.open(self, mode, buffering, encoding, errors,
FileNotFoundError: [Errno 2] No such file or directory: 'test-job.yaml'
```
Using an absolute path doesn't help:
```
/tmp # $ testflinger-cli submit /tmp/test-job.yaml
ERROR: 2025-04-30 14:42:43 __init__.py:531 -- [Errno 2] No such file or directory: '/tmp/test-job.yaml'
Traceback (most recent call last):
File "/snap/testflinger-cli/201/lib/python3.10/site-packages/testflinger_cli/__init__.py", line 527, in submit
data = self.args.filename.read_text(
File "/usr/lib/python3.10/pathlib.py", line 1134, in read_text
with self.open(mode='r', encoding=encoding, errors=errors) as f:
File "/usr/lib/python3.10/pathlib.py", line 1119, in open
return self._accessor.open(self, mode, buffering, encoding, errors,
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/test-job.yaml'
```
Moving the job file out of `/tmp` fixed it for me, but the tutorial might want to specify putting it in the user's home directory or something like that.
## No example queue
Tutorial specifies `job_queue: example-queue-1` in the job yaml, but this queue does not exist in the Canonical server. Submitting the job results in:
```
ERROR: No online agents available for queue example-queue-1. If you want to wait for agents to become available, use the --wait-for-available-agents option.
```
Taking that advice, I tried the wait option. After realizing the job was in a perpetual wait, I checked the list of queues and realized there is no `example-queue-1`.
The tutorial should specify a queue that can actually accept jobs.
## `testflinger` vs `testflinger-cli`
It appears that one is just a symlink to the other, but the tutorial specifies both. I see `testflinger-cli` most places, but in the [check job status](https://canonical-testflinger.readthedocs-hosted.com/en/latest/tutorial/index.html#check-job-status) section, it uses `testflinger`.
---
*Reported from: https://canonical-testflinger.readthedocs-hosted.com/en/latest/tutorial/index.html*
Contributor guide
Research direction
Start with the linked tutorial, especially the job submission and check-job-status sections, and reproduce the documented testflinger-cli commands. Verify the /tmp behavior, the example queue, and the testflinger versus testflinger-cli naming against the available CLI behavior. Done means the tutorial uses a readable job-file location, a usable queue or accurate instructions, and one consistent command name.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100