phosphor-host-ipmid/docs/testing.md

7 of your machine setup. It also offers a strong guarantee that you're testing the
25 You'll want a couple of different repositories, so start by making a place for
36 We also need to put a copy of the project you want to test against here. But
37 you've probably got a copy checked out already, so we're going to make a _git
38 worktree_. You can read more about those by running `git help worktree`, but the
41 protects you from checking out the same branch in two places.
43 Your new worktree doesn't know about any untracked files you have in your main
44 worktree, so you should get in the habit of committing everything you want to
46 `run-unit-test-docker.sh`, you can't run the CI with untracked changes anyways,
47 so this isn't the worst thing in the world. (If you make untracked changes in
58 Now, if you `cd /path/to/openbmc-ci-tests`, you should see a directory
59 `phosphor-host-ipmid/`, and if you enter it and run `git status` you will see
60 that you're likely on a new branch named `phosphor-host-ipmid`. This is just for
61 convenience, since you can't check out a branch in your worktree that's already
62 checked out somewhere else; you can safely ignore or delete that branch later.
79 Then commit this, so you can make sure not to lose it if you update the scripts
91 You can create a local upstream:
103 This method would require you to push your topic branch to `ci` and then
104 `git checkout` the appropriate branch every time you switched topics:
114 You can also create a symlink from your Git workspace into `openbmc-ci-tests/`.
115 This is especially not recommended, since you won't be able to work on your code
116 in parallel while the tests run, and since the CI scripts are unhappy when you
117 have untracked changes - which you're likely to have during active development.
121 The OpenBMC CI scripts take care of the build for you, and run the test suite.
136 printed to `stdout`. You will also see other `.log` files generated for each
142 Now that you've got an easy working environment for running tests, let's write
155 checks out that branch for you to start hacking.
202 First, include the header you want to test, as well as the GTest header:
256 tutorial like this; in practice, tests you write will likely be for more
323 Finally, we'll need to add the new tests to `test/Makefile.am`. You can mimic
350 Commit your test changes. Then, you'll want to checkout the
358 git checkout master   # Here you can use any branch except sensorhandler-tests
363 Now you can run the test suite as described earlier in the document. If you see
364 a linter error when you run, you can actually apply the cleaned-up code easily:
373 (If you will need to apply the proposed changes to multiple commits, you can do
388 Keep your tests small. Avoid branching - if you feel a desire to, instead
392 When a test fails, it's useful if the test is named in such a way that you can
393 tell _what it's supposed to do_ and _when_. That way you can be certain whether
394 the change you made really broke it or not. A good pattern is
401 code under test. For example, don't test what happens if you give a bad input to
402 `sdbusplus` when you're supposed to be testing `phosphor-host-ipmid`.
404 However, don't trust other people's code, either! Try to test _how you respond_
406 bad inputs, check whether you handle an `sdbusplus` failure gracefully. You can
409 Think about testing when you write your business logic code. Concepts like
410 dependency injection and small functions make your code more testable - you'll
411 be thanking yourself later when you're writing tests.
413 Finally, you're very likely to find bugs while writing tests, especially if it's
415 along with a test that verifies the fix worked, if you're only doing one test
416 and one bugfix. If you're checking in a large suite of tests, do the bugfixes in
423 You can send your test update and any associated bugfixes for review to Gerrit
424 as you would send any other change. For the `Tested:` field in the commit
425 message, you can state that you ran the new unit tests written.
429 Tests are written primarily to be read. So when you review a test, you're the
434 First, all the best practices listed above for writing tests are things you
435 should check for and encourage when you're reading tests.
437 Next, you should ensure that you can tell what's going on when you read the
438 test. If it's not clear to you, it's not going to be clear to someone else, and
441 Finally, think about what's _not_ being tested. If there's a case you're curious
442 about and it isn't covered, you should mention it to the committer.
446 Now that you've got a handy setup as described earlier in this document, you can
447 quickly download and run the tests yourself. Within the Gerrit change, you
448 should be able to find a button that says "Download", which will give you
459 worktree into detached-HEAD mode pointing to the commit that's under review. You
467 - The committer doesn't have "Ok-To-Test" permission, and you don't have