diff --git a/DEVELOPING.md b/DEVELOPING.md index 49c33c0..83832f0 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -1,7 +1,149 @@ # Developing `trustify-tests` -This document describes how to setup your environment to run the `trustify-tests` -on your local environment. +This document describes: + +- the layout of the `trustify-tests` repository + +- how to contribute a test + +- how to setup your environment to run the `trustify-tests` on your local + environment + +## Repository Layout + +The layout of the `trustify-tests` repository looks like follows: + +``` +. +├── package.json +├── playwright.config.ts +├── config +├── etc +└── tests + ├── api + │   ├── fixtures.ts + │   ├── client + │   ├── dependencies + │   ├── features + │   └── helpers + ├── common + │   ├── constants.ts + │   └── assets + │   ├── csaf + │   └── sbom + └── ui + ├── dependencies + ├── features + │   ├── *.feature + │   ├── @sbom-explorer + │   └── @vulnerability-explorer + ├── helpers + └── steps +``` + +- `package.json` - project configuration the `npm` ([Node.js Package Manager](https://docs.npmjs.com/)) + understands; you can define your scripts (commands) here that you can then + execute by `npm run ` + +- `playwright.config.ts` - a configuration for [Playwright](https://playwright.dev/docs/intro) + and [Playwright-BDD](https://vitalets.github.io/playwright-bdd/#/) + +- `config` contains configuration files that are common for the repository; + currently it contains + + - `openapi.yaml` - a file with the [Trustify](https://github.com/trustification/trustify) + API definition; every time the file changes on the [Trustify](https://github.com/trustification/trustify) + side it should be also updated here + + - `openapi-ts.config.ts` - a configuration for `@hey-api/openapi-ts` telling + it how to generate the content of `tests/api/client`; whenever this or + `openapi.yaml` file changes `npm run openapi` should be executed to update + the content of `tests/api/client` + +- `etc` contains auxiliary files such as Podman/Docker compose files to start + a Playwright container + +- `tests/api` contains API tests organized as follows + + - `fixtures.ts` - API tests fixtures written in TypeScript + + - `client` contains a TypeScript interface to [Trustify](https://github.com/trustification/trustify) + API generated from `config/openapi.yaml` by `npm run openapi` + + - `dependencies` contains setup and tear down routines which are run before + the start and after the end of the API test suite, respectively + + - `features` contains API tests itself; `_openapi_client_examples.ts` shows + how to use generated TypeScript interface to [Trustify](https://github.com/trustification/trustify) + in API tests + + - `helpers` contains auxiliary utilities used by API tests + +- `tests/common` contains data and definitions shared by both API and UI tests + + - `constants.ts` - constant definitions used by both API and UI tests + + - `assets/csaf` contains compressed (`bz2`) samples of CSAF files + + - `assets/sboms` contains compressed (`bz2`) samples of SBOM files + +- `tests/ui` contains UI tests; UI tests are developed following BDD (Behavior + Driven Development) methodology; the directory is organized as follows + + - `dependencies` contains setup and tear down routines which are run before + the start and after the end of the UI test suite, respectively + + - `features` contains the UI tests itself; the content of the directory is + further organized as follows + + - `*.feature` files are test scenarios described in [Gherkin](https://cucumber.io/docs/gherkin/); + `*.feature` files on the top level of the `tests/ui/features` directory + describe scenarios that need to be implemented first in the [front end](https://github.com/trustification/trustify-ui); + that is, they describe the expected front end behavior + + - `@*` directories contain `*.feature` files and `*.step.ts` files used to + test the so far implemented [front end](https://github.com/trustification/trustify-ui) + features; see also [Tags from path](https://vitalets.github.io/playwright-bdd/#/writing-steps/scoped?id=tags-from-path) + documentation + + - `helpers` contains auxiliary utilities used by UI tests + + - `steps` contains implementation of common BDD steps used in `tests/ui/features` + +## Contributing a Test + +To contribute an API test, put your code under the `tests/api/features` directory. +If the test also contains a generic code that could be shared by more API tests, +put that code under the `tests/api/helpers` directory. In a case that code is +also intended to be shared by UI tests, put it under the `tests/common` directory +instead. If you have also some assets that need to be contributed together with +the test, put them under the `tests/common/assets` directory. + +To contribute a UI (front end) test, put your code under the `tests/ui/features` +directory. Depending on the status of a feature your test is trying to cover, +there are two ways of how to proceed: + +1. **A test is covering an implemented UI feature.** Put your test under + a `tests/ui/features/@*` directory. You can choose from the existing or create + your own depending on your use case. + +1. **A test is covering a use case (scenario) not yet implemented.** Describe + your use case in [Gherkin](https://cucumber.io/docs/gherkin/) and put it + inside a `tests/ui/features/*.feature` file. The use case should be + communicated with the [upstream](https://github.com/trustification/trustify-ui) + before. Once the upstream implements the requested features covering your use + case, the next step is to put your `*.feature` file(s) under a `tests/ui/features/@*` + directory and implement missing steps to make it work under the Playwright + BDD framework. + +Other directories you should be interested in when contributing a UI test: + +- `tests/common` (described earlier) + +- `tests/ui/helpers` follows the same rules as `tests/api/helpers` + +- `tests/ui/steps` is intended to be a right place for steps that are common + across many use cases (scenarios) ## System Requirements