Skip to content

Commit b642736

Browse files
claremacraeclaremacrae
authored
docs: Add developer docs to use GitHub builds and run smoke tests (#858)
* docs: Add docs on using a GitHub build of the plugin * chore: Turn on spell-checking in Tasks-Demo vault * chore: Pin the Tasks commands in Tasks-Demo vault * docs: Add "Smoke Testing the Tasks Plugin" in Tasks-Demo vault. * docs: Add "How do I smoke-test the Tasks plugin?" For background, see #826 and #854. * docs: Say how to open Tasks-Demo vault for smoke tests * docs: Note importance name of smoke test file * docs: Prevent numbered steps being hidden in Reading view
1 parent 42a9ca5 commit b642736

File tree

4 files changed

+125
-1
lines changed

4 files changed

+125
-1
lines changed

‎CONTRIBUTING.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,19 @@ Toggle behavior:
127127

128128
Obsidian writes the changes to disk at its own pace.
129129

130+
### How do I test a GitHub build of the Tasks plugin?
131+
132+
1. Go to the [Verify Commit actions page](https://github.com/obsidian-tasks-group/obsidian-tasks/actions/workflows/verify.yml).
133+
2. Click on the build of the code version you want to test. For example, you might click on the build for a particular pull request, or the most recent build on `main`.
134+
3. In the Artifacts section at the bottom, click on **dist-verified** to download a build of the plugin.
135+
4. Expand the downloaded `dist-verified.zip` file
136+
5. Copy the files in the expanded folder to the `.obsidian/plugins/obsidian-tasks-plugin/` folder in your vault, over-writing the previous files.
137+
6. Restart Obsidian.
138+
139+
### How do I smoke-test the Tasks plugin?
140+
141+
Follow the steps in `resources/sample_vaults/Tasks-Demo/Manual Testing/Smoke Testing the Tasks Plugin.md`.
142+
130143
### How do I make a release?
131144

132145
1. Check out the `main` branch

‎resources/sample_vaults/Tasks-Demo/.obsidian/app.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,6 @@
44
"useTab": false,
55
"readableLineLength": false,
66
"newFileLocation": "current",
7-
"attachmentFolderPath": "./"
7+
"attachmentFolderPath": "./",
8+
"spellcheck": true
89
}

‎resources/sample_vaults/Tasks-Demo/.obsidian/command-palette.json

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"pinned": [
3+
"obsidian-tasks-plugin:edit-task",
4+
"obsidian-tasks-plugin:toggle-done"
5+
]
6+
}

