You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+17-4Lines changed: 17 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,10 @@ A short course on the basics of software testing in Python using the `pytest` li
4
4
5
5
This lesson uses [The Carpentries Workbench][workbench] template.
6
6
7
+
It is derived from the [FAIR2 for Research Software](https://fair2-for-research-software.github.io/)
8
+
training course [python-testing-for-research](https://github.com/FAIR2-for-research-software/python-testing-for-research)
9
+
by the University of Sheffield.
10
+
7
11
## Course Description
8
12
9
13
Whether you are a seasoned developer or just write the occasional script, it's important to know that your code does what you intend, and will continue to do so as you make changes.
@@ -18,7 +22,7 @@ This course seeks to provide you with conceptual understanding and the tools you
18
22
- Running a test suite & understanding outputs
19
23
- Best practices
20
24
- Testing for errors
21
-
- Testing data structures
25
+
- Testing floating point data
22
26
- Fixtures
23
27
- Parametrisation
24
28
- Testing file outputs
@@ -30,18 +34,27 @@ Contributions are welcome, please refer to the [contribution guidelines](CONTRIB
30
34
31
35
### Build the lesson locally
32
36
33
-
To render the lesson locally, you will need to have [R][r] installed. Instructions for using R with the Carpentries template is [available](https://carpentries.github.io/workbench/#installation) but some additional setps have been taken to make sure the enivronment is reproducible using the [`{renv}`](https://rstudio.github.io/renv/articles/renv.html) package and an `renv.lockfile` is included which allows the environment to be re-created along with dependencies.
37
+
To render the lesson locally, you will need to have [R][r] installed.
38
+
Instructions for using R with the Carpentries template is available on the
After cloning the repository, you can set up `renv` and install all packages with:
34
44
35
-
After cloning the repository, you can set up the `renv` and install all packages with:
36
45
```r
37
-
renv::restore()
46
+
renv::init()
38
47
# Optionally update packages
39
48
renv::update()
40
49
```
41
50
Once you have installed the dependencies, you can render the pages locally by starting R in the project root and running:
51
+
42
52
```r
43
53
sandpaper::serve()
44
54
```
55
+
56
+
When building the site subsequently, you may need to run `renv::activate()` first.
57
+
45
58
This will build the pages and start a local web-server in R and open it in your browser. These pages are "live" and will respond to local file changes if you save them.
Copy file name to clipboardExpand all lines: episodes/00-introduction.Rmd
+4-4Lines changed: 4 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,7 @@ exercises: 2
22
22
This course aims to equip researchers with the skills to write effective tests and ensure the quality and reliability of their research software. No prior testing experience is required! We'll guide you through the fundamentals of software testing using Python's Pytest framework, a powerful and beginner-friendly tool. You'll also learn how to integrate automated testing into your development workflow using continuous integration (CI). CI streamlines your process by automatically running tests with every code change, catching bugs early and saving you time. By the end of the course, you'll be able to write clear tests, leverage CI for efficient development, and ultimately strengthen the foundation of your scientific findings.
23
23
24
24
This course has a single continuous project that you will work on throughout the lessons and each lesson builds on the last through practicals that will help you apply the concepts you learn. However if you get stuck or fall behind during the course, don't worry!
25
-
All the stages of the project for each lesson are available in the `files` directory in this course's materials that you can copy across if needed. For example if you are on lesson 3 and haven't completed the practicals for lesson 2, you can copy the corresponding folder from the `files` directory.
25
+
All the stages of the project for each lesson are available in the `learners/files` directory in this [course's materials](https://github.com/researchcodingclub/python-testing-for-research) that you can copy across if needed. For example if you are on lesson 3 and haven't completed the practicals for lesson 2, you can copy the corresponding folder from the `learners/files` directory.
26
26
27
27
By the end of this course, you should:
28
28
@@ -72,9 +72,9 @@ This course uses blocks like the one below to indicate an exercise for you to at
72
72
73
73
::::::::::::::::::::::::::::::::::::: keypoints
74
74
75
-
- This course will teach you how to write effective tests and ensure the quality and reliability of your research software
76
-
- No prior testing experience is required
77
-
- You can catch up on practicals by copying the corresponding folder from the `files` directory of this course's materials
75
+
- This course will teach you how to write effective tests and ensure the quality and reliability of your research software.
76
+
- No prior testing experience is required.
77
+
- You can catch up on practicals by copying the corresponding folder from the `learners/files` directory of this [course's materials](https://github.com/researchcodingclub/python-testing-for-research).
Copy file name to clipboardExpand all lines: episodes/01-why-test-my-code.Rmd
+91-57Lines changed: 91 additions & 57 deletions
Original file line number
Diff line number
Diff line change
@@ -18,16 +18,22 @@ exercises: 2
18
18
19
19
## What is software testing?
20
20
21
-
Software testing is the process of checking that code is working as expected. You may have data processing functions or automations that you use in your work - how do you know that they are doing what you expect them to do?
21
+
Software testing is the process of checking that code is working as expected.
22
+
You may have data processing functions or automations that you use in your work.
23
+
How do you know that they are doing what you expect them to do?
22
24
23
-
Software testing is most commonly done by writing code (tests) that check that your code works as expected.
25
+
Software testing is most commonly done by writing test code that check that
26
+
your code works as expected.
24
27
25
-
This might seem like a lot of effort, so let's go over some of the reasons you might want to add tests to your project.
28
+
This might seem like a lot of effort, so let's go over some of the reasons you
29
+
might want to add tests to your project.
26
30
27
31
28
32
## Catching bugs
29
33
30
-
Whether you are writing the occasional script or developing a large software, mistakes are inevitable. Sometimes you don't even know when a mistake creeps into the code, and it gets published.
34
+
Whether you are writing the occasional script or developing a large software,
35
+
mistakes are inevitable. Sometimes you don't even know when a mistake creeps
36
+
into the code, and it gets published.
31
37
32
38
Consider the following function:
33
39
@@ -36,50 +42,63 @@ def add(a, b):
36
42
return a - b
37
43
```
38
44
39
-
When writing this function, I made a mistake. I accidentally wrote `a - b` instead of `a + b`. This is a simple mistake, but it could have serious consequences in a project.
45
+
When writing this function, I made a mistake. I accidentally wrote `a - b`
46
+
instead of `a + b`. This is a simple mistake, but it could have serious
47
+
consequences in a project.
40
48
41
-
When writing the code, I could have tested this function by manually trying it with different inputs and checking the output, but:
49
+
When writing the code, I could have tested this function by manually trying it
50
+
with different inputs and checking the output, but:
42
51
43
52
- This takes time.
44
53
- I might forget to test it again when we make changes to the code later on.
45
-
- Nobody else in my team knows if I tested it, or how I tested it, and therefore whether they can trust it.
54
+
- Nobody else in my team knows if I tested it, or how I tested it, and
55
+
therefore whether they can trust it.
46
56
47
57
This is where automated testing comes in.
48
58
49
59
## Automated testing
50
60
51
-
Automated testing is where we write code that checks that our code works as expected. Every time we make a change, we can run our tests to automatically make sure that our code still works as expected.
61
+
Automated testing is where we write code that checks that our code works as
62
+
expected. Every time we make a change, we can run our tests to automatically
63
+
make sure that our code still works as expected.
52
64
53
-
If we were writing a test from scratch for the `add` function, think for a moment on how we would do it.
54
-
We would need to write a function that runs the `add` function on a set of inputs, checking each case to ensure it does what we expect. Let's write a test for the `add` function and call it `test_add`:
65
+
If we were writing a test from scratch for the `add` function, think for a
66
+
moment on how we would do it.
67
+
68
+
We would need to write a function that runs the `add` function on a set of
69
+
inputs, checking each case to ensure it does what we expect. Let's write a test
70
+
for the `add` function and call it `test_add`:
55
71
56
72
```python
57
73
deftest_add():
58
-
# Check that it adds two positive integers
59
-
if add(1, 2) !=3:
60
-
print("Test failed!")
61
-
# Check that it adds zero
62
-
if add(5, 0) !=5:
63
-
print("Test failed!")
64
-
# Check that it adds two negative integers
65
-
if add(-1, -2) !=-3:
66
-
print("Test failed!")
74
+
# Check that it adds two positive integers
75
+
if add(1, 2) !=3:
76
+
print("Test failed!")
77
+
# Check that it adds zero
78
+
if add(5, 0) !=5:
79
+
print("Test failed!")
80
+
# Check that it adds two negative integers
81
+
if add(-1, -2) !=-3:
82
+
print("Test failed!")
67
83
```
68
84
69
-
Here we check that the function works for a set of test cases. We ensure that it works for positive numbers, negative numbers, and zero.
85
+
Here we check that the function works for a set of test cases. We ensure that
86
+
it works for positive numbers, negative numbers, and zero.
70
87
71
88
72
89
::::::::::::::::::::::::::::::::::::: challenge
73
90
74
-
## Challenge 1: What could go wrong?
91
+
## What could go wrong?
75
92
76
-
When writing functions, sometimes we don't anticipate all the ways that they could go wrong.
93
+
When writing functions, sometimes we don't anticipate all the ways that they
94
+
could go wrong.
77
95
78
-
Take a moment to think about what is wrong, or might go wrong with these functions:
96
+
Take a moment to think about what is wrong, or might go wrong with these
When a test fails, it can help us to find the root cause of a bug. For example, consider the following function:
153
+
When a test fails, it can help us to find the root cause of a bug. For example,
154
+
consider the following function:
133
155
134
156
```python
135
157
136
158
defmultiply(a, b):
137
-
return a * a
159
+
return a * a
138
160
139
161
defdivide(a, b):
140
-
return a / b
162
+
return a / b
141
163
142
164
deftriangle_area(base, height):
143
-
return divide(multiply(base, height), 2)
165
+
return divide(multiply(base, height), 2)
144
166
```
145
167
146
-
There is a bug in this code too, but since we have several functions calling each other, it is not immediately obvious where the bug is. Also, the bug is not likely to cause a crash, so we won't get a helpful error message telling us what went wrong. If a user happened to notice that there was an error, then we would have to check `triangle_area` to see if the formula we used is right, then `multiply`, and `divide` to see if they were working as expected too!
168
+
There is a bug in this code too, but since we have several functions calling
169
+
each other, it is not immediately obvious where the bug is. Also, the bug is
170
+
not likely to cause a crash, so we won't get a helpful error message telling us
171
+
what went wrong. If a user happened to notice that there was an error, then we
172
+
would have to check `triangle_area` to see if the formula we used is right,
173
+
then `multiply`, and `divide` to see if they were working as expected too!
147
174
148
-
However, if we had written tests for these functions, then we would have seen that both the `triangle_area` and `multiply` functions were not working as expected, allowing us to quickly see that the bug was in the `multiply` function without having to check the other functions.
175
+
However, if we had written tests for these functions, then we would have seen
176
+
that both the `triangle_area` and `multiply` functions were not working as
177
+
expected, allowing us to quickly see that the bug was in the `multiply`
178
+
function without having to check the other functions.
149
179
150
180
151
181
## Increased confidence in code
152
182
153
-
When you have tests for your code, you can be more confident that it works as expected. This is especially important when you are working in a team or producing software for users, as it allows everyone to trust the code. If you have a test that checks that a function works as expected, then you can be confident that the function will work as expected, even if you didn't write it yourself.
183
+
When you have tests for your code, you can be more confident that it works as
184
+
expected. This is especially important when you are working in a team or
185
+
producing software for users, as it allows everyone to trust the code. If you
186
+
have a test that checks that a function works as expected, then you can be
187
+
confident that the function will work as expected, even if you didn't write it
188
+
yourself.
154
189
155
190
## Forcing a more structured approach to coding
156
191
157
-
When you write tests for your code, you are forced to think more carefully about how your code behaves and how you will verify that it works as expected. This can help you to write more structured code, as you will need to think about how to test it as well as how it could fail.
192
+
When you write tests for your code, you are forced to think more carefully
193
+
about how your code behaves and how you will verify that it works as expected.
194
+
This can help you to write more structured code, as you will need to think
195
+
about how to test it as well as how it could fail.
158
196
159
197
::::::::::::::::::::::::::::::::::::: challenge
160
198
161
-
## Challenge 2: What could go wrong?
199
+
## What could go wrong?
162
200
163
201
Consider a function that controls a driverless car.
164
202
165
203
- What checks might we add to make sure it is not dangerous to use?
166
204
167
205
```python
168
-
169
206
defdrive_car(speed, direction):
170
207
171
-
...# complex car driving code
208
+
...# complex car driving code
172
209
173
210
return speed, direction, brake_status
174
-
175
-
176
211
```
177
212
178
213
:::::::::::::::::::::::: solution
179
214
180
-
## Answer
181
215
182
216
- We might want to check that the speed is within a safe range.
183
-
184
-
- We might want to check that the direction is a valid direction. ie not towards a tree, and if so, the car should be applying the brakes.
217
+
- We might want to check that the direction is a valid direction. ie not
218
+
towards a tree, and if so, the car should be applying the brakes.
0 commit comments