Refactoring the Testing section

docs/automated-testing/README.md

@@ -1,20 +1,60 @@
 # Testing
 
+## Why testing
+
+- Tests allow us to find flaws in our software
+- Good tests document the code by describing the intent
+- Automated tests saves time, compared to manual tests
+- Automated tests allow us to safely change and refactor our code without introducing regressions
+
+## The fundamentals
+
+- We consider code to be incomplete if it is not accompanied by tests
+- We write unit tests (tests without external dependencies) that can run before every PR merge to validate that we don’t have regressions
+- We write Integration tests/E2E tests that test the whole system end to end, and run them regularly
+- We write our tests early and block any further code merging if tests fail.
+- We run load tests/performance tests where appropriate to validate that the system performs under stress
+
+## Build for testing
+
+Testing is a critical part of the development process.  It is important to build your application with testing in mind.  Here are some tips to help you build for testing:
+
+- **Parameterize everything.** Rather than hard-code any variables, consider making everything a configurable parameter with a reasonable default. This will allow you to easily change the behavior of your application during testing. Particularly during performance testing, it is common to test different values to see what impact that has on performance. If a range of defaults need to change together, consider one or more parameters which set "modes", changing the defaults of a group of parameters together.
+
+- **Document at startup.** When your application starts up, it should log all parameters. This ensures the person reviewing the logs and application behavior know exactly how the application is configured.
+
+- **Log to console.** Logging to external systems like Azure Monitor is desirable for traceability across services. This requires logs to be dispatched from the local system to the external system and that is a dependency that can fail. It is important that someone be able to console logs directly on the local system.
+
+- **Log to external system.** In addition to console logs, logging to an external system like Azure Monitor is desirable for traceability across services and durability of logs.
+
+- **Log all activity.** If the system is performing some activity (reading data from a database, calling an external service, etc.), it should log that activity. Ideally, there should be a log message saying the activity is starting and another log message saying the activity is complete. This allows someone reviewing the logs to understand what the application is doing and how long it is taking. Depending on how noisy this is, different messages can be associated with different log levels, but it is important to have the information available when it comes to debugging a deployed system.
+
+- **Correlate distributed activities.** If the system is performing some activity that is distributed across multiple systems, it is important to correlate the activity across those systems. This can be done using a Correlation ID that is passed from system to system. This allows someone reviewing the logs to understand the entire flow of activity. For more information, please see [Observability in Microservices](../observability/microservices.md).
+
+- **Log metadata.** When logging, it is important to include metadata that is relevant to the activity. For example, a Tenant ID, Customer ID, or Order ID. This allows someone reviewing the logs to understand the context of the activity and filter to a manageable set of logs.
+
+- **Log performance metrics.** Even if you are using App Insights to capture how long dependency calls are taking, it is often useful to know long certain functions of your application took. It then becomes possible to evaluate the performance characteristics of your application as it is deployed on different compute platforms with different limitations on CPU, memory, and network bandwidth. For more information, please see [Metrics](../observability/pillars/metrics.md).
+
+
 ## Map of Outcomes to Testing Techniques
 
-The table below maps outcomes -- the results that you may want to achieve in your validation efforts -- to one or more techniques that can be used to accomplish that outcome.
+The table below maps outcomes (the results that you may want to achieve in your validation efforts) to one or more techniques that can be used to accomplish that outcome.
 
 | When I am working on... | I want to get this outcome... | ...so I should consider |
-|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Development | Prove backward compatibility with existing callers and clients | [Shadow testing](shadow-testing/README.md) | Development; [Integration testing](integration-testing/README.md) | Ensure telemetry is sufficiently detailed and complete to trace and diagnose malfunction in [End-to-End testing](e2e-testing/README.md) flows | Distributed Debug challenges ;  Orphaned call chain analysis |
+| -- | -- | -- |
+| Development | Prove backward compatibility with existing callers and clients | [Shadow testing](shadow-testing/README.md) |
+| Development | Ensure telemetry is sufficiently detailed and complete to trace and diagnose malfunction in [End-to-End testing](e2e-testing/README.md) flows | Distributed Debug challenges; Orphaned call chain analysis |
 | Development | Ensure program logic is correct for a variety of expected, mainline, edge and unexpected inputs | [Unit testing](unit-testing/README.md); Functional tests; [Consumer-driven Contract Testing](cdc-testing/README.md); [Integration testing](integration-testing/README.md) |
