Proposed updates to Terminal Testing article (#145)
* Proposed updates for run-test-terminal article * Update run-test-terminal.md * Add example showing running scenario from URL. Add callout showing where the prism binary will be installed to.
This commit is contained in:
Ross McDonald
committed by
Robert Wallach
Robert Wallach
parent
aaf2cfe2fe
commit
1c17bf6e19
@@ -1,80 +1,75 @@
|
||||
# Running a Scenario from Terminal
|
||||
# Running Prism from the Terminal
|
||||
|
||||
It is very easy to run scenario collections, or individual scenarios, on your own computer, completely outside of the Scenarios app.
|
||||
|
||||
First, install Prism, our command line tool for running scenarios.
|
||||
|
||||
*On macOs or Linux:*
|
||||
```
|
||||
_On macOS or Linux:_
|
||||
|
||||
```bash
|
||||
curl https://raw.githubusercontent.com/stoplightio/prism/2.x/install.sh | sh
|
||||
```
|
||||
|
||||
*On Windows:*
|
||||
<!-- theme: info -->
|
||||
|
||||
> When installed through the installation script, Prism will be installed to `/usr/local/bin/prism`
|
||||
|
||||
_On Windows:_
|
||||
|
||||
```
|
||||
Download from https://github.com/stoplightio/prism/tree/2.x
|
||||
```
|
||||
|
||||
After installing, you should be able to run `prism -h` (or `prism.exe -h` in Windows) and see some help text.
|
||||
After installing, you should be able to run `prism -h` (or `prism.exe -h` in Windows) from your CLI and see the Prism help text.
|
||||
|
||||
The Scenario app has a convenient display that gives you the exact command required to run the collection or scenario that you are viewing, taking into account your current environment variables. If you have the Scenario editor connected to a local file on your computer, it will use the path to that file, otherwise it will use the Scenario SRN (unique identifier).
|
||||
The Scenario app has a convenient display that gives you the exact command required to run the collection or scenario that you are viewing (taking into account your current environment variables). If you have the Scenario editor connected to a local file on your computer, it will use the path to that file, otherwise it will use the Scenario SRN (unique identifier).
|
||||
|
||||
<!-- theme: warning -->
|
||||
|
||||
> Keep in mind that if you are storing your Scenarios on Stoplight's servers, and running them from the command line, you must save them in the Stoplight app before running! This is because Prism will make a call to the Stoplight API to fetch your Scenario JSON, which it will then run from your computer.
|
||||
|
||||
See below for a screenshot of the "Run From Terminal" command generator. The command in this box will update live in response to environment, user, and scenario changes.
|
||||
|
||||
|
||||
<!-- FIXME: image showing "Run from Terminal" option under a scenario -->
|
||||
|
||||
## Running Local Files
|
||||
## Running Scenarios
|
||||
|
||||
The `prism conduct` command accepts a filepath. So, if you are working with [local scenario collection](#docTextSection:Ap4Z2B7RgbbLFLjJD) .json files, you can run them with something like:
|
||||
To run a local Scenario, you can use the `prism conduct` command. The `conduct`
|
||||
command accepts either a local file path or URL. If you are working with a local
|
||||
Scenario `collection.json` file, you can run the Scenario using the following
|
||||
command:
|
||||
|
||||
```bash
|
||||
# Run a local scenario
|
||||
prism conduct /path/to/collection.json
|
||||
|
||||
# Run a remote scenario by URL
|
||||
prism conduct "https://export.stoplight.io/1234/master/main.scenarios.yml"
|
||||
```
|
||||
|
||||
## Including Specs For Contract Testing
|
||||
For more information on Scenarios and how they can be used, see [here](./scenarios-introduction.md).
|
||||
|
||||
If you are using [contract testing](#docTextSection:tFWniZdshJYLLtKms), you will need to include the filepath to the API specification as part of the command. This is what that looks like:
|
||||
## Contract Testing
|
||||
|
||||
To use Prism for contract testing (or API validation), you can use the `prism validate` command.
|
||||
The `validate` command takes a `--spec` argument, which is either a file path or URL to an OpenAPI specification file.
|
||||
To run a contract test against the default API URL set in the specification, use the command:
|
||||
|
||||
```bash
|
||||
prism conduct myOrg/scenarios/myScenarios --spec /path/to/my/swagger.json
|
||||
prism validate --spec /path/to/my/spec.json
|
||||
```
|
||||
|
||||
## Continuous integration
|
||||
You can also run a contract test against a specific upstream URL with the
|
||||
`--upstream` argument.
|
||||
|
||||
Most CI products (Circle CI, Travis, Jenkins, Codship, etc) generally function in the same way: setup environment, invoke commands to run tests. With Scenarios + Prism, the process is similar. Install Prism, and then configure the CI process to run the appropriate Prism command. We've included instructions for Circle CI below, but these concepts should loosely apply to other CI products.
|
||||
|
||||
#### Circle CI
|
||||
|
||||
Integrating [Prism](http://stoplight.io/platform/prism) into Circle CI is easy. All you need to do is install Prism and overide the test command.
|
||||
|
||||
To install Prism just add a dependency to your circle config.
|
||||
|
||||
|
||||
``` yaml
|
||||
dependencies:
|
||||
pre:
|
||||
- curl https://raw.githubusercontent.com/stoplightio/prism/2.x/install.sh | sh
|
||||
```bash
|
||||
prism validate --spec /path/to/my/spec.json --upstream http://localhost:8080
|
||||
```
|
||||
|
||||
For more information on contract testing and how it can be used, see [here](./contract-testing.md).
|
||||
|
||||
Then override the default test command for circle in your config.
|
||||
## Related
|
||||
|
||||
|
||||
``` yaml
|
||||
test:
|
||||
override:
|
||||
- prism conduct orgId/scenarios/scenarioId
|
||||
```
|
||||
|
||||
When running `prism conduct` you can:
|
||||
|
||||
- Use the Scenario SRN, as displayed above.
|
||||
- Include the Scenario JSON on your CI server, and pass in its absolute file path
|
||||
- Pass in the absolute URL to the scenario JSON served up via HTTP.
|
||||
|
||||
<!-- theme: warning -->
|
||||
> Don't forget to pass in any required environment values with the --env command line flag (or you can provide the filepath to a json file with your environment variables)!
|
||||
|
||||
For convenience, you can find the full command to run your scenario collection or individual scenario in the Stoplight app.
|
||||
* [Scenarios Overview](./scenarios-introduction.md)
|
||||
* [Contract Testing Overview](./contract-testing.md)
|
||||
* [Integrating Prism into a CI Pipeline](./continuous-integration.md)
|
||||
|
||||
Reference in New Issue
Block a user