You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Want to do the same, but for a project using [pytest](https://pytest.org)? Easy
19
+
(because it's the same!):
20
+
21
+
```
22
+
export TEP_TESTS_TO_RUN="my test"
23
+
run-tests pytest
24
+
```
25
+
26
+
Check out [RFC 0001](./protocol/rfcs/0001/README.md) for the motivation behind
27
+
universal-test-runner and the Test Execution Protocol, and why it's useful to
28
+
have a common interface for passing arguments to test runners.
29
+
30
+
## 🤔 When should I use universal-test-runner?
31
+
32
+
You should install universal-test-runner in the following cases:
33
+
34
+
* Your IDE or CI/CD system tells you to, in order for it to support running tests according to the [Test Execution Protocol](./protocol/README.md)
35
+
* You're developing an adapter for universal-test-runner, and you want to test it out
36
+
* You're writing a custom adapter for use with your project setup, and you want to test it out
37
+
38
+
## 📈 Frameworks and build tool support
39
+
14
40
First-party test adapter support is provided for the following frameworks/build tools:
15
41
16
-
* Jest
17
-
* Pytest
18
-
* Maven
19
-
* Gradle
20
-
* ... and more to come!
42
+
* Jest: https://jestjs.io/
43
+
* Pytest: https://pytest.org
44
+
* Maven: https://maven.apache.org/
45
+
* Gradle: https://gradle.org/
46
+
47
+
See the [1.0.0 milestone](https://github.com/aws/codeaws-test-runner/milestone/1)
48
+
for all features planned for v1.0.0, and all frameworks and build tools we plan
49
+
to support for v1.0.0.
50
+
51
+
## 🔋 Custom adapters
52
+
53
+
It's possible to write custom adapters and pass them to universal-test-runner,
54
+
providing support for new frameworks or custom testing setups. See the docs on
55
+
[writing custom adapters](#writing-adapters) for how to implement one.
21
56
22
-
It's also possible to write custom adapters and pass them to the runner,
23
-
providing support for custom testing setups, or frameworks that don't already
24
-
have a first-party or third-party adapter:
57
+
If you write a custom adapter, please host it in its own GitHub repo and
58
+
publish it to npm; then [open a pull request](https://github.com/aws/codeaws-test-runner/compare) to add it to our
59
+
[list of known third-party adapters](TODO), so everyone can benefit. (Note that we
60
+
won't be adding the source code of third-party adapters directly to this repo.)
61
+
62
+
Example of using a third-party adapter from npm:
25
63
26
64
```
27
-
run-tests ./my-customer-adapter.js
65
+
npm install -g my-awesome-adapter
66
+
run-tests my-awesome-adapter
67
+
```
68
+
69
+
If you have a specific project setup that you don't think merits a generic
70
+
third-party adapter, you can pass an adapter from a local file:
71
+
72
+
```
73
+
run-tests ./my-local-adapter.js
28
74
```
29
75
30
76
If universal-test-runner doesn't suit your needs exactly, you can use it as an
31
-
example of how to write your own Test Execution Protocol-aware runner. See
32
-
the [Test Execution Protocol](./protocol/README.md) docs for more info.
77
+
example of how to write your own Test Execution Protocol-aware runner. See the
78
+
[writing custom runners](#custom-runners) and the
79
+
[Test Execution Protocol](./protocol/README.md) docs for more info.
80
+
81
+
## 👩💻 Writing adapters
33
82
34
-
## Test Adapters
83
+
Test adapters are responsible for executing tests as specified by the Test
84
+
Execution Protocol, and reporting the status of the test execution back to the
85
+
universal-test-runner. The runner will do all the work of parsing the protocol
86
+
environment variables, and then invoke the `executeTests` function exposed by
87
+
the adapter.
35
88
36
-
Test adapters are responsible for executing the tests and reporting the status
37
-
of the test execution back to the runner. Adapters must expose a function
38
-
`executeTests` that accepts an object as its argument, and returns a result
39
-
object. If there's an error that prevents tests from being executed, the
40
-
adapter should throw an error. The adapter can also return a promise. A promise
41
-
resolved with the result object indicates that the tests were executed, while a
42
-
rejected promise indicates that there was an error that prevented the tests
43
-
from being executed.
89
+
* The `executeTests` function must accept an input object of type [`AdapterInput`](./packages/universal-test-runner-types/src/index.ts)
90
+
* The `executeTests` function must return an ouput object of type [`AdapterOutput`](./packages/universal-test-runner-types/src/index.ts) or `Promise<AdapterOutput>`.
91
+
* If the adapter executes the tests successfully, and the test run passes, `executeTests` should return an exitCode of `0` (or a promise resolved with an exitCode of `0`).
92
+
* If the adapter executes the tests successfully, and the test run fails, `executesTests` should return a non-zero exitCode (or a promise resolved with a non-zero exitCode).
93
+
* If the adapter cannot execute the tests due to an unrecoverable error, `executeTests` should throw an error (or return a rejected promise).
94
+
95
+
Two simple adapters are shown below, with the details of test execution omitted:
44
96
45
97
```javascript
46
98
// adapter.js
@@ -70,11 +122,32 @@ The adapter is passed to the runner as follows:
70
122
run-tests ./adapter.js
71
123
```
72
124
73
-
## Custom runners
125
+
### Publishing adapters to npm
126
+
127
+
Structure your adapter as described above, and make sure the `main` field in your package.json points to a file that exports an `executeTests` function.
128
+
129
+
## 🏃♀️ Custom runners
74
130
75
131
TODO
76
132
77
-
## Local development setup
133
+
## 🔀 Contributing
134
+
135
+
Please see the [contributing guide](./CONTRIBUTING.md) for all the logistical
136
+
details. Read the existing issues and pull requests before starting to make any
137
+
code changes; large changes that haven't been discussed will be rejected
138
+
outright in favour of small, incremental changes, so please open an issue early
139
+
to discuss anything that may be non-trivial before development starts.
140
+
141
+
All changes to the Test Execution Protocol must follow the [RFC process](./protocol/README.md).
142
+
143
+
### Local development setup
144
+
145
+
[Fork](https://github.com/aws/codeaws-test-runner/fork) the repository, and then clone your fork:
Make sure you're using the correct Node.js version (install nvm [here](https://github.com/nvm-sh/nvm) if needed):
80
153
@@ -94,4 +167,10 @@ Run tests
94
167
npm test
95
168
```
96
169
97
-
To run the pre-commit hook, you'll have to install [TruffleHog](https://github.com/trufflesecurity/trufflehog).
170
+
Run integration tests (you may have to install some of the frameworks and build tools manually to get these to pass locally):
171
+
172
+
```
173
+
npm run test:integ
174
+
```
175
+
176
+
Make your changes and commit them. To run the pre-commit hook, you'll have to install [TruffleHog](https://github.com/trufflesecurity/trufflehog). Push the changes to your fork, and open a pull request.
0 commit comments