Improve existing documentation
Improve documentation for different markdown documentation files. Goal is to simplify and make the language and content more clear.
This commit is contained in:
undergroundwires
@@ -59,10 +59,8 @@ This project includes [GitHub Actions](../.github/workflows/) to automatically p
|
||||
|
||||
## GitOps
|
||||
|
||||
CI/CD is fully automated using different Git events and GitHub actions. This repository uses [bump-everywhere](https://github.com/undergroundwires/bump-everywhere) to automate versioning, tagging, creation of [`CHANGELOG.md`](./../CHANGELOG.md) and GitHub releases. A dedicated [workflow](./../.github/workflows/release.desktop.yaml) creates desktop installers and executables and attaches them into GitHub releases.
|
||||
CI/CD pipelines automate operational tasks based on different Git events. [bump-everywhere](https://github.com/undergroundwires/bump-everywhere) enables this automation.
|
||||
|
||||
Everything that's merged in the master goes directly to production.
|
||||
📖 Read more in [`ci-cd.md`](./ci-cd.md#gitops).
|
||||
|
||||
📖 Refer to [ci-cd.md](./ci-cd.md) to read more on CI/CD pipelines.
|
||||
|
||||
[](../.github/workflows/)
|
||||
[](../.github/workflows/)
|
||||
|
||||
@@ -1,10 +1,26 @@
|
||||
# Pipelines
|
||||
# CI/CD overview
|
||||
|
||||
Pipelines are found under [`.github/workflows`](./../.github/workflows).
|
||||
## GitOps
|
||||
|
||||
CI/CD is fully automated using different Git events and GitHub actions. This repository uses [bump-everywhere](https://github.com/undergroundwires/bump-everywhere) to automate versioning, tagging, creation of `CHANGELOG.md` and GitHub releases. A dedicated workflow [release.desktop.yaml](./../.github/workflows/release.desktop.yaml) creates desktop installers and executables and attaches them into GitHub releases.
|
||||
|
||||
Everything that's merged in the master goes directly to production.
|
||||
|
||||
[](../.github/workflows/)
|
||||
|
||||
## Pipeline files
|
||||
|
||||
privacy.sexy uses [GitHub actions](https://github.com/features/actions) to define and run pipelines as code.
|
||||
|
||||
GitHub workflows i.e. pipelines exist in [`/.github/.workflows/`](./../.github/workflows/) folder without any subfolders due to GitHub actions requirements [1] .
|
||||
|
||||
[1]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows
|
||||
|
||||
## Pipeline types
|
||||
|
||||
They are categorized based on their type:
|
||||
We categorize pipelines into different categories. We use these names in convention when naming files and actions, see [naming conventions](#naming-conventions).
|
||||
|
||||
The categories consist of:
|
||||
|
||||
- `tests`: Different types of tests to verify functionality.
|
||||
- `checks`: Other controls such as vulnerability scans or styling checks.
|
||||
@@ -12,8 +28,18 @@ They are categorized based on their type:
|
||||
|
||||
## Naming conventions
|
||||
|
||||
Pipeline files are named using: **`<type>.<name>.yaml`**.
|
||||
Convention for naming pipeline files: **`<type>.<name>.yaml`**.
|
||||
|
||||
**`type`**: Sub-folders do not work for GitHub workflows so that's why `<type>.` prefix is used. See also [pipeline types](#pipeline-types).
|
||||
**`type`**:
|
||||
|
||||
**`name`**: Pipeline themselves are named using kebab case. It allows for easier URL references for their status badges. E.g. file name `tests.unit.yaml`, pipeline name: `name: unit-tests`
|
||||
- Sub-folders do not work for GitHub workflows [1] so we use `<type>.` prefix to organize them.
|
||||
- See also [pipeline types](#pipeline-types) for list of all usable types.
|
||||
|
||||
**`name`**:
|
||||
|
||||
- We name workflows using kebab-case.
|
||||
- E.g. file name `tests.unit.yaml`, pipeline file should set the naem as: `name: unit-tests`.
|
||||
- Kebab-case allows to have better URL references to them.
|
||||
- [README.md](./../README.md) uses URL references to show status badges for actions.
|
||||
|
||||
[1]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows
|
||||
|
||||
@@ -5,7 +5,7 @@ Before your commit, a good practice is to:
|
||||
1. [Run unit tests](#testing)
|
||||
2. [Lint your code](#linting)
|
||||
|
||||
You could run other types of tests as well, but they may take longer time and overkill for your changes. All tests are executed inside a pull request.
|
||||
You could run other types of tests as well, but they may take longer time and overkill for your changes. Automated actions executes the tests for a pull request or change in the main branch. See [ci-cd.md](./ci-cd.md) for more information.
|
||||
|
||||
## Commands
|
||||
|
||||
@@ -22,6 +22,8 @@ You could run other types of tests as well, but they may take longer time and ov
|
||||
- Interactive mode with GUI: `npm run test:e2e`
|
||||
- Headless mode without GUI: `npm run test:e2e -- --headless`
|
||||
|
||||
📖 Read more about testing in [tests](./tests.md).
|
||||
|
||||
### Linting
|
||||
|
||||
- Lint all (recommended 💡): `npm run lint`
|
||||
@@ -48,4 +50,4 @@ You could run other types of tests as well, but they may take longer time and ov
|
||||
|
||||
You should use EditorConfig to follow project style.
|
||||
|
||||
For Visual Studio Code, recommended extensions are defined in [`.vscode/extensions.json`](./../.vscode/extensions.json).
|
||||
For Visual Studio Code, [`.vscode/extensions.json`](./../.vscode/extensions.json) includes list of recommended extensions.
|
||||
|
||||
@@ -3,14 +3,15 @@
|
||||
## Benefits of templating
|
||||
|
||||
- Generating scripts by sharing code to increase best-practice usage and maintainability.
|
||||
- Creating self-contained scripts without depending on each other that can be easily shared.
|
||||
- Creating self-contained scripts without cross-dependencies.
|
||||
- Use of pipes for writing cleaner code and letting pipes do dirty work.
|
||||
|
||||
## Expressions
|
||||
|
||||
- Expressions in the language are defined inside mustaches (double brackets, `{{` and `}}`).
|
||||
- Expression syntax is inspired mainly by [Go Templates](https://pkg.go.dev/text/template).
|
||||
- Expressions are used in and enabled by functions where they can be used.
|
||||
- Expressions start and end with mustaches (double brackets, `{{` and `}}`).
|
||||
- E.g. `Hello {{ $name }} !`
|
||||
- Syntax is close to [Go Templates ❤️](https://pkg.go.dev/text/template) that has inspired this templating language.
|
||||
- Functions enables usage of expressions.
|
||||
- In script definition parts of a function, see [`Function`](./collection-files.md#Function).
|
||||
- When doing a call as argument values, see [`FunctionCall`](./collection-files.md#Function).
|
||||
|
||||
@@ -55,34 +56,36 @@ A function can call other functions such as:
|
||||
|
||||
### with
|
||||
|
||||
- Skips the block if the variable is absent or empty.
|
||||
- Binds its context (`.`) value of provided argument for the parameter if provided one.
|
||||
- A block is defined as `{{ with $parameterName }} Parameter value is {{ . }} here {{ end }}`.
|
||||
- The parameters used for `with` condition should be declared as optional, otherwise `with` block becomes redundant.
|
||||
- Example:
|
||||
Skips its "block" if the variable is absent or empty. Its "block" is between `with` start (`{{ with .. }}`) and end (`{{ end }`}) expressions. E.g. `{{ with $parameterName }} Hi, I'm a block! {{ end }}`.
|
||||
|
||||
```yaml
|
||||
function: FunctionThatOutputsConditionally
|
||||
parameters:
|
||||
- name: 'argument'
|
||||
optional: true
|
||||
code: |-
|
||||
{{ with $argument }}
|
||||
Value is: {{ . }}
|
||||
{{ end }}
|
||||
```
|
||||
Binds its context (`.`) value of provided argument for the parameter if provided one. E.g. `{{ with $parameterName }} Parameter value is {{ . }} here {{ end }}`.
|
||||
|
||||
💡 Declare parameters used for `with` condition as optional. Set `optional: true` for the argument if you use it like `{{ with $argument }} .. {{ end }}`.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
function: FunctionThatOutputsConditionally
|
||||
parameters:
|
||||
- name: 'argument'
|
||||
optional: true
|
||||
code: |-
|
||||
{{ with $argument }}
|
||||
Value is: {{ . }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
### Pipes
|
||||
|
||||
- Pipes are set of functions available for handling text in privacy.sexy.
|
||||
- Pipes are functions available for handling text.
|
||||
- Allows stacking actions one after another also known as "chaining".
|
||||
- Just like [Unix pipelines](https://en.wikipedia.org/wiki/Pipeline_(Unix)), the concept is simple: each pipeline's output becomes the input of the following pipe.
|
||||
- Pipes are provided and defined by the compiler and consumed by collection files.
|
||||
- Pipes can be combined with [parameter substitution](#parameter-substitution) and [with](#with).
|
||||
- Like [Unix pipelines](https://en.wikipedia.org/wiki/Pipeline_(Unix)), the concept is simple: each pipeline's output becomes the input of the following pipe.
|
||||
- You cannot create pipes. [A dedicated compiler](./application.md#parsing-and-compiling) provides pre-defined pipes to consume in collection files.
|
||||
- You can combine pipes with other expressions such as [parameter substitution](#parameter-substitution) and [with](#with) syntax.
|
||||
- ❗ Pipe names must be camelCase without any space or special characters.
|
||||
- **Existing pipes**
|
||||
- `inlinePowerShell`: Converts a multi-lined PowerShell script to a single line.
|
||||
- `escapeDoubleQuotes`: Escapes `"` characters to be used inside double quotes (`"`)
|
||||
- `escapeDoubleQuotes`: Escapes `"` characters, allows you to use them inside double quotes (`"`).
|
||||
- **Example usages**
|
||||
- `{{ with $code }} echo "{{ . | inlinePowerShell }}" {{ end }}`
|
||||
- `{{ with $code }} echo "{{ . | inlinePowerShell | escapeDoubleQuotes }}" {{ end }}`
|
||||
|
||||
@@ -1,23 +1,28 @@
|
||||
# Tests
|
||||
|
||||
- There are two different types of tests executed:
|
||||
1. [Unit tests](#unit-tests)
|
||||
2. [Integration tests](#integration-tests)
|
||||
3. [End-to-end (E2E) tests](#e2e-tests)
|
||||
- All tests
|
||||
- Uses [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/).
|
||||
- Are written in files that includes `.spec` extension.
|
||||
- 💡 You can use path/module alias `@/tests` in import statements.
|
||||
There are different types of tests executed:
|
||||
|
||||
1. [Unit tests](#unit-tests)
|
||||
2. [Integration tests](#integration-tests)
|
||||
3. [End-to-end (E2E) tests](#e2e-tests)
|
||||
|
||||
Common aspects for all tests:
|
||||
|
||||
- They use [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/).
|
||||
- Their files end with `.spec.{ts|js}` suffix.
|
||||
|
||||
💡 You can use path/module alias `@/tests` in import statements.
|
||||
|
||||
## Unit tests
|
||||
|
||||
- Tests each component in isolation.
|
||||
- Defined in [`./tests/unit`](./../tests/unit).
|
||||
- Unit tests test each component in isolation.
|
||||
- All unit tests goes under [`./tests/unit`](./../tests/unit).
|
||||
- They rely on [stubs](./../tests/unit/shared/Stubs) for isolation.
|
||||
|
||||
### Unit tests structure
|
||||
|
||||
- [`./src/`](./../src/)
|
||||
- Includes code that will be tested tested.
|
||||
- Includes source code that unit tests will test.
|
||||
- [`./tests/unit/`](./../tests/unit/)
|
||||
- Includes test code.
|
||||
- Tests follow same folder structure as [`./src/`](./../src).
|
||||
@@ -29,7 +34,7 @@
|
||||
- Asserting functions should start with `expect` prefix.
|
||||
- [`TestCases/`](./../tests/unit/shared/TestCases/)
|
||||
- Shared test cases.
|
||||
- Test runner functions that uses `it()` from Mocha test [Mocha test framework](https://mochajs.org/) should be prefixed with `it.`
|
||||
- Functions that calls `it()` from [Mocha test framework](https://mochajs.org/) should have `it` prefix.
|
||||
- E.g. `itEachAbsentCollectionValue()`.
|
||||
- [`Stubs/`](./../tests/unit/shared/Stubs)
|
||||
- Includes stubs to be able to test components in isolation.
|
||||
@@ -38,39 +43,39 @@
|
||||
### Unit tests naming
|
||||
|
||||
- Each test suite first describe the system under test.
|
||||
- E.g. tests for class `Application` is categorized under `Application`.
|
||||
- Tests for specific methods are categorized under method name (if applicable).
|
||||
- E.g. test for `run()` is categorized under `run`.
|
||||
- E.g. tests for class `Application.ts` are all inside `Application.spec.ts`.
|
||||
- `describe` blocks tests for same function (if applicable).
|
||||
- E.g. test for `run()` are inside `describe('run', () => ..)`.
|
||||
|
||||
### Act, arrange, assert
|
||||
|
||||
- Tests use act, arrange and assert (AAA) pattern when applicable.
|
||||
- **Arrange**
|
||||
- Should set up the test case.
|
||||
- Sets up the test case.
|
||||
- Starts with comment line `// arrange`.
|
||||
- **Act**
|
||||
- Should cover the main thing to be tested.
|
||||
- Executes the actual test.
|
||||
- Starts with comment line `// act`.
|
||||
- **Assert**
|
||||
- Should elicit some sort of response.
|
||||
- Elicit some sort of expectation.
|
||||
- Starts with comment line `// assert`.
|
||||
|
||||
## Integration tests
|
||||
|
||||
- Tests functionality of a component in combination with others (not isolated).
|
||||
- Ensure dependencies to third parties work as expected.
|
||||
- Defined in [`./tests/integration`](./../tests/integration).
|
||||
- Defined in [./tests/integration](./../tests/integration).
|
||||
|
||||
## E2E tests
|
||||
|
||||
- Test the functionality and performance of a running application.
|
||||
- E2E tests are configured by vue plugin [`e2e-cypress`](https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-plugin-e2e-cypress#readme) for Vue CLI.
|
||||
- Names and folders are structured logically based on tests.
|
||||
- Vue CLI plugin [`e2e-cypress`](https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-plugin-e2e-cypress#readme) configures E2E tests.
|
||||
- Test names and folders have logical structure based on tests executed.
|
||||
- The structure is following:
|
||||
- [`cypress.json`](./../cypress.json): Cypress configuration file.
|
||||
- [`./tests/e2e/`](./../tests/e2e/): Base Cypress folder.
|
||||
- [`/specs/`](./../tests/e2e/specs/): Test files, test are named with `.spec.js` extension.
|
||||
- [`/plugins/index.js`](./../tests/e2e/plugins/index.js): Plugin file executed before project is loaded.
|
||||
- [`/specs/`](./../tests/e2e/specs/): Test files named with `.spec.js` extension.
|
||||
- [`/plugins/index.js`](./../tests/e2e/plugins/index.js): Plugin file executed before loading project.
|
||||
- [`/support/index.js`](./../tests/e2e/support/index.js): Support file, runs before every single spec file.
|
||||
- *(Ignored)* `/videos`: Asset folder for videos taken during tests.
|
||||
- *(Ignored)* `/screenshots`: Asset folder for Screenshots taken during tests.
|
||||
|
||||
Reference in New Issue
Block a user