Skip to content

Commit c6a62f6

Browse files
GuldemGuldem
committed
📝 Improved readme and minor fixes
1 parent cd0bee3 commit c6a62f6

File tree

8 files changed

+353
-299
lines changed

8 files changed

+353
-299
lines changed

‎README.md‎

Lines changed: 163 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -23,151 +23,85 @@ Supercharge your Dart testing with **parameterized_test**! Built on top of the [
2323
* [How it works](#how-it-works)
2424
* [Additional information](#additional-information)
2525

26-
## Features ✨
26+
## ✨ Features
2727

2828
- ✅ Run a test multiple times based on provide parameter list.
29-
- ✅ Uses [dart test package](https://pub.dev/packages/test) under the hood.
29+
- ✅ Built on top of [dart test package](https://pub.dev/packages/test).
3030
- ✅ Type cast test parameters used in the tests.
3131
- ✅ Include test options for parameter_test.
32-
- ✅ Include test options per parameters.
32+
- ✅ Include test options per parameter.
3333

34-
- ❌ No CSV parsing is supported. Its only possible to use Lists with actual values.
35-
36-
## Installation
34+
## 🛠 Installation
3735

3836
```yaml
3937
dev_dependencies:
4038
parameterized_test: [latest-version]
4139
```
4240
43-
## Usage
44-
45-
Instead of using `groups` or `test` you can now use `parameterizedTest` and supply it list of test parameters to use in the same test.
46-
To specify the test body use `TestParametersX` that matches the same amount of test parameters for 1 test. For example when the test has 2 parameters `actual` and `expected` use `TestParameters2` for supplying the test body.
47-
The package offers `TestParameters` classes up to 10 parameters. Instead of writing `TestParameters` completely it also possible to use `typedef`'s `p1`..`p10`.
48-
49-
## Examples
50-
51-
Example parameterizedTest with 1 parameter:
52-
53-
```dart
54-
parameterizedTest(
55-
'Number are less than 4 tests',
56-
[
57-
1,
58-
2,
59-
3,
60-
],
61-
p1((int number) {
62-
final result = number < 4;
63-
expect(result, true);
64-
}),
65-
);
66-
```
41+
## ⚡️ Usage
6742
68-
Example parameterizedTest with 2 parameters:
43+
Instead of creating a `group` test with multiple of the same `test` and different parameters, you can now use `parameterizedTest` and supply it list of test parameters to run the same test with multiple times.
44+
Specifying a parameterized test is almost the same as normal test. It has all the same parameters as a normal test like: `skip` or `testOn` etc.
45+
The only difference is that you need to provide a list of test values and a function that takes the same amount of arguments as the test values.
6946

47+
For example:
7048
```dart
7149
parameterizedTest(
72-
'Amount of letters tests',
73-
[
74-
['kiwi', 4],
75-
['apple', 5],
76-
['banana', 6],
77-
],
78-
p2((String word, int length) {
79-
expect(word.length, length);
80-
}),
81-
);
82-
```
83-
84-
or
85-
86-
```dart
87-
parameterizedTest2(
88-
'Amount of letters tests',
50+
'Fruit name matches length',
51+
// List of values to test
8952
[
53+
// parameters for the test
9054
['kiwi', 4],
9155
['apple', 5],
9256
['banana', 6],
57+
['pineapple', 9],
9358
],
94-
(String word, int length) {
95-
expect(word.length, length);
59+
// Test function accepting the provided parameters
60+
(String fruit, int length) {
61+
expect(fruit.length, length);
9662
},
9763
);
9864
```
99-
100-
Example parameterizedTest with extra test options for a value:
101-
102-
```dart
103-
parameterizedTest(
104-
'Amount of letters',
105-
[
106-
['kiwi', 4],
107-
['apple', 5],
108-
['banana', 6].withTestOptions(skip: true),
109-
],
110-
p2((String word, int length) {
111-
expect(word.length, length);
112-
}),
113-
);
65+
This `parameterizedTest` will create a `group` with 4 `test` inside it. Each test will run the test function with the provided parameters.
11466
```
115-
116-
Example parameterizedTest with test enum values:
117-
118-
```dart
119-
enum AwesomeEnum { such, woow, much, skill}
120-
121-
parameterizedTest(
122-
'Doge enum tests',
123-
AwesomeEnum.values,
124-
p1((AwesomeEnum doge) {
125-
final result = doge.name.length >= 4;
126-
expect(result, true);
127-
}),
128-
);
67+
- Fruit name matches length (group)
68+
- [ 'kiwi', 4 ] (test)
69+
- [ 'apple', 5 ] (test)
70+
- [ 'banana', 6 ] (test)
71+
- [ 'pineapple', 9 ] (test)
12972
```
13073
131-
## How it works
74+
There is also a `parameterizedGroup` which is basically the same as `parameterizedTest` but instead of creating a `group` that runs a `test` multiple times, it creates a `group` that runs a `group` multiple times.
75+
Here you still need to provide a `test`. This can be useful if you want to have nested groups of tests.
76+
77+
Besides accepting a list of test values, you can also provide a `setUp` and `tearDown` function to run before and after each test.
13278
133-
`parameterized_test` is basically a wrapper that executes a `group` test and loops over the provide `List` of test values. Each set of values is cast to the specified type inside the body. Which is wrapped inside a `test`.
79+
## 🔩 Add test options to parameter
80+
If you want to add test options to a specific parameter you can do so by using the `options` extension on `List`. This will allow you to add test options like `skip` or `testOn` to a specific parameter.
13481
82+
For example:
13583
```dart
13684
parameterizedTest(
137-
'Amount of letters',
85+
'Fruit name matches length',
86+
// List of values to test
13887
[
88+
// parameters for the test
13989
['kiwi', 4],
140-
['apple', 5],
90+
['apple', 5].options(skip: 'Apple is not ripe yet'),
14191
['banana', 6],
92+
['pineapple', 9],
14293
],
143-
p2((String word, int length) {
144-
expect(word.length, length);
145-
}),
94+
// Test function accepting the provided parameters
95+
(String fruit, int length) {
96+
expect(fruit.length, length);
97+
},
14698
);
14799
```
148100

149-
The above example roughly translates to:
150-
```dart
151-
group('Amount of letter', () {
152-
final testValues = [
153-
['kiwi', 4],
154-
['apple', 5],
155-
['banana', 6],
156-
];
101+
This will create a `group` with 4 `test` inside it. The second test will receive the provided test options and will be skipped in this case.
157102

158-
for (final testValue in testValues) {
159-
test(testValue.toString(), () {
160-
final String word = testValue[0] as String;
161-
final int length = testValue[1] as int;
162-
163-
expect(word.length, length);
164-
});
165-
}
166-
});
167-
```
168-
169-
## Changing test description output
170-
By default the test description contains the test value used within the tests. This can be override by using `customDescriptionBuilder`.
103+
## 📝 Changing test description output
104+
By default, the test description contains the test value used within the tests. you can override this by using `customDescriptionBuilder`.
171105

172106
When normally running parameterized tests with description 'My parameterized test' and the values `[['first', 'second', true], ['third', 'fourth', false]]` the test description output looks something like this:
173107
```
@@ -190,31 +124,135 @@ My parameterized test 🚀[2] My parameterized test: <<third|fourth|false>>
190124

191125
>Note: the first 'My parameterized test' is because parameterized tests make use of a group test. Most IDE's will group this for you and only show the second part.
192126
193-
## Extending parameters
127+
## 📦 Examples
128+
### Simple test containing a list of single values
129+
```dart
130+
parameterizedTest(
131+
'Example of list of single values',
132+
[
133+
1,
134+
2,
135+
3,
136+
],
137+
(int value) {
138+
final result = value < 4;
139+
expect(result, true);
140+
},
141+
);
142+
```
194143

195-
Currently the package supports `TestParameters` classes up to 10 arguments. If need to more arguments within a test than this is possible by implementing the `TestParameters` class.
144+
### Simple test containing a list of multiple values
145+
```dart
146+
parameterizedTest('Example of list of multiple values', [
147+
[0, 1, 1],
148+
[1, 1, 2],
149+
[1, 2, 3],
150+
[2, 2, 4],
151+
], (int value1, int value2, int sum) {
152+
expect(value1 + value2, sum);
153+
});
154+
```
155+
### Test containing a list with complex objects
156+
```dart
157+
parameterizedTest('Example of a list with complex object', [
158+
[DateTime(2024, 4, 12), 5],
159+
[DateTime(1969, 07, 20), 7],
160+
], (DateTime dateTime, int expectedWeekday) {
161+
expect(dateTime.weekday, expectedWeekday);
162+
});
163+
```
196164

197-
For example:
165+
### Test containing a list of enums
198166
```dart
199-
class MyParameters<A1, A2> implements TestParameters {
200-
const MyParameters(this.body);
167+
enum TestEnum {
168+
one(3),
169+
two(3),
170+
three(5);
201171
202-
@override
203-
final dynamic Function(A1, A2) body;
172+
const TestEnum(this.myLength);
204173
205-
@override
206-
final int count = 2;
174+
final int myLength;
175+
}
207176
208-
@override
209-
dynamic mapBody<R>(Iterable<R> values) {
210-
final A1 a1 = values.elementAt(0) as A1;
211-
final A2 a2 = values.elementAt(1) as A2;
212-
return body(a1, a2);
213-
}
177+
parameterizedTest(
178+
'Example using enum as value',
179+
TestEnum.values,
180+
(TestEnum testEnum) {
181+
expect(testEnum.name.length, testEnum.myLength);
182+
},
183+
);
184+
```
185+
### Test retreiving the list of values from a function
186+
```dart
187+
List<dynamic> provideData() {
188+
return [
189+
[0, 1, 1],
190+
[1, 1, 2],
191+
[1, 2, 3],
192+
[2, 2, 4],
193+
];
214194
}
195+
196+
parameterizedTest(
197+
'Example of list of values from function',
198+
provideData(),
199+
(int value1, int value2, int sum) {
200+
expect(value1 + value2, sum);
201+
},
202+
);
203+
```
204+
205+
### Simple test with setup and teardown
206+
```dart
207+
parameterizedTest(
208+
'Example with setup and teardown ',
209+
[
210+
['kiwi', 4],
211+
['apple', 5],
212+
['banana', 6],
213+
],
214+
(String word, int length) {
215+
expect(word.length, length);
216+
},
217+
setUp: () {
218+
print('Setup everything I need for testing');
219+
},
220+
tearDown: () {
221+
print('tear it down again');
222+
},
223+
);
224+
```
225+
226+
### Test which is an async test
227+
```dart
228+
parameterizedTest(
229+
'Example using a async test',
230+
[
231+
100,
232+
200,
233+
300,
234+
],
235+
(int value) async {
236+
final millis = DateTime.now().millisecondsSinceEpoch;
237+
await Future<void>.delayed(Duration(milliseconds: value));
238+
final passed = DateTime.now().millisecondsSinceEpoch - millis;
239+
240+
expect(passed >= value, true);
241+
},
242+
);
243+
```
244+
### Test with CSV data
245+
Its also possible to combine parameterizedTest for example with the [csv](https://pub.dev/packages/csv) package.
246+
247+
```dart
248+
parameterizedTest('Example of CSV data',
249+
const CsvToListConverter().convert('kiwi,4\r\napple,5\r\nbanana,6'),
250+
(String fruit, int length) {
251+
expect(fruit.length, length);
252+
});
215253
```
216254

217-
## Additional information
255+
## 💡 Additional information
218256

219-
Its just a simple wrapper to easily execute tests multiple times with different values. Feel free to
220-
leave some feedback or open an pull request :)
257+
It's just a simple wrapper to easily execute tests multiple times with different values. Feel free to
258+
leave some feedback or open a pull request :)

0 commit comments

Comments
 (0)