Test-driven onboarding: How to get up to speed in a new job

Test-driven onboarding: How to get up to speed in a new job


Write a test. Get it merged. Deploy it to production.


Welcome to X Ltd! We're really pleased you could join us. Your first day will start by meeting your manager, getting a tour of the (virtual) office and heading to lunch. Your afternoon will be filled with presentations about the company's history, how to check your payslips and how to book time off. Don't forget to do your online GDPR training!

The following days usually involve meeting the team, getting invited to team ceremonies you can't make much of a contribution to, and setting up your laptop.

These things can be important, but more than once have I been left with the question "...but when will I be useful? When can I write some code?"

(If you're reading this and it's your first day in a software engineering job ever, relax - no-one is expected to actually get up to speed properly for months, possibly even up to a year if you're totally fresh out of a bootcamp or a degree.)

My own motivation to write this was a sense that my own onboarding was lacking in hindsight, due to some unique circumstances at the time. I'd managed to avoid having to work on one particular codebase for over a year, and then suddenly my project depended on me reworking a feature in it. I went from feeling like a great technical leader to feeling like I knew nothing.

Writing a test

Once you have written a test, you'll have demonstrated a few things:

  • You can check out the code and run both the application and the tests - that your dev environment is setup correctly.
  • You understand the "business" problem that your test was covering
  • You have a feel for the testing strategy - at least for this codebase.
  • If it's your first exposure to a particular language or framework, that you understand the basics enough to learn-by-doing.

What type of test - a unit, integration or end-to-end test - isn't too important. What you're asserting is - preferably it covers some aspect of the business logic. A test that adds to code coverage but not actually testing something isn't useful.

Thankfully, very few codebases have 100% test coverage - there's normally something that was missed or some code that was hastily written in the past. An easy way to spot something useful to test is to look for an untested branch - some "if" condition that the tests don't execute.

Getting it merged

Getting it merged sounds like the easy bit but it can be the hardest. Getting a change merged demonstrates:

  • You understand the code review process, if there is one.
  • You understand the version control process.
  • You're familiar with the styling, idioms and some patterns in this codebase or language

There's very rarely one standard that everyone follows, even within the same company. The habits you might have from a previous job might have to be unlearned, and try not to jump to conclusions.

Even if getting it merged turns out be far more arduous than your last job, try to reserve judgement. It's important to understand how it currently works and the motivation behind the approach before you can make reasonable arguments in favour of changing it. Maybe your team is cautious because they've used up their error budget after a lot of downtime earlier in the year, or maybe moving fast and breaking things is their style because they need to experiment quickly to improve their product-market fit.

Going through this process is a great way to get to know your colleagues a bit better too - if someone has some code-review comments that don't make sense to you, ask them if they can spare a few minutes to explain face to face (admittedly, video call is best at the moment!). This is always advisable for large or unclear code-reviews, but particularly useful to do early.

Deploying it to production

If it's just a test, why do you need to deploy it to production? Deploying to production demonstrates:

  • You can deliver value to the customer - the most valuable code is what is in production!
  • You know about any testing environments that exist before production and how they might be different
  • You're familiar with any CI/CD processes and tooling your company has

Deploying to production might be full of little gotchas - flaky end to end tests, manual steps, cache-invalidations - it's good to know about any and all of these.

You want to know what is deployed - is it a Docker image? Zipped up lambda code?

You want to know how it gets there - is it all managed by a platform like Vercel? How do you manage supporting infrastructure like databases? Terraform? Kubernetes? Is it all in the cloud or is there company infrastructure somewhere? How often is it released? When you merge, or at the end of a sprint?

How do you know your deployment was successful? Are there alarms, metrics or logs you should keep an eye on?

That's a lot of questions but the good news is being as hands on as possible is the quickest way to figuring it out. If your production deployments are managed by an Ops team or QA Engineers, ask if you can watch them do the release.

Practical advice

Advice for individuals

Hopefully the previous sections have covered why I think this is a good way of onboarding yourself into a codebase but there's some meta-level suggestions I have too.

Announce your intentions to your manager and team. You might find there's plenty of new colleagues that would love to pair with you and walk you through this process. Better yet, there may be a small piece of work of real value you can pair on together. It's a great opportunity for them to develop their coaching and mentoring skills too, so don't be afraid to ask for help.

Besides this process, ask your team or manager if there's anything else you should be doing too. Writing code isn't the only way to be a valued team member. The point of this article is to minimise surprises for yourself in the future. If you're suffering from impostor syndrome, I think it's a great way to develop some practical confidence.

Advice for teams and organisations

Measure how long it takes a new joiner to deploy code to production. Track it and try to improve this.

Set realistic expectations with new joiners. If your onboarding process sucks, let them know that you value their feedback. Let them know how long you think it will take them to be productive. This isn't a euphemism for pressuring them to deliver something by a date, which could easily be counter-productive.

Encourage engineers to take an active part in the onboarding process. One thing that has worked great for me in the past was to ask the person that most recently joined to pair with the newest person.

Write your onboarding guide down - it should be a living document that anyone can contribute to.

I'd love to know how you do onboarding and any good or bad experiences you might have had. You can find me on Twitter as @lewisgj, or email me at (my Twitter handle)@hey.com .