-| Development | Prevent regressions in logical correctness; earlier is better | [Unit testing](unit-testing/README.md); Functional tests; [Consumer-driven Contract Testing](cdc-testing/README.md); [Integration testing](integration-testing/README.md); Rings (each of these are expanding scopes of coverage) | | Development                                                       | Quickly validate mainline correctness of a point of functionality (e.g. single API), manually | Manual smoke testing Tools: postman, powershell, curl |
+| Development | Prevent regressions in logical correctness; earlier is better | [Unit testing](unit-testing/README.md); Functional tests; [Consumer-driven Contract Testing](cdc-testing/README.md); [Integration testing](integration-testing/README.md); Rings (each of these are expanding scopes of coverage) |
+| Development | Quickly validate mainline correctness of a point of functionality (e.g. single API), manually | Manual smoke testing Tools: postman, powershell, curl |
 | Development | Validate interactions between components in isolation, ensuring that consumer and provider components are compatible and conform to a shared understanding documented in a contract | [Consumer-driven Contract Testing](cdc-testing/README.md) |
-| Development; [Integration testing](integration-testing/README.md) | Validate that multiple components function together across multiple interfaces in a call chain, incl network hops | [Integration testing](integration-testing/README.md); End-to-end ([End-to-End testing](e2e-testing/README.md)) tests; Segmented end-to-end ([End-to-End testing](e2e-testing/README.md)) |
+| Development | Validate that multiple components function together across multiple interfaces in a call chain, incl network hops | [Integration testing](integration-testing/README.md); End-to-end ([End-to-End testing](e2e-testing/README.md)) tests; Segmented end-to-end ([End-to-End testing](e2e-testing/README.md)) |
 | Development | Prove disaster recoverability – recover from corruption of data | DR drills |
-| Development | Find vulnerabilities in service Authentication or Authorization | Scenario (security) | | Development | Prove correct RBAC and claims interpretation of Authorization code | Scenario (security) | | Development                                                       | Document and/or enforce valid API usage | [Unit testing](unit-testing/README.md); Functional tests; [Consumer-driven Contract Testing](cdc-testing/README.md) |
+| Development | Find vulnerabilities in service Authentication or Authorization | Scenario (security) |
+| Development | Prove correct RBAC and claims interpretation of Authorization code | Scenario (security) |
+| Development | Document and/or enforce valid API usage | [Unit testing](unit-testing/README.md); Functional tests; [Consumer-driven Contract Testing](cdc-testing/README.md) |
 | Development | Prove implementation correctness in advance of a dependency or absent a dependency | [Unit testing](unit-testing/README.md) (with mocks); [Unit testing](unit-testing/README.md) (with emulators); [Consumer-driven Contract Testing](cdc-testing/README.md) |
-| Development | Ensure that the user interface is accessible | [Accessibility](../accessibility/README.md) |
+| Development | Ensure that the user interface is accessible | [Accessibility](../non-functional-requirements/accessibility.md) |
 | Development | Ensure that users can operate the interface | [UI testing (automated)](ui-testing/README.md) (human usability observation) |
 | Development | Prevent regression in user experience | UI automation; [End-to-End testing](e2e-testing/README.md) |
 | Development | Detect and prevent 'noisy neighbor' phenomena | [Load testing](performance-testing/load-testing.md) |
@@ -40,42 +80,9 @@ The table below maps outcomes -- the results that you may want to achieve in you
 | Staging; Operation | Measure behavior under rapid changes in traffic | Spike |
 | Staging; Optimizing | Discover cost metrics per unit load volume (what factors influence cost at what load points, e.g. cost per million concurrent users) | Load (stress) |
 | Development; Operation | Discover points where a system is not resilient to unpredictable yet inevitable failures (network outage, hardware failure, VM host servicing, rack/switch failures, random acts of the Malevolent Divine, solar flares, sharks that eat undersea cable relays, cosmic radiation, power outages, renegade backhoe operators, wolves chewing on junction boxes, …) | Chaos |
-| Development | Perform unit testing on Power platform custom connectors | [Custom Connector Testing](unit-testing/custom-connector.md)                                                                                                                                                                      |
-
-## Sections within Testing
-
-- [Consumer-driven contract (CDC) testing](cdc-testing/README.md)
-- [End-to-End testing](e2e-testing/README.md)
-- [Fault Injection testing](fault-injection-testing/README.md)
-- [Integration testing](integration-testing/README.md)
-- [Performance testing](performance-testing/README.md)
-- [Shadow testing](shadow-testing/README.md)
-- [Smoke testing](smoke-testing/README.md)
-- [Synthetic Transaction testing](synthetic-monitoring-tests/README.md)
-- [UI testing](ui-testing/README.md)
-- [Unit testing](unit-testing/README.md)
+| Development | Perform unit testing on Power platform custom connectors | [Custom Connector Testing](unit-testing/custom-connector.md) |
 
 ## Technology Specific Testing
 
