Skip to content

Commit ca445db

Browse files
adrianoaru-nhsadrianoaru-nhs
authored
Feature/bcss 20627 investigation dataset markdown updates (#86)
<!-- markdownlint-disable-next-line first-line-heading --> ## Description <!-- Describe your changes in detail. --> Altered the markdown document to address feedback given during reviews ## Context <!-- Why is this change required? What problem does it solve? --> Makes the utility easier to understand and use. ## Type of changes <!-- What types of changes does your code introduce? Put an `x` in all the boxes that apply. --> - [x] Refactoring (non-breaking change) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would change existing functionality) - [ ] Bug fix (non-breaking change which fixes an issue) ## Checklist <!-- Go over all the following points, and put an `x` in all the boxes that apply. --> - [x] I am familiar with the [contributing guidelines](https://github.com/nhs-england-tools/playwright-python-blueprint/blob/main/CONTRIBUTING.md) - [x] I have followed the code style of the project - [ ] I have added tests to cover my changes (where appropriate) - [x] I have updated the documentation accordingly - [ ] This PR is a result of pair or mob programming --- ## Sensitive Information Declaration To ensure the utmost confidentiality and protect your and others privacy, we kindly ask you to NOT including [PII (Personal Identifiable Information) / PID (Personal Identifiable Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public) or any other sensitive data in this PR (Pull Request) and the codebase changes. We will remove any PR that do contain any sensitive information. We really appreciate your cooperation in this matter. - [x] I confirm that neither PII/PID nor sensitive data are included in this PR and the codebase changes.
1 parent 794cc2c commit ca445db

File tree

1 file changed

+94
-80
lines changed

1 file changed

+94
-80
lines changed

‎docs/utility-guides/InvestigationDataset.md‎

Lines changed: 94 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,147 @@
11
# Utility Guide: Investigation Dataset Utility
22

3-
The Investigation Dataset Utility provides methods to fill out the investigation dataset forms, and progress episodes, based on the age of the subject and the test results.
3+
The Investigation Dataset Utility provides methods to fill out the investigation dataset forms and progress episodes based on the age of the subject and the test results.<br>
4+
**Note:** This utility uses predetermined variables and logic to select input field values and progress forms. There is currently no way to alter which options are selected for each field, results are determined by the utility's internal logic.
45

56
## Table of Contents
67

78
- [Utility Guide: Investigation Dataset Utility](#utility-guide-investigation-dataset-utility)
89
- [Table of Contents](#table-of-contents)
910
- [Using the Investigation Dataset Utility](#using-the-investigation-dataset-utility)
10-
- [Investigation Dataset Completion - Required Arguments](#investigation-dataset-completion---required-arguments)
11-
- [After Investigation Dataset Complete - Required Arguments](#after-investigation-dataset-complete---required-arguments)
12-
- [Investigation Dataset Specific Functions](#investigation-dataset-specific-functions)
11+
- [InvestigationDatasetCompletion Class](#investigationdatasetcompletion-class)
12+
- [Required Arguments](#required-arguments)
13+
- [Key Methods](#key-methods)
14+
- [AfterInvestigationDatasetComplete Class](#afterinvestigationdatasetcomplete-class)
15+
- [Required Arguments](#required-arguments-1)
16+
- [Key Methods](#key-methods-1)
17+
- [InvestigationDatasetResults Class](#investigationdatasetresults-class)
1318
- [Example Usage](#example-usage)
1419

1520
## Using the Investigation Dataset Utility
1621

17-
To use the Investigation Dataset Utility, import the `InvestigationDatasetCompletion` and/or `AfterInvestigationDatasetComplete` classes from the `utils.investigation_dataset` directory into your test file and call the relevant methods as required.
22+
To use the Investigation Dataset Utility, import the `InvestigationDatasetCompletion`, `AfterInvestigationDatasetComplete`, and `InvestigationDatasetResults` classes from the `utils.investigation_dataset` module into your test file and call the relevant methods as required.
1823

19-
## Investigation Dataset Completion - Required Arguments
24+
```python
25+
from utils.investigation_dataset import (
26+
InvestigationDatasetCompletion,
27+
AfterInvestigationDatasetComplete,
28+
InvestigationDatasetResults,
29+
)
30+
```
31+
32+
The **InvestigationDatasetCompletion** and **AfterInvestigationDatasetComplete** classes are meant to be used one after another. this is because once the methods in the first class complete, you are on the correct page to call the methods in the other class. For further clarity on this please use the example provided at the bottom of the guide as a reference.
33+
34+
---
35+
36+
## InvestigationDatasetCompletion Class
2037

21-
The methods in this utility require specific arguments. Below is a summary of the required arguments for key methods:
38+
This class is responsible for filling out the investigation dataset forms for a subject.
39+
**All field selections are made using predetermined values within the utility.**
2240

23-
Required arguments for initialization:
24-
- page (Page): The Playwright Page object used for browser automation.
41+
### Required Arguments
2542

26-
Required arguments for main method:
27-
- nhs_no (str): The NHS number of the subject.
28-
- result (str): The result of the investigation dataset. Should be one of InvestigationDatasetResults (HIGH_RISK, LNPCP, NORMAL).
43+
- `page (Page)`: The Playwright Page object used for browser automation.
2944

30-
## After Investigation Dataset Complete - Required Arguments
45+
### Key Methods
3146

32-
The methods in this utility require specific arguments. Below is a summary of the required arguments for key methods:
47+
- **`complete_with_result(self, nhs_no: str, result: str) -> None`**
48+
Fills out the investigation dataset forms based on the test result and the subject's age.
49+
- `nhs_no (str)`: The NHS number of the subject.
50+
- `result (str)`: The result of the investigation dataset. Should be one of `InvestigationDatasetResults` (`HIGH_RISK`, `LNPCP`, `NORMAL`).
3351

34-
Required arguments for initialization:
35-
- page (Page): The Playwright Page object used for browser automation.
52+
- **`go_to_investigation_datasets_page(self, nhs_no) -> None`**
53+
Navigates to the investigation datasets page for a subject.
3654

37-
Required arguments for main method:
38-
- result (str): The result of the investigation dataset. Should be one of InvestigationDatasetResults (HIGH_RISK, LNPCP, NORMAL).
39-
- younger (`bool`): True if the subject is younger than 70, False otherwise.
55+
- **`default_investigation_dataset_forms(self) -> None`**
56+
Fills out the first part of the default investigation dataset form.
4057

41-
## Investigation Dataset Specific Functions
58+
- **`default_investigation_dataset_forms_continuation(self) -> None`**
59+
Fills out the second part of the default investigation dataset form.
4260

43-
The `investigation_dataset` utility is used to complete the investigation dataset forms for a subject.It contains methods to fill out the forms, and progress episodes, based on the age of the subject and the test result. Below are their key functions:
61+
- **`investigation_datasets_failure_reason(self) -> None`**
62+
Fills out the failure reason section of the investigation dataset form.
4463

45-
1. **`complete_with_result(self, nhs_no: str, result: str) -> None`**
46-
This method fills out the investigation dataset forms based on the test result and the subject's age.
64+
- **`polyps_for_high_risk_result(self) -> None`**
65+
Fills out the polyp information section of the investigation dataset form to trigger a high risk result.
4766

48-
- **Arguments**:
49-
- nhs_no (str): The NHS number of the subject.
50-
- result (str): The result of the investigation dataset. Should be one of InvestigationDatasetResults (HIGH_RISK, LNPCP NORMAL).
67+
- **`polyps_for_lnpcp_result(self) -> None`**
68+
Fills out the polyp information section of the investigation dataset form to trigger a LNPCP result.
5169

52-
2. **`go_to_investigation_datasets_page(self, nhs_no) -> None`**
53-
This method navigates to the investigation datasets page for a subject.
70+
- **`polyp1_intervention(self) -> None`**
71+
Fills out the intervention section of the investigation dataset form for polyp 1.
5472

55-
- **Arguments**:
56-
- nhs_no (str): The NHS number of the subject.
73+
- **`save_investigation_dataset(self) -> None`**
74+
Saves the investigation dataset form.
5775

58-
3. **`default_investigation_dataset_forms(self) -> None`**
59-
This method fills out the first part of the default investigation dataset form.
76+
---
6077

61-
4. **`default_investigation_dataset_forms_continuation(self) -> None`**
62-
This method fills out the second part of the default investigation dataset form.
78+
## AfterInvestigationDatasetComplete Class
6379

64-
5. **`investigation_datasets_failure_reason(self) -> None`**
65-
This method fills out the failure reason section of the investigation dataset form.
80+
This class provides methods to progress an episode after the investigation dataset has been completed.
81+
**All field selections and progressions are made using predetermined values within the utility.**
6682

67-
6. **`polyps_for_high_risk_result(self) -> None`**
68-
This method fills out the polyp information section of the investigation dataset form to trigger a high risk result.
83+
### Required Arguments
6984

70-
7. **`polyps_for_lnpcp_result(self) -> None`**
71-
This method fills out the polyp information section of the investigation dataset form to trigger a LNPCP result.
85+
- `page (Page)`: The Playwright Page object used for browser automation.
7286

73-
8. **`polyp1_intervention(self) -> None`**
74-
This method fills out the intervention section of the investigation dataset form for polyp 1.
87+
- **For main progression method:**
88+
- `result (str)`: The result of the investigation dataset. Should be one of `InvestigationDatasetResults` (`HIGH_RISK`, `LNPCP`, `NORMAL`).
89+
- `younger (bool)`: `True` if the subject is between 50-70, `False` otherwise.
7590

76-
9. **`save_investigation_dataset(self) -> None`**
77-
This method saves the investigation dataset form.
91+
### Key Methods
7892

79-
10. **`progress_episode_based_on_result(self, result: str, younger: bool) -> None`**
80-
This method progresses the episode based on the result of the investigation dataset.
93+
- **`progress_episode_based_on_result(self, result: str, younger: bool) -> None`**
94+
Progresses the episode according to the investigation result and whether the subject is younger than 70.
8195

82-
- **Arguments**:
83-
- result (str): The result of the investigation dataset. Should be one of InvestigationDatasetResults (HIGH_RISK, LNPCP, NORMAL).
84-
- younger (`bool`): True if the subject is younger than 50, False otherwise.
96+
- **`after_high_risk_result(self) -> None`**
97+
Advances an episode that has a high-risk result using predetermined field values.
8598

86-
11. **`after_high_risk_result(self) -> None`**
87-
This method advances an episode that has a high-risk result.
99+
- **`after_lnpcp_result(self) -> None`**
100+
Advances an episode that has a LNPCP result using predetermined field values.
88101

89-
12. **`after_lnpcp_result(self) -> None`**
90-
This method advances an episode that has a LNPCP result.
102+
- **`after_normal_result(self) -> None`**
103+
Advances an episode that has a normal result using predetermined field values.
91104

92-
13. **`after_normal_result(self) -> None`**
93-
This method advances an episode that has a normal result.
105+
- **`handover_subject_to_symptomatic_care(self) -> None`**
106+
Hands over a subject to symptomatic care.
94107

95-
14. **`handover_subject_to_symptomatic_care(self) -> None`**
96-
This method hands over a subject to symptomatic care.
108+
- **`record_diagnosis_date(self) -> None`**
109+
Records the diagnosis date for a subject.
97110

98-
15. **`record_diagnosis_date(self) -> None`**
99-
This method records the diagnosis date for a subject.
111+
---
112+
113+
## InvestigationDatasetResults Class
114+
115+
This `enum` provides the possible result values for the investigation dataset:
116+
117+
- `HIGH_RISK`
118+
- `LNPCP`
119+
- `NORMAL`
120+
121+
---
100122

101123
## Example Usage
102124

103125
```python
104-
from playwright.sync_api import sync_playwright
126+
from playwright.sync_api import Page
105127
from utils.investigation_dataset import (
106128
InvestigationDatasetCompletion,
107-
InvestigationDatasetResults,
108129
AfterInvestigationDatasetComplete,
130+
InvestigationDatasetResults,
109131
)
110132

111-
def example_investigation_dataset_usage(nhs_no: str, result: str, younger: bool) -> None:
112-
# Start Playwright and open a browser/page (simplified for example)
113-
with sync_playwright() as p:
114-
browser = p.chromium.launch(headless=True)
115-
page = browser.new_page()
133+
nhs_no="1234567890",
134+
result=InvestigationDatasetResults.HIGH_RISK,
135+
younger=True
116136

117-
# Complete the investigation dataset for a subject
118-
investigation = InvestigationDatasetCompletion(page)
119-
investigation.complete_with_result(nhs_no, result)
137+
investigation = InvestigationDatasetCompletion(page)
138+
investigation.complete_with_result(nhs_no, result)
120139

121-
# Progress the episode based on the result and subject's age
122-
after_investigation = AfterInvestigationDatasetComplete(page)
123-
after_investigation.progress_episode_based_on_result(result, younger)
140+
# Progress the episode based on the result and subject's age
141+
after_investigation = AfterInvestigationDatasetComplete(page)
142+
after_investigation.progress_episode_based_on_result(result, younger)
143+
```
124144

125-
browser.close()
145+
---
126146

127-
# Example usage:
128-
example_investigation_dataset_usage(
129-
nhs_no="1234567890",
130-
result=InvestigationDatasetResults.HIGH_RISK,
131-
younger=True
132-
)
133-
```
147+
For more details on each function's implementation, refer to the source code in `utils/investigation_dataset.py`.

0 commit comments

Comments
 (0)