‎resources/sample_vaults/Tasks-Demo/Manual Testing/Smoke Testing the Tasks Plugin.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Smoke Testing the Tasks Plugin
2+
3+
## Introduction
4+
5+
- **Intended audience of this note**
6+
- Developers working on the Tasks plugin, reviewing a Pull Request (especially ones that change dependencies), or making a release, and who wish to do some basic tests of the plugin to make sure there are no glaring show-stopper errors.
7+
- **What is a Smoke Test?**
8+
- As [Wikipedia](https://en.wikipedia.org/wiki/Smoke_testing_(software)) says: smoke testing ... is preliminary testing to reveal simple failures severe enough to, for example, reject a prospective software release.
9+
- **Why not test everything?**
10+
- The Tasks plugin is run by volunteers in our finite spare time. We take care during development to write automated tests for the algorithms in our code, but there are some kinds of changes, such as in tools the project depends on, that we do not have automated tests for.
11+
- **Why not test on every platform?**
12+
- It's not feasible nor a good use of limited volunteer time on a free tool.
13+
14+
## How the tests work
15+
16+
- Make sure you have the [obsidian-tasks repo](https://github.com/obsidian-tasks-group/obsidian-tasks)cloned and up-to-date on your machine.
17+
- Open the Tasks-Demo vault on a machine of your choice:
18+
- Open Obsidian
19+
- Click 'Open another vault' button
20+
- Click 'Open folder as vault' button
21+
- Navigate to `obsidian-tasks/resources/sample_vaults/Tasks-Demo`
22+
- Click 'Open'
23+
- Install the candidate build for the pull request or release inside the `Tasks-Demo` vault
24+
- See the [FAQs in the CONTRIBUTING page](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/CONTRIBUTING.md#faqs).
25+
- This note is a self-contained set of steps to check. You should check off tasks beginning `- [ ] check:` as you complete each section.
26+
27+
> [!Important]
28+
> Several task blocks in this file depend of the the file name being unchanged. Please don't rename the file before running the tests.
29+
30+
---
31+
32+
## Remaining tests
33+
34+
Work through all the tasks below, until zero tasks remain in this query:
35+
36+
> [!Todo] Remaining groups of tests
37+
>
38+
> ```tasks
39+
> not done
40+
> path includes Smoke Testing the Tasks Plugin
41+
> description includes **check**:
42+
>
43+
> short display
44+
> ```
45+
46+
---
47+
48+
## The Smoke Tests
49+
50+
### Completion of tasks
51+
52+
- [ ] #task Mark this task complete in **Source view** using **Tasks: Toggle task done** command
53+
- [ ] #task Mark this task complete by clicking on it in **Reading view**
54+
- [ ] #task Mark this task complete by clicking on it in **Live Preview**
55+
- [ ] #task **check**: Checked all above methods for **completing tasks** - and they worked
56+
57+
### Un-completion of tasks
58+
59+
- [x] #task Mark this task not complete in **Source view** using **Tasks: Toggle task done** command ✅ 2022-07-05
60+
- [x] #task Mark this task not complete by clicking on it in **Reading view** ✅ 2022-07-05
61+
- [x] #task Mark this task not complete by clicking on it in **Live Preview** ✅ 2022-07-05
62+
- [ ] #task **check**: Checked all above methods for **un-completing tasks** - and they worked
63+
64+
### Recurring Tasks
65+
66+
Confirm that when a recurring task is completed, a new task is created and all the date fields are incremented.
67+
68+
- [ ] #task Complete this recurring task in **Source view** using **Tasks: Toggle task done** command 🔁 every day 🛫 2022-02-17 ⏳ 2022-02-18 📅 2022-02-19
69+
- [ ] #task Complete this recurring task in **Reading view**🔁 every day 🛫 2022-02-17 ⏳ 2022-02-18 📅 2022-02-19
70+
- [ ] #task Complete this recurring task in **Live Preview**🔁 every day 🛫 2022-02-17 ⏳ 2022-02-18 📅 2022-02-19
71+
- [ ] #task **check**: Checked all above steps for **recurring tasks** worked
72+
73+
### Rendering of Task Blocks
74+
75+
Steps to do:
76+
77+
- [ ] #task View this file in **Reading view** and confirm that the tasks in this section are listed
78+
- [ ] #task View this file in **Live Preview** and confirm that the tasks in this section are listed
79+
- [ ] #task **check**: Checked all above steps for **viewing task blocks** worked
80+
81+
---
82+
83+
Tasks block to check - should list all the tasks in this section, regardless of state
84+
85+
```tasks
86+
path includes Smoke Testing the Tasks Plugin
87+
heading includes Rendering of Task Blocks
88+
```
89+
90+
---
91+
92+
### Create or edit Task modal
93+
94+
- This text should copied in to the task Description, after following steps below
95+
- [ ] #task Switch to **Live Preview** or **Source mode**, Click on the list item above, then do the following numbered steps and checks:
96+
1. run **Tasks: Create or edit task**
97+
2. **Check** that the text in the list item is copied in to the Description field
98+
3. Type some values in to the fields
99+
4. In one of the date fields, type `tm` (including the space afterwards) and **Check** it is expanded in to `tomorrow`
100+
5. Hit Return or click **Apply**
101+
6. **Check** that the list item above is converted in to a task
102+
7. **Check** that values you entered in the modal have been copied in to the list item above
103+
8. **Check** that the `#task` tag has been added to the start of the task
104+
- [ ] #task **check**: Checked all above steps for **creating a task via the modal** worked

0 commit comments

Comments
 (0)