canonical / canonical/testflinger

docs: some tutorial issues

Open
#661 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.