-- [Using DevTest Pattern for building containers with AzDO](tech-specific-samples/azdo-container-dev-test-release/README.md)
+- [Using DevTest Pattern for building containers with AzDO](tech-specific-samples/building-containers-with-azure-devops.md)
 - [Using Azurite to run blob storage tests in pipeline](tech-specific-samples/blobstorage-unit-tests/README.md)
-
-## Build for Testing
-
-Testing is a critical part of the development process.  It is important to build your application with testing in mind.  Here are some tips to help you build for testing:
-
-- **Parameterize everything.** Rather than hard-code any variables, consider making everything a configurable parameter with a reasonable default. This will allow you to easily change the behavior of your application during testing. Particularly during performance testing, it is common to test different values to see what impact that has on performance. If a range of defaults need to change together, consider one or more parameters which set "modes", changing the defaults of a group of parameters together.
-
-- **Document at startup.** When your application starts up, it should log all parameters. This ensures the person reviewing the logs and application behavior know exactly how the application is configured.
-
-- **Log to console.** Logging to external systems like Azure Monitor is desirable for traceability across services. This requires logs to be dispatched from the local system to the external system and that is a dependency that can fail. It is important that someone be able to console logs directly on the local system.
-
-- **Log to external system.** In addition to console logs, logging to an external system like Azure Monitor is desirable for traceability across services and durability of logs.
-
-- **Log all activity.** If the system is performing some activity (reading data from a database, calling an external service, etc.), it should log that activity. Ideally, there should be a log message saying the activity is starting and another log message saying the activity is complete. This allows someone reviewing the logs to understand what the application is doing and how long it is taking. Depending on how noisy this is, different messages can be associated with different log levels, but it is important to have the information available when it comes to debugging a deployed system.
-
-- **Correlate distributed activities.** If the system is performing some activity that is distributed across multiple systems, it is important to correlate the activity across those systems. This can be done using a Correlation ID that is passed from system to system. This allows someone reviewing the logs to understand the entire flow of activity. For more information, please see [Observability in Microservices](../observability/microservices.md).
-
-- **Log metadata.** When logging, it is important to include metadata that is relevant to the activity. For example, a Tenant ID, Customer ID, or Order ID. This allows someone reviewing the logs to understand the context of the activity and filter to a manageable set of logs.
-
-- **Log performance metrics.** Even if you are using App Insights to capture how long dependency calls are taking, it is often useful to know long certain functions of your application took. It then becomes possible to evaluate the performance characteristics of your application as it is deployed on different compute platforms with different limitations on CPU, memory, and network bandwidth. For more information, please see [Metrics](../observability/pillars/metrics.md).

docs/automated-testing/integration-testing/README.md

@@ -12,7 +12,7 @@ Consider a banking application with three modules: login, transfers, and current
 
 Integration testing is done by the developer or QA tester. In the past, integration testing always happened after unit and before system and E2E testing. Compared to unit-tests, integration tests are fewer in quantity, usually run slower, and are more expensive to set up and develop. Now, if a team is following agile principles, integration tests can be performed before or after unit tests, early and often, as there is no need to wait for sequential processes. Additionally, integration tests can utilize mock data in order to simulate a complete system. There is an abundance of language-specific testing frameworks that can be used throughout the entire development lifecycle.
 
-\*\* It is important to note the difference between integration and acceptance testing. Integration testing confirms a group of components work together as intended from a technical perspective, while acceptance testing confirms a group of components work together as intended from a business scenario.
+> It is important to note the difference between integration and acceptance testing. Integration testing confirms a group of components work together as intended from a technical perspective, while acceptance testing confirms a group of components work together as intended from a business scenario.
 
 ## Applying Integration Testing
 

docs/automated-testing/performance-testing/README.md

@@ -38,7 +38,7 @@ following:
     the cost of running the hardware and software infrastructure.
 
 - Assess the **system's readiness** for release:
-  
+
   - Evaluating the system's performance characteristics (response time, throughput)
   in a production-like environment.
   The goal is to ensure that performance goals can be achieved upon release.
@@ -49,7 +49,7 @@ following:
     to the values of performance characteristics during previous runs (or
     baseline values), can provide an indication of performance issues (performance regression) or
     enhancements introduced due to a change
-  
+
 ## Key Performance Testing categories
 
 Performance testing is a broad topic. There are many areas where you can perform

docs/automated-testing/performance-testing/iterative-perf-test-template.md

@@ -26,7 +26,7 @@
 ### Results
 
 ```md
-In bullet points document the results from the test.  
+In bullet points document the results from the test.
 - Attach any documents supporting the test results.
 - Add links to the dashboard for metrics and logs such as Application Insights.
 - Capture screenshots for metrics and include it in the results. Good candidate for this is CPU/Memory/Disk usage.