add outside-in to testing principles

Author: lundybernard

docs/pages/principles/testing.md

@@ -10,11 +10,100 @@ parent: Principles
 
 # Testing recommendations
 
-## Outside-In Tests
-* live outside of source code, in the tests/ directory
-* Describe the various types of outsid-in tests (integration, fuzz, e2e, API)
-* Reference topical guides
-* Provide suggestions for testing categories
+## External or outside-in testing
+A good place to start writing tests is from the perspective of a user of your module
+or library, as described in the [Test Tutorial][], and [Testing with pytest guide][].
+These test cases live outside your code, and include many styles or types of test
+that you may have heard of (behavioral, fuzz, end-to-end, feature, etc., etc.).
+There are many, many kinds of tests that can be used to verify that your code is correct,
+and works as expected, and a lot to learn.
+
+### Any test case, is better than none
+When in doubt, write the test that makes sense to you at the time. While you are learning,
+and writing your first test suites, try not to get bogged down in the taxonomy of test cases.
+As you write and use your test suite, the reason for classifying and sorting some types
+of tests into different test-suites will become apparent.
+
+### As long as that test is correct...
+It can be surprisingly easy to write a test that passes when it should fail, especially
+when using complicated Mocks and fixtures. The best way to avoid this is to deliberately
+break the code you are testing, hard-code a failure, and run the test-case to make sure
+it fails when the code is broken.
+
+* Check that your test fails when it should!
+* Keep It Simple: Excessive use of mocks and fixtures can make it difficult to know if our
+  test is running the code we expect it to.
+* Test one thing at a time: A single test, should test a single behavior, and it is better
+  to write many test cases for a single function or class, than one giant case.
+
+
+{: .highlight-title }
+> A note to new test developers:
+>
+> This is a good place to pause and go write some tests.
+> The rest of these principles apply to more advanced test development.
+> As you gain experience and your test suite(s) grow, taxonomy of test cases,
+> the and the use/need for different kinds of tests will become more clear.
+
+
+### Taxonomy of outside-in tests
+A non-exhaustive discussion of some common types of tests.
+
+^_^ Dont Panic ^_^
+
+Depending on your project, you may not need many, or most of these kinds of tests.
+* A library project probably does not need to test integration with microservices.
+* A library with no 3rd party dependencies, does not need test them.
+* Fuzz testing is for critical code, that many users rely on.
+
+#### Behavioral, Feature, or Functional Tests:
+High-level tests, which ensure a specific feature works.
+Used for testing things like:
+* Loading a file
+* Setting a debug flag results in debug messages being printed
+* A configuration option, affects the behavior of the code as expected.
+
+
+#### Fuzz Tests
+Fuzz tests, attempt to test the full range of possible inputs to a function.
+They are good for finding edge-cases, where what should be valid input causes a failure.
+[Hypothesis](https://hypothesis.readthedocs.io/en/latest/) is an excellent tool for this, 
+and a lot of fun to use.
+
+* SLOW TESTS: fuzz tests can take a very long time to run,
+  and should usually be placed in a test suite, which we run seperately from our faster tests.
+* Reserve fuzz testing for the few critical functions, where it really matters.
+
+
+#### Integration Tests
+The word "Integration" is a bit overloaded, and can reffer to many levels of integration between
+our code, its dependencies, and external systems.
+
+##### Code level
+Test the integration between your software and external / 3rd party dependencies.
+Low-level testing of your code-base, where we run the code imported from dependencies,
+without mocking it.
+
+##### Environment level
+Testing that your software works in the environments we plan to run it in.
+* Running inside of a docker container
+* Using GPU's or other specialized hardware
+* Deploying it to cloud servers
+
+##### System level
+Testing that it interacts with other software in a larger system.
+* Interactions with other services, on local or cloud-based platforms.
+* micro-service, Database, or API connections and interactions.
+
+
+#### End to End Tests
+The slowest, and most brittle, of all tests. Here, we setup an entire production-like system,
+and run tests against it.
+* Create a Dev / Testing / staging environment, and run tests against it to make sure everything
+  works together.
+* Fake user input, using tools like [Selenium](https://www.selenium.dev/documentation/)
+* Processing data from a pre-loaded test database.
+* Manual QA testing
 
 
 ## Unit Tests