Best practices for testing (#997)

* added best practices * fix broken links * fix broken links * removed extra space * added content from review --------- Co-authored-by: Tess Ferrandez <[email protected]> Co-authored-by: Tess Ferrandez <[email protected]> Co-authored-by: Shiran Rubin <[email protected]>
microsoft · Nov 15, 2023 · 3be466e · 3be466e
1 parent 7c075aa
commit 3be466e
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 0 deletions.
diff --git a/docs/automated-testing/README.md b/docs/automated-testing/README.md
@@ -59,3 +59,23 @@ The table below maps outcomes -- the results that you may want to achieve in you
 
 - [Using DevTest Pattern for building containers with AzDO](tech-specific-samples/azdo-container-dev-test-release)
 - [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, pelase see [Metrics](../observability/pillars/metrics.md).
diff --git a/docs/automated-testing/performance-testing/README.md b/docs/automated-testing/performance-testing/README.md
@@ -93,6 +93,22 @@ Developers often implement fallback procedures for service failure. Chaos
 testing arbitrarily shuts down different parts of the system to validate that
 fallback procedures function correctly.
 
+## Best practices
+
+Consider the following best practices for performance testing:
+
+- **Make one change at a time.** Don't make multiple changes to the system
+  between tests. If you do, you won't know which change caused the performance
+  to improve or degrade.
+
+- **Automate testing.** Strive to automate the setup and teardown of resources
+  for a performance run as much as possible. Manual execution can lead to
+  misconfigurations.
+
+- **Use different IP addresses.** Some systems will throttle requests from a
+  single IP address. If you are testing a system that has this type of
+  restriction, you can use different IP addresses to simulate multiple users.
+
 ## Performance monitor metrics
 
 When executing the various types of testing approaches, whether it is stress,