Skip to content

add instructions for running specific tests #1980

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lorerod merged 2 commits into from
Sep 9, 2025
Merged

add instructions for running specific tests #1980

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7e762c5
add instructions for running specific tests
lorerod Sep 4, 2025
e678695
implemented feedback
lorerod Sep 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 104 additions & 9 deletions content/en/community/contributing/code/core/automated-tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,40 @@ High coverage of functionality. If measured in branch coverage percentage, aim
### Implementation
In cht-core unit tests are located in the `tests` directories of each app (For example, in [`webapp/tests`](https://github.com/medic/cht-core/tree/master/webapp/tests) you can find unit test for the webapp). Run them locally with: `npm run unit`.

### Running Unit Tests Locally
Run the full unit test suite locally with:
```bash
npm run unit
```

#### Running one module isolated
To run unit tests for a specific module/service instead of the entire suite:

```bash
# Run unit tests for admin module
npm run unit-admin

# Run unit tests for couchdb module
npm run unit-couchdb

# Run unit tests for API module
npm run unit-api

# Run unit tests for sentinel module
npm run unit-sentinel

# Run unit tests for shared-lib module
npm run unit-shared-lib

# Run unit tests for webapp module
npm run unit-webapp
```
Comment on lines +61 to +64

@mrjones-plip mrjones-plip Sep 4, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great! I suggest instead of listing a bunch of examples of running an individual tests, I'd give and example to run just one. Then, list out how to find the rest. For example, for me, if type npm run unit and then hit the key to get autocomplete to fire and dynamically show all available:

$ npm run unit
unit                      unit-couchdb              unit-sentinel           
unit-admin                unit-haproxy              unit-shared-lib         
unit-api                  unit-haproxy-healthcheck  unit-webapp             
unit-cht-deploy           unit-nginx                unit-webapp-continuous


#### Isolating specific tests within a module
To run only specific test suites or individual tests within a module, you can use `describe.only` or `it.only` in your test files.

@mrjones-plip mrjones-plip Sep 4, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you give a more specific example of exactly how to do this? Maybe deep link to a line number on a file and show the before and after?


**Note:** Remember to remove `.only` before committing your code, as it will prevent other tests from running.

## Integration Tests

### Description
Expand All @@ -70,7 +104,7 @@ Dramatically fewer than unit tests. The goal is not to verify all branches; it i
Backend integration testing means testing through the entire stack of the application connected to other applications within the system. In the image below, this involves testing each application (box) and its interaction with other applications within the system.
The tests are isolated from the webapp with necessary shortcuts to make testing more straightforward and faster. No part of the system is mocked.

**Backend integration tests** are located in [`tests/integration`](https://github.com/medic/cht-core/tree/master/tests/integration). Run them locally with `npm run integration-all-local` and `npm run integration-sentinel-local`.
**Backend integration tests** are located in [`tests/integration`](https://github.com/medic/cht-core/tree/master/tests/integration).

```mermaid
flowchart LR
Expand All @@ -94,9 +128,52 @@ flowchart LR
integration-tests <--Pouch/HTTPS--> cht-e2e
```

### Running Backend Integration Tests Locally

Run the full integration test suites locally with:

```bash
# Run all backend integration tests
npm run integration-all-local

# Run sentinel integration tests
npm run integration-sentinel-local

# Run API integration tests
npm run integration-api

# Run integration tests with k3d (Kubernetes)
npm run integration-all-k3d-local
npm run integration-sentinel-k3d-local
```

#### Running one spec isolated
To run a specific integration test spec instead of the entire test suite:

```bash
# Run only contact-edit tests
npx mocha --config tests/integration/.mocharc-base.js tests/integration/contacts/contact-edit.spec.js
```

#### Isolating specific tests
To run only specific integration tests within a spec file, you can use `describe.only` or `it.only` in your test files.

**Note:** Remember to remove `.only` before committing your code, as it will prevent other tests from running.

**Frontend integration tests** (or web component tests) are designed to validate form behavior (including page layout) without needing to run the whole CHT. The web component isolates the enketo form functionality from the CHT webapp. This only covers forms and not other parts of the webapp. It does not trace behavior though the whole system and the database is never involved. Instead, the whole idea of the web component is to abstract the UI functionality away from the underlying backend complexity.

Frontend integration tests are located in [`tests/integration`](https://github.com/medic/cht-core/tree/master/tests/integration). To run them locally you need to build a cht-form Web Component with `npm run build-cht-form` and `npm run integration-cht-form` to run the web component tests.
Frontend integration tests are located in [`tests/integration`](https://github.com/medic/cht-core/tree/master/tests/integration).

### Running Frontend Integration Tests Locally

To run them locally you need to build a cht-form Web Component with:
```bash
npm run build-cht-form
```
And after building you can run the tests with:
```bash
npm run integration-cht-form
```

## E2E Tests

Expand All @@ -119,10 +196,32 @@ E2e tests give the most confidence to decide if the feature is working, but must
### Implementation
Our end-to-end tests are designed to test the entire system as a whole. They interact with the webapp as a user would, using [WebdriverIO](https://webdriver.io/) to control a headless browser session. They are not isolated from the rest of the system, and they do not use mocking.

End-to-end tests are located in [`tests/e2e`](https://github.com/medic/cht-core/tree/master/tests/e2e). Run them locally with the following:
End-to-end tests are located in [`tests/e2e`](https://github.com/medic/cht-core/tree/master/tests/e2e).


### Running E2E Tests Locally
Run the full E2E test suites locally with:

- `npm run wdio-local` to run the tests for the default config
- `npm run wdio-default-mobile-local` to run the mobile tests
```bash
# Run default E2E tests
npm run wdio-local

# Run mobile E2E tests
npm run wdio-default-mobile-local
```

#### Running one spec isolated
To run a specific E2E test spec instead of the entire test suite:

```bash
# Run only the tests inside the pregnancy spec
npm run wdio-local -- --spec=pregnancy.wdio-spec.js

@mrjones-plip mrjones-plip Sep 4, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should say wow to find a list of all e2e tests to run. I assume just specify the file name, but a deep link to the directory with all the files would be good.

alternately, walking the user down the sub directories in /tree/master/tests/e2e to find the specific pregnancy.wdio-spec.js could work instead. We could use the filetree feature maybe??

Comment thread
dianabarsan marked this conversation as resolved.
Resolved
```

#### Isolating specific tests
To run only specific E2E tests within a spec file, you can use `describe.only` or `it.only` in your test files.

**Note:** Remember to remove `.only` before committing your code, as it will prevent other tests from running.

```mermaid
flowchart LR
Expand Down Expand Up @@ -208,10 +307,6 @@ There are logs and screenshots stored in the allure reports when a job failed on
- Extract the `.zip` file.
- From your cht-core directory, run `npx allure open <path>/allure-report/`. Being `<path>` the location where the zip file was extracted.

#### Running just the failing test

Running e2e tests can be quite slow so to save time modify the `specs` property of [`/tests/e2e/**/wdio.conf.js`](https://github.com/medic/cht-core/blob/master/tests/e2e/default/wdio.conf.js#L7) so it only finds your test. You can also use `describe.skip` and `it.skip` to skip specific tests.

##### IntelliJ Based

1. In a terminal, run `npm run build-dev-watch`
Expand Down