Skip to content

Commit 1c0d3e5

Browse files
Copilotaholstrup1
andauthored
Add unit testing guidelines to Contribute.md (#114)
* Initial plan * Add comprehensive testing notes to Contribute.md Co-authored-by: aholstrup1 <117829001+aholstrup1@users.noreply.github.com> * Remove E2E testing documentation, keep only unit tests Co-authored-by: aholstrup1 <117829001+aholstrup1@users.noreply.github.com> * Update unit test best practices Removed the guideline to follow the Arrange-Act-Assert pattern from best practices for unit tests. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: aholstrup1 <117829001+aholstrup1@users.noreply.github.com>
1 parent aefefe4 commit 1c0d3e5

File tree

1 file changed

+69
-0
lines changed

1 file changed

+69
-0
lines changed

Scenarios/Contribute.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,10 +43,79 @@ Please ensure that all unit tests run and create a Pull Request against [https:/
4343

4444
In the AL-Go repository we use a number of precommit hooks to help us identify issues in the code. We run the precommit hooks locally but also as a PR check. In order to ensure this check passes please install pre-commit in your local AL-Go repository. Pre-Commit can be installed by following the instructions on https://pre-commit.com/#quick-start. Once the precommint hooks are installed you can run `pre-commit run --all-files` to verify your changes.
4545

46+
## Testing your contributions
47+
48+
When contributing to AL-Go, it's important to add tests for your changes to ensure code quality and prevent regressions.
49+
50+
**When to add tests:**
51+
52+
- **Always add unit tests** for new functions, modules, or bug fixes
53+
- **Update existing tests** if you modify existing functionality
54+
- **Ensure all tests pass** before submitting a pull request
55+
56+
Unit tests in AL-Go are fast, isolated tests that verify individual functions and modules using the Pester testing framework.
57+
58+
The section below provides detailed guidance on how to add unit tests.
59+
4660
## Unit tests
4761

4862
The Tests folder, in the AL-Go repository, contains a number of unit-tests. Open Tests/runtests.ps1 in VS Code and select Run. Unit tests are quick and will run on every PR and every Push. We will be adding a lot of unit tests going forward.
4963

64+
### How to add unit tests
65+
66+
When contributing to AL-Go, you should add unit tests for your changes. Unit tests in AL-Go use the [Pester](https://pester.dev/) testing framework for PowerShell.
67+
68+
**Creating a new unit test file:**
69+
70+
1. Create a new `.Test.ps1` file in the `Tests` folder. The file name should describe what you're testing (e.g., `MyFeature.Test.ps1`)
71+
2. Import the module or script you want to test at the beginning of your test file
72+
3. Use `Describe` blocks to group related tests
73+
4. Use `It` blocks for individual test cases
74+
5. Use `BeforeAll` for setup that runs once before all tests in a `Describe` block
75+
6. Use `Mock` to mock external dependencies and function calls
76+
77+
**Example test structure:**
78+
79+
```powershell
80+
Import-Module (Join-Path $PSScriptRoot '../Actions/.Modules/MyModule.psm1') -Force
81+
82+
Describe "MyFeature tests" {
83+
BeforeAll {
84+
# Setup code that runs once
85+
}
86+
87+
It 'Should do something specific' {
88+
# Arrange
89+
Mock Write-Host { }
90+
91+
# Act
92+
$result = MyFunction -Parameter "value"
93+
94+
# Assert
95+
$result | Should -Be "expected"
96+
}
97+
}
98+
```
99+
100+
**Best practices for unit tests:**
101+
102+
- Test one thing per `It` block
103+
- Use descriptive test names that explain what is being tested
104+
- Mock external dependencies to isolate the code under test
105+
- Clean up temporary files and folders created during tests
106+
- Use `InModuleScope` when you need to test private functions within a module
107+
108+
**Running unit tests locally:**
109+
110+
```powershell
111+
# Run all unit tests
112+
pwsh -File Tests/runtests.ps1 -Path Tests
113+
114+
# Or run from VS Code by opening Tests/runtests.ps1 and selecting Run
115+
```
116+
117+
The CI workflow automatically runs all unit tests on both Windows (PowerShell 5) and Linux (PowerShell 7) when you create a pull request.
118+
50119
## End to End tests
51120

52121
In the e2eTests folder, in the AL-Go repository, there are 3 types of end to end tests.

0 commit comments

Comments
 (0)