various fixes in the documentation (#123)

This commit is contained in:
Pantazis Deligiannis 2021-03-01 10:58:12 -08:00 коммит произвёл GitHub
Родитель 3ef56f0403
Коммит ff34b1d868
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
11 изменённых файлов: 186 добавлений и 173 удалений

Просмотреть файл

@ -8,7 +8,7 @@ the github repo</a>
### Prerequisites
- [.NET Core SDK 5.0](https://dotnet.microsoft.com/download/dotnet-core)
- [.NET 5.0 SDK](https://dotnet.microsoft.com/download/dotnet-core)
**Optional:**

Просмотреть файл

@ -4,7 +4,7 @@ Coyote is a NuGet library and works on .NET Core which means it can be used on W
macOS.
### Prerequisites
- [.NET Core SDK 5.0](https://dotnet.microsoft.com/download/dotnet-core)
- [.NET 5.0 SDK](https://dotnet.microsoft.com/download/dotnet-core)
**Optional:**
@ -62,17 +62,8 @@ dotnet tool uninstall --global Microsoft.Coyote.CLI
```
**Note:** this command line tool is only for .NET Core. If you need a version of `coyote.exe` that
runs on .NET Framework 4.7 or 4.8, this is installed from the `Microsoft.Coyote.Test` package, and
you can run it from the bin folder of your Coyote application.
### Building the samples
Clone the [Coyote samples repo](http://github.com/microsoft/coyote-samples), then use the following
`PowerShell` command line from a Visual Studio 2019 Developer Command Prompt:
```plain
powershell -f build.ps1
```
runs on .NET Framework, this is installed from the `Microsoft.Coyote.Test` package, and you can run
it from the bin folder of your Coyote application.
### Troubleshooting

Просмотреть файл

@ -1,91 +1,30 @@
## Using Coyote
As shown in the [overview](../index.md), there are two main ways to use Coyote.
The simplest is to use the [asynchronous tasks](../advanced-topics/tasks/overview.md) and the
more advanced way is using the [asynchronous actors](../advanced-topics/actors/overview.md).
Assuming you have [installed Coyote](install.md), the best place to get started is by following
[this tutorial](../tutorials/first-concurrency-unit-test.md) to learn how to write your first
concurrency unit test, which is also available as a [video on
YouTube](https://youtu.be/wuKo-9iRm6o).
**Note:** If you are upgrading to Coyote from P#, see [upgrading from
P#](upgrade-from-psharp.md).
Once you are ready to dive in, you read the [core concepts](../concepts/non-determinism.md) behind
Coyote and how it can be used to [test the concurrency in your
code](../concepts/concurrency-unit-testing.md).
Assuming you have [installed Coyote](install.md) and built the samples, you
are ready to use the `coyote` command line tool. In your [Coyote
samples](http://github.com/microsoft/coyote-samples) local repo you can find the compiled binaries
in the `bin` folder. Here we assume you are using the [.NET 5.0 version of the `coyote` tool](install.md#installing-the-net-core-31-coyote-tool).
There are many tutorials and samples available for you to explore Coyote further!
You can use the `coyote` tool to automatically test these samples and find bugs. There is a
particularly hard bug to find in the `coyote-samples/Monitors` sample application. If you run this
application from your command prompt it will write output forever. It seems perfectly happy,
right? But there is a bug that happens rarely, the kind of pesky bug that would keep you up late at
night scratching your head.
Ok then, let's see if Coyote can find the bug. Type `coyote -?` to see the help page to make sure
you have installed it correctly. Now you are ready to run a `coyote` test as follows:
To build the samples, clone the [Coyote samples repo](http://github.com/microsoft/coyote-samples),
then use the following `PowerShell` command line from a Visual Studio 2019 Developer Command Prompt:
```plain
cd coyote-samples
coyote test ./bin/net5.0/Monitors.dll --iterations 1000 --max-steps 200
powershell -f build.ps1
```
This also runs perfectly up to 1000 iterations. So this is indeed a hard bug to find. It can be
found using the `PCT` exploration strategy with a given maximum number of priority switch points
`--sch-pct` (or with the default `Random` exploration strategy, but with a much larger number of
iterations, typically more than 100,000 of them).
In your local [Coyote samples](http://github.com/microsoft/coyote-samples) repo you can find the
compiled binaries in the `bin` folder. You can use the `coyote` tool to automatically test these
samples and find bugs. Read how to use the tool [here](../tools/rewriting.md).
```plain
coyote test ./bin/net5.0/Monitors.dll --iterations 1000 --max-steps 200 --sch-pct 10
```
Optionally, you can try out the advanced [actor and state
machine](../advanced-topics/actors/overview.md) programming model of Coyote, which allows you to
build a highly-reliable system from scratch using lightweight concurrency primitives that are
battle-tested inside Azure.
Even then you might need to run it a few times to catch the bug. Set `--iterations` to a bigger
number if necessary. You can also let `coyote` decide which exploration strategy to use. Just use
`--sch-portfolio` and size `--parallel N` and Coyote will run `N` different exploration strategies
for you, in parallel. `coyote` manages the portfolio to give you the best chance of revealing bugs.
These strategies were developed from real-world experience on large products in Microsoft Azure.
When you use the right scheduling strategy, you will see a bug report:
```plain
... Task 0 found a bug.
... Emitting task 0 traces:
..... Writing .\bin\net48\Output\Monitors.exe\CoyoteOutput\Monitors_0_0.txt
..... Writing .\bin\net48\Output\Monitors.exe\CoyoteOutput\Monitors_0_0.schedule
```
The `*.txt` file is the text log of the iteration that found the bug. The `*.schedule` contains the information needed to reproduce the bug.
Finding a hard to find bug is one thing, but if you can't reproduce this bug while debugging there
is no point. So the `*.schedule` can be used with the `coyote replay` command as follows:
```plain
coyote replay ./bin/net5.0/Monitors.dll .\bin\net48\Output\Monitors.exe\CoyoteOutput\Monitors_0_0.schedule
. Reproducing trace in coyote-samples\./bin/net48/Monitors.exe
... Reproduced 1 bug.
... Elapsed 0.1724228 sec.
```
Attach a debugger during replay and you can see what exactly is going wrong.
You might be wondering what the `Monitors` sample app is really doing. The `coyote` command line
tool can help you with that also. If you run the following command line it will produce a [DGML
diagram](../tools/dgml.md) of the state machines that are being tested:
```plain
coyote test ./bin/net5.0/Monitors.dll --iterations 10 --max-steps 20 --graph
```
You will see the following output:
```plain
... Emitting graph:
..... Writing .\bin\net48\Output\Monitors.exe\CoyoteOutput\Monitors_0_1.dgml
```
Open the DGML diagram using Visual Studio 2019 and you will see the following:
![monitors](../assets/images/Monitors.svg)
Download the [Monitors.dgml](../assets/images/Monitors.dgml) file to view it
interactively using Visual Studio. Make sure the downloaded file keeps the file extension `.dgml`.
Use CTRL+A to select everything and this will show you all the detailed links as well.
You are now ready to dive into the core concepts for using Coyote to test [async
tasks](../advanced-topics/tasks/overview.md) and the more advanced [async
actors](../advanced-topics/actors/overview.md).
**Note:** If you are upgrading to Coyote from P#, see [upgrading from P#](upgrade-from-psharp.md).

4
docs/index.md поставляемый
Просмотреть файл

@ -104,14 +104,14 @@ Get started with the following links:
[Install the NuGet package and CLI tool, it is super easy](get-started/install.md)
[Read how various Azure teams are using Coyote](case-studies/azure-batch-service.md)
[Write your first concurrency unit test with Coyote](tutorials/first-concurrency-unit-test.md)
[Check out this cool demo showing Coyote in practice](advanced-topics/actors/state-machine-demo/)
[Learn the core concepts behind Coyote](concepts/non-determinism.md)
[Read how various Azure teams are using Coyote](case-studies/azure-batch-service.md)
[Say hello on Gitter](https://gitter.im/Microsoft/coyote)
[Contribute on Github](https://github.com/microsoft/coyote/)

Просмотреть файл

@ -9,6 +9,38 @@
I'm glad you asked. See [how does it work](how.md).
<br/><br/>
#### What programming languages does Coyote support?
Coyote currently only supports C#.
<br/><br/>
#### Is Coyote only available with Azure?
No, Coyote can run in any Windows or Linux machine, regardless if it is a local machine or a VM on
the cloud.
<br/><br/>
#### What type of projects will benefit most from using Coyote?
Projects that have to deal with asynchrony/concurrency or other non-deterministic issues (such as
timeouts, failures and re-orderings).
<br/><br/>
#### Will Coyote slow down my production code?
No, Coyote testing works on [unmodified code](../concepts/binary-rewriting.md). If you decide to use
the _optional_ Coyote [actors](../advanced-topics/actors/overview.md) API to build your system, then
there is minimal production overhead as Coyote actors were designed to be lightweight (they are
in-memory objects that execute on top of a C# task) and have been battle-tested by several teams
inside Azure.
<br/><br/>
#### At what stage of the development lifecycle is it best to start using Coyote?
Ideally at the very beginning. It is better to do testing while developing, not after you are ready
to ship :)
<br/><br/>
#### Will using Coyote affect the total budget for a software development project?
It will have minimal impact initially, as developers ramp up on Coyote concepts. In the long run,
@ -16,17 +48,6 @@ our experience with Azure teams suggests that it will help reduce the total budg
designed to add agility so that the development and testing processes move at a faster pace.
<br/><br/>
#### What type of projects will benefit most from using Coyote?
Projects that have to deal with concurrency/asynchrony or other non-deterministic issues (such as
timers, failures and re-orderings).
<br/><br/>
#### Will Coyote slow down my production code?
No, Coyote is very lightweight.
<br/><br/>
#### How much time will developers need to learn Coyote?
We have been working hard towards making Coyote accessible to all developers, however, we cannot
@ -36,59 +57,41 @@ things I worked on was Coyote, it was really quick to onboard, writing actual co
straightforward_". Tell us about your experience!
<br/><br/>
#### At what stage of the development lifecycle is it best to start using Coyote?
Ideally at the very beginning, since you need to design and build using Coyote APIs. It is better to
do testing while developing, not after you are ready to ship :)
<br/><br/>
#### How much additional effort is needed to test an existing system with Coyote?
Depends on what programming model and concurrency APIs you used for developing your existing system
because, for Coyote testing to work, it needs to understand the
[non-determinism](../concepts/non-determinism.md) in your system. In some cases, this may be as simple as
replacing the `System.Threading.Tasks.Task` type with
[`Microsoft.Coyote.Tasks.Task`](../advanced-topics/tasks/overview.md). In other cases, you would
also have to model additional non-determinism, such as timers and external services. In general, we
recommend using Coyote in early stages of development.
<br/><br/>
#### How is Coyote being maintained and what level of support can we expect?
Coyote is currently an Open Source project on GitHub under the MIT license. Microsoft continues to
invest in Coyote and accepts community contributions as well. Issues can be posted there and will be
resolved in a timely manner.
[non-determinism](../concepts/non-determinism.md) in your system. If you write your code using
typical task-based APIs in C#, then most likely you do not need to do anything as Coyote testing
works on [unmodified code](../concepts/binary-rewriting.md). In other cases, you would also have to
model additional non-determinism, such as timers and external services. In general, we recommend
using Coyote in early stages of development.
<br/><br/>
#### How do Coyote actors compare against other actor frameworks?
See [How are Coyote Actors different from existing Microsoft Actor frameworks?](../advanced-topics/actors/why-actors.md).
Read [how are Coyote Actors different from existing Microsoft Actor frameworks](../advanced-topics/actors/why-actors.md).
<br/><br/>
#### How is Coyote different from other similar systems out there?
One comparison point for Coyote would be other offerings that help build reliable systems. It would
be difficult to give an exhaustive answer here, but Coyote is quite unique in its combination of
powerful testing and very light run-time requirements (i.e., it requires the .NET Core only).
powerful testing and minimal runtime requirements (i.e., it requires the .NET Core only).
Other systems might require a buy-in to a particular distributed runtime or messaging system, or
might not help much in the way of testing custom business logic. You can adapt Coyote to work with
whatever platform you are using today.
<br/><br/>
#### Is Coyote only available with Azure?
#### How many machines do you need to run a Coyote actor-based program?
No, Coyote can run in any Windows or Linux machine, regardless if it is a local machine or a VM on
the cloud.
A Coyote actor-based program is hosted in a .NET process, so it can easily run on just one machine.
You can also create a distributed Coyote actor-based program by connecting multiple processes, each
running Coyote. You are free to use any distributed host platform as well as any messaging system
that you want.
<br/><br/>
#### How many machines do you need to run a Coyote program?
A Coyote program is hosted in a .NET process, so it can easily run on just one machine. You can also
create a distributed Coyote program by connecting multiple processes, each running Coyote. You are
free to use any distributed host platform as well as any messaging system that you want.
<br/><br/>
#### Can Coyote be used with any existing distributed host and communication platform?
#### Can Coyote actors be used with any existing distributed host and communication platform?
Yes, Coyote does not constrain you. Coyote is built on top of the .NET Task Parallel Library, and on
its own only executes in-memory in the scope of a single .NET process. To build a distributed Coyote
program, you are free to use any distributed host and communication mechanism that you like. All you
@ -108,3 +111,10 @@ Sure, in fact most testing with Coyote is performed on a single machine. Many Co
build reliable cloud services, and Coyote itself is not service-specific. You can use it to build
and test any kind of asynchronous .NET program that needs to be reliable.
<br/><br/>
#### How is Coyote being maintained and what level of support can we expect?
Coyote is currently an open source project on GitHub under the MIT license. Microsoft continues to
invest in Coyote and accepts community contributions as well. Issues can be posted there and will be
resolved in a timely manner.
<br/><br/>

Просмотреть файл

@ -1,4 +1,4 @@
## Coyote rewriting tool
## Rewriting binaries for testing with Coyote
The `coyote` command line tool can be used to automatically rewrite any .NET binary to take over
concurrency that is built using `System.Threading.Tasks.Task`. For details on what kinds of
@ -21,12 +21,11 @@ version of `coyote` then you simply run `dotnet coyote.dll ...` instead.
### Example usage
The [BoundedBuffer example](https://github.com/microsoft/coyote-samples/tree/main/BoundedBuffer)
is written with `System.Threading.Tasks.Task`. It does not start with `using
Microsoft.Coyote.Tasks`. So `BoundedBuffer.cs` is pure .NET C# code that knows nothing about Coyote
The [BoundedBuffer example](https://github.com/microsoft/coyote-samples/tree/main/BoundedBuffer) is
written with `System.Threading.Tasks.Task`.It is is pure C# code that knows nothing about Coyote
types.
However, using `coyote rewrite` we can make it testable under `coyote test` tool as follows:
Using `coyote rewrite` we can make it testable under the `coyote test` tool as follows:
1. Build BoundedBuffer.sln
2. coyote rewrite bin\net5.0\BoundedBuffer.dll

Просмотреть файл

@ -0,0 +1,95 @@
## Bug in failure detector
There is a particularly hard bug to find in the `coyote-samples/Monitors` sample application. If you
run this application from your command prompt it will write output forever. It seems perfectly
happy, right? But there is a bug that happens rarely, the kind of pesky bug that would keep you up
late at night scratching your head. Read further to learn how to find this bug using Coyote!
## What you will need
You will also need to:
- Install [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/).
- Install the [.NET 5.0 version of the coyote tool](../../get-started/install.md).
- Clone the [Coyote Samples git repo](http://github.com/microsoft/coyote-samples).
- Be familiar with the `coyote test` tool. See [Testing](../../tools/testing.md).
## Build the samples
Build the `coyote-samples` repo by running the following command:
```plain
powershell -f build.ps1
```
## Run the sample
Let's see if Coyote can find the bug in this sample. Type `coyote -?` to see the help page to make
sure you have installed it correctly. Now you are ready to run a `coyote` test as follows:
```plain
cd coyote-samples
coyote test ./bin/net5.0/Monitors.dll --iterations 1000 --max-steps 200
```
This also runs perfectly up to 1000 iterations. So this is indeed a hard bug to find. It can be
found using the `PCT` exploration strategy with a given maximum number of priority switch points
`--sch-pct` (or with the default `Random` exploration strategy, but with a much larger number of
iterations, typically more than 100,000 of them).
```plain
coyote test ./bin/net5.0/Monitors.dll --iterations 1000 --max-steps 200 --sch-pct 10
```
Even then you might need to run it a few times to catch the bug. Set `--iterations` to a bigger
number if necessary. You can also let `coyote` decide which exploration strategy to use. Just use
`--sch-portfolio` and size `--parallel N` and Coyote will run `N` different exploration strategies
for you, in parallel. `coyote` manages the portfolio to give you the best chance of revealing bugs.
These strategies were developed from real-world experience on large products in Microsoft Azure.
When you use the right scheduling strategy, you will see a bug report:
```plain
... Task 0 found a bug.
... Emitting task 0 traces:
..... Writing .\bin\net48\Output\Monitors.exe\CoyoteOutput\Monitors_0_0.txt
..... Writing .\bin\net48\Output\Monitors.exe\CoyoteOutput\Monitors_0_0.schedule
```
The `*.txt` file is the text log of the iteration that found the bug. The `*.schedule` contains the
information needed to reproduce the bug.
Finding a hard to find bug is one thing, but if you can't reproduce this bug while debugging there
is no point. So the `*.schedule` can be used with the `coyote replay` command as follows:
```plain
coyote replay ./bin/net5.0/Monitors.dll .\bin\net48\Output\Monitors.exe\CoyoteOutput\Monitors_0_0.schedule
. Reproducing trace in coyote-samples\./bin/net48/Monitors.exe
... Reproduced 1 bug.
... Elapsed 0.1724228 sec.
```
Attach a debugger during replay and you can see what exactly is going wrong.
You might be wondering what the `Monitors` sample app is really doing. The `coyote` command line
tool can help you with that also. If you run the following command line it will produce a [DGML
diagram](../../tools/dgml.md) of the state machines that are being tested:
```plain
coyote test ./bin/net5.0/Monitors.dll --iterations 10 --max-steps 20 --graph
```
You will see the following output:
```plain
... Emitting graph:
..... Writing .\bin\net48\Output\Monitors.exe\CoyoteOutput\Monitors_0_1.dgml
```
Open the DGML diagram using Visual Studio 2019 and you will see the following:
![monitors](../../assets/images/Monitors.svg)
Download the [Monitors.dgml](../../assets/images/Monitors.dgml) file to view it interactively using
Visual Studio. Make sure the downloaded file keeps the file extension `.dgml`. Use CTRL+A to select
everything and this will show you all the detailed links as well.

Просмотреть файл

@ -141,14 +141,6 @@ if (is_top_frame) { $('body').addClass('wm-top-page'); }
<footer class="wm-page-content">
{%- block footer %}
{%- block repo %}
{%- if config.repo_url %}
<p>
<a href="{{ config.repo_url }}">{% include 'repo-icon.html' %}{{ config.repo_name }}</a>
</p>
{%- endif %}
{%- endblock %}
{% include 'footer.html' %}
{%- endblock %}
</footer>

Просмотреть файл

@ -7,7 +7,6 @@
</div>
</div>
<div class="row">
</div>
</div>
</section>
@ -24,11 +23,8 @@
<nav>
<h4>Coyote</h4>
<ul class="list-unstyled">
<li><a href="{{ base_url }}">Home</a></li>
<li><a href="{{ base_url }}overview/about">About</a></li>
</ul>
</nav>
</div>
@ -37,11 +33,8 @@
<nav>
<h4>Resources</h4>
<ul class="list-unstyled">
<li><a href="{{ base_url }}get-started/install">Install</a></li>
<li><a href="{{ base_url }}get-started/using-coyote">Getting started</a></li>
</ul>
</nav>
</div>
@ -50,15 +43,12 @@
<nav>
<h4>Community</h4>
<ul class="list-unstyled">
<li><a href="https://github.com/microsoft/coyote" target="_blank">GitHub</a></li>
<li><a href="{{ config.repo_url }}">{% include 'repo-icon.html' %}{{ config.repo_name }}</a></li>
<li><a href="https://twitter.com/coyote_dev" target="_blank"><i class="fa fa-twitter"></i> Twitter</a></li>
<li><a href="https://gitter.im/microsoft/coyote" target="_blank">Gitter</a></li>
</ul>
</nav>
</div>
</div>
<div class="row footnote pt-50 pb-20">
@ -67,15 +57,10 @@
</div>
<div class="col-sm-6">
<ul class="list-unstyled list-inline footnote-copy">
<li><a href="https://privacy.microsoft.com/en-us/privacystatement/" target="_blank">Privacy</a></li>
<li><a href="https://www.microsoft.com/en-us/legal/intellectualproperty/copyright/default.aspx" target="_blank">Terms of Use</a></li>
<li><a href="https://github.com/microsoft/coyote/blob/main/LICENSE" target="_blank">License</a></li>
<li><a href="javascript:manageCookies()">Cookies</a></li>
</ul>
</div>
<div class="col-sm-6 text-right footnote-copy">

Просмотреть файл

@ -45,13 +45,13 @@ nav:
- Overview:
- Key benefits: overview/benefits.md
- How does it work: overview/how.md
- Frequently asked questions: overview/faq.md
- Videos: overview/videos.md
- Publications: overview/publications.md
- FAQ: overview/faq.md
- Get started with Coyote:
- Installing Coyote: get-started/install.md
- Using Coyote: get-started/using-coyote.md
- Building the source code: get-started/build-source.md
- Building from source: get-started/build-source.md
- Concepts:
- Program non-determinism: concepts/non-determinism.md
- Concurrency unit testing: concepts/concurrency-unit-testing.md
@ -82,11 +82,12 @@ nav:
- Hello world: tutorials/actors/hello-world.md
- Coffee machine failover: tutorials/actors/failover-coffee-machine.md
- Robot navigator failover: tutorials/actors/failover-robot-navigator.md
- Bug in failure detector: tutorials/actors/failure-detector.md
- Raft actor service (on Azure): tutorials/actors/raft-azure.md
- Raft actor service (mocked): tutorials/actors/raft-mocking.md
- Tools:
- Rewriting: tools/rewriting.md
- Testing: tools/testing.md
- Rewriting tool: tools/rewriting.md
- Unit testing: tools/unit-testing.md
- Tester requirements: tools/tester-requirements.md
- Code and activity coverage: tools/coverage.md

Просмотреть файл

@ -45,13 +45,13 @@ nav:
- Overview:
- Key benefits: overview/benefits.md
- How does it work: overview/how.md
- Frequently asked questions: overview/faq.md
- Videos: overview/videos.md
- Publications: overview/publications.md
- FAQ: overview/faq.md
- Get started with Coyote:
- Installing Coyote: get-started/install.md
- Using Coyote: get-started/using-coyote.md
- Building the source code: get-started/build-source.md
- Building from source: get-started/build-source.md
- Concepts:
- Program non-determinism: concepts/non-determinism.md
- Concurrency unit testing: concepts/concurrency-unit-testing.md
@ -82,11 +82,12 @@ nav:
- Hello world: tutorials/actors/hello-world.md
- Coffee machine failover: tutorials/actors/failover-coffee-machine.md
- Robot navigator failover: tutorials/actors/failover-robot-navigator.md
- Bug in failure detector: tutorials/actors/failure-detector.md
- Raft actor service (on Azure): tutorials/actors/raft-azure.md
- Raft actor service (mocked): tutorials/actors/raft-mocking.md
- Tools:
- Rewriting: tools/rewriting.md
- Testing: tools/testing.md
- Rewriting tool: tools/rewriting.md
- Unit testing: tools/unit-testing.md
- Tester requirements: tools/tester-requirements.md
- Code and activity coverage: tools/coverage.md