Skip to content

Commit c56a0f9

Browse files
Wrote instructions for part 6 section 1
1 parent 9550cc1 commit c56a0f9

File tree

1 file changed

+98
-15
lines changed

1 file changed

+98
-15
lines changed

tutorial/6-api-testing.md

Lines changed: 98 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,25 +8,108 @@ this feature shines when used together with web UI testing.
88
In this part, we will learn how to use Playwright's API testing features by automating tests
99
for [GitHub project boards](https://docs.github.com/en/issues/organizing-your-work-with-project-boards).
1010
These tests will be more complex than our previous DuckDuckGo search test.
11-
They will also require additional setup.
11+
They will make multiple calls to the [GitHub API](https://docs.github.com/en/rest) with authentication.
12+
The first test will *create* a new project card purely from the GitHub API,
13+
and the second test will *move* a project card from one column to another.
1214

1315

1416
## API setup
1517

16-
17-
Prerequisites:
18-
19-
* GitHub account
20-
* User project
21-
* Personal access token
22-
23-
24-
Inputs:
25-
26-
* GitHub username
27-
* GitHub password
28-
* GitHub access token
29-
* GitHub user project name
18+
Before we can develop tests for GitHub project boards,
19+
we need to set up a few things:
20+
21+
1. A GitHub account
22+
2. A GitHub user project
23+
3. A GitHub personal access token
24+
25+
Pretty much every developer these days already has a GitHub account,
26+
but not every developer may have set up a project board in GitHub.
27+
Follow the [user project instructions](https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/creating-a-project-board#creating-a-user-owned-project-board)
28+
to create a user project.
29+
Create a "classic" project and not a *Beta* project.
30+
Use the "Basic Kanban" template – the project must have at least two columns.
31+
The project may be public or private,
32+
but I recommend making it private if you intend to use it only for this tutorial.
33+
34+
GitHub API calls require a *personal access token* for authentication.
35+
GitHub no longer supports "basic" authentication with username and password.
36+
Follow the [personal access token instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
37+
to create a personal access token.
38+
Select the **repo** and **user** permissions.
39+
Remember to copy and save your token somewhere safe,
40+
because you won't be able to view it again!
41+
42+
The tests also need the following four inputs:
43+
44+
1. Your GitHub username
45+
2. Your GitHub password (for UI login)
46+
3. Your GitHub personal access token (for API authentication)
47+
4. Your GitHub user project name
48+
49+
Let's set these inputs as environment variables
50+
and read them into tests using pytest fixtures.
51+
Environment variables must be set before launching tests.
52+
53+
On macOS or Linxu, use the following commands:
54+
55+
```bash
56+
$ export GITHUB_USERNAME=<github-username>
57+
$ export GITHUB_PASSWORD=<github-password>
58+
$ export GITHUB_ACCESS_TOKEN=<github-access-token>
59+
$ export GITHUB_PROJECT_NAME="<github-project-name>"
60+
```
61+
62+
On Windows:
63+
64+
```console
65+
> set GITHUB_USERNAME=<github-username>
66+
> set GITHUB_PASSWORD=<github-password>
67+
> set GITHUB_ACCESS_TOKEN=<github-access-token>
68+
> set GITHUB_PROJECT_NAME="<github-project-name>"
69+
```
70+
71+
> *Warning:*
72+
> Make sure to keep these values secure.
73+
> Do not share your password or access token with anyone.
74+
75+
We should read these environment variables through pytest fixtures
76+
using the [`os`](https://docs.python.org/3/library/os.html) module
77+
so that any test can easily access them.
78+
Add the following function for reading environment variables to `tests/conftest.py`:
79+
80+
```python
81+
import os
82+
83+
def _get_env_var(varname):
84+
value = os.getenv(varname)
85+
assert value, f'{varname} is not set'
86+
return value
87+
```
88+
89+
This function will not only read an environment variable by name
90+
but also make sure the variable has a value.
91+
Then, add fixtures for each environment variable:
92+
93+
```python
94+
@pytest.fixture(scope='session')
95+
def gh_username():
96+
return _get_env_var('GITHUB_USERNAME')
97+
98+
@pytest.fixture(scope='session')
99+
def gh_password():
100+
return _get_env_var('GITHUB_PASSWORD')
101+
102+
@pytest.fixture(scope='session')
103+
def gh_access_token():
104+
return _get_env_var('GITHUB_ACCESS_TOKEN')
105+
106+
@pytest.fixture(scope='session')
107+
def gh_project_name():
108+
return _get_env_var('GITHUB_PROJECT_NAME')
109+
```
110+
111+
Now, our tests can safely and easily fetch these variables.
112+
These fixtures have *session* scope so that pytest will read them only one time during the entire testing session.
30113

31114

32115
## Writing a pure API test

0 commit comments

Comments
 